neeto-approvals-nano

The neeto-approvals-nano manages approvals within neeto applications. The nano exports the @bigbinary/neeto-approvals-frontend NPM package and neeto-approvals-engine Rails engine for development.

Contents

1. Development with Host Application
   • Engine
     • Installation
     • Usage
   • Frontend package
     • Installation
     • Instructions for development
     • Components
2. Instructions for Publishing

Development with Host Application

Engine

The engine is used to manage approval requests and approval templates for an organization.

Installation

1. Add this line to your application's Gemfile:

   source "NEETO_GEM_SERVER_URL" do
      # ..existing gems
   
      gem 'neeto-approvals-engine'
   end
   

2. And then execute:

   bundle install
   

3. Add this line to your application's config/routes.rb file:

   mount NeetoApprovalsEngine::Engine, at: "/neeto_approvals"
   

4. Run the following command to copy the migrations from the engine to the host application:

   bundle exec rails neeto_approvals_engine:install:migrations
   

5. Add the migrations to the database:

   bundle exec rails db:migrate
   

Usage

You can learn more about the setup and usage here:

1. Models
2. Controllers
3. Services

Frontend package

The package exports three components: Approvals, Form, and Public.

Installation

1. neeto-approvals-nano has a few peer dependencies that are required for the proper functioning of the package. Install all the peer dependencies using the below command:

   yarn add @bigbinary/[email protected] @bigbinary/[email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] @tanstack/[email protected] @tanstack/[email protected] [email protected]
   

2. Now install the latest neeto-approvals-nano package using the below command:

   yarn add @bigbinary/neeto-approvals-frontend
   

Instructions for development

Check the Frontend package development guide for step-by-step instructions to develop the frontend package.

Components

Approvals (source code)

This component manages approval requests, approval templates and history of approval requests. It consists of three tabs: Pending, Templates, and History

1. Pending - Lists all pending approval requests.
2. Templates - Lists all approval templates.
3. History - Lists all approved, rejected, and cancelled approval requests.

Props

• config: Configuration object that includes specifications for paths, URLs, template placeholders and breadcrumbs. It also allows optional configurations for help articles.

Configuration

Refer to the Approvals section for detailed information on the available configurations for the Approvals component.

Usage

import React from "react";

import { Approvals } from "@bigbinary/neeto-approvals-frontend";
import { routes } from "common/routes";
import { BrowserRouter, Redirect, Route, Switch } from "react-router-dom";
import { ToastContainer } from "react-toastify";

import SideBar from "./Common/SideBar";


const Main = () => (
  <BrowserRouter>
    <div className="flex">
      <SideBar />
      <Switch>
        <Route
          path={routes.approvals}
          render={() => (
            <Approvals
              config={APPROVALS_CONFIG}
            />
          )}
        />
      </Switch>
    </div>
    <ToastContainer />
  </BrowserRouter>
);

export default Main;

Form (source code)

This component handles creation and updation of approval templates.

Props

• isLoading - Boolean value to show the loading state in the submit button
• isOpen - Boolean value to open the pane
• setIsPaneOpen - Set it to false to close the pane
• requestableId - ID of the entity to which we are associating requests. This is used to parse messages based on the entity's attributes in the engine.
• onSubmit - Function which calls the API to submit approval request details such as request message, template title, approver ID and requestable ID.

Usage

import React from "react";
import { Form } from "@bigbinary/neeto-approvals-frontend";

const RequestApproval = () => {
  const { mutate: createRequest, isPending } = useCreateRequest();

  const onSubmit = (request, template, onClose) => {
    createRequest(
      {
        request: {
          ...request,
          title: template.name,
          approverId: template.approverId,
          requestableId: requestableId, // Specify the ID of the requestable associated entity
        },
      },
      { onSuccess: onClose }
    );
  };

  return (
    <Form
      isLoading={isPending}
      isOpen={isNewApprovalRequestPaneOpen}
      setIsPaneOpen={setIsNewApprovalRequestPaneOpen}
      requestableId={requestableId} // Specify the ID of the requestable associated entity
      onSubmit={onSubmit}
    />
  );
};

export default RequestApproval;

Public (source code)

This component is used to show the approval request detail without any user login.

Props

No props need to be passed. However, ensure that the path of the page rendering the Public component contains the id param for the request ID.

Usage

import React from "react";
import { Public } from "@bigbinary/neeto-approvals-frontend";

const PublicRequestApproval = () => {
  return (
    <Public />
  );
};

export default PublicRequestApproval;

Instructions for Publishing

Consult the building and releasing packages guide for details on how to publish.