neeto-fields-nano

The neeto-fields-nano enables the management of dynamically added fields (often referred to as custom fields) across neeto applications. The nano exports the @bigbinary/neeto-fields-frontend NPM package and neeto-fields-engine Rails engine for development.

Contents

1. Development with Host Application
   • Engine
     • Installation
     • customizability
   • Frontend package
     • Installation
     • Instructions for development
     • Components
       • FieldsDashBoard
       • FieldsPane
       • FieldValuesContainer
       • FieldInputs
       • InlineFieldValueInput
       • FieldDeleteAlert
     • Functions
       • mergeInitialValues
       • transformValues
     • Hooks
       • useFetchFields
       • useShowFields
       • useCreateField
       • useUpdateField
       • useDestroyField
2. Instructions for Publishing

Development with Host Application

Engine

The engine is used to manage fields for any entity across neeto products.

Installation

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

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

2. And then execute:

   bundle install
   

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

   mount NeetoFieldsEngine::Engine, at: "/neeto_fields"
   

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

   rails g neeto_fields_engine:install
   

5. Add the migrations to the database:

   bundle exec rails db:migrate
   

6. Generate the required associations between models using the following command:

   rails g neeto_fields_engine:associations
   

   This will prompt the user to enter 2 things:

   1. Name of Owner model.
   2. Names of Resource models.

   Explore Owner & Resource Information for details.

7. Add the required permissions to your permissions.yml file:

   • neeto_fields_engine.view_fields - Allows viewing fields
   • neeto_fields_engine.manage_fields - Allows creating, updating, deleting, and reordering fields
   • neeto_fields_engine.view_field_values - Allows viewing field values
   • neeto_fields_engine.manage_field_values - Allows creating, updating, and deleting field values

Supported Permissions

The engine provides granular permission control through the following permissions:

• neeto_fields_engine.view_fields - Allows users to view fields
• neeto_fields_engine.manage_fields - Allows users to create, update, delete, and reorder fields
• neeto_fields_engine.view_field_values - Allows users to view field values
• neeto_fields_engine.manage_field_values - Allows users to create, update, and delete field values

Policy Callbacks

The engine exposes the following policy methods through the FieldPolicy class:

• can_view_fields? - Checks if user can view fields
• can_manage_fields? - Checks if user can manage fields
• can_view_field_values? - Checks if user can view field values
• can_manage_field_values? - Checks if user can manage field values

These methods are automatically used by the controllers' authorization callbacks and can be overridden in host applications if needed.

Customizability

Refer Engine customizability to learn about customizing the engine's default behavior.

Frontend package

Installation

Install the latest neetoFields nano package using the below command:

yarn add @bigbinary/neeto-fields-frontend

Dependency

neeto-fields-nano has a peer dependency which is required to use the nano properly. Install the peer dependency using the below command:

yarn add uuid

Instructions for development

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

Components

1. FieldsDashboard

The FieldsDashboard component serves as a dashboard for managing all custom-field related operations. It functions without requiring any props by default, but you can customize its behavior by passing optional props.

Props

1. rowData: Represents the rowData for the table within the dashboard.

2. buildColumnData : A function that builds the column data (in neetoUI table format) for the dashboard table. This function gets the onDeleteClick, onEditClick callbacks and defaultColumns as arguments.

3. showOwnersInMenu: Accepts a boolean value. When set to true, the fields are displayed in categorized form (side menu) based on owners. By default, fields are categorized based on the resourceType.

4. resourceType: Explicitly specifies the resource_type of the fields to be shown in the dashboard table. This prop is expected when showOwnersInMenu is set to true.

5. allowedKinds:Specifies the list of field kinds allowed to be created.

6. paneProps: Props to be passed to the Add/Edit pane. It accepts the following.

   • children: The children components to be rendered inside the pane.
   • validations: The validations for the formik input fields in the children. validations must be provided as an object with the field name as key and the corresponding yup validation schema as the value.
   • initialValues: The initial values for the formik input fields in the children. It is provided as an object with the field name as key and the corresponding value.
   • hideRequiredSwitch: A boolean value when set to true hides the toggle switch for isRequried.
   • onMutationSuccess: Callback function which is triggered on the success of mutation functions (create, update & delete).
   • lookupOptions: Specifies the lookup resource types available for lookup fields.
   • allowSelectingAccessType: A boolean value (default false). When set to true, enables selecting field access type (everyone or restricted) and restricting field visibility to specific organization roles.

7. showStateFilter: Boolean value which specifies whether to show or hide state filters.

8. fieldStatesTaxonomy: Specifies the names to be rendered for active and inactive states.

9. breadcrumbs: Specifies the breadcrumbs to be displayed on the dashboard page.

10. helpDescription: To set the description of the popover, this can be a string or a custom component.

11. helpDocUrl: Specify the URL to the help documentation about fields. This URL will be shown in the NoData screen.

12. nameAliases: This property accepts alias names as key-value pairs to be displayed for the names of resource types in header and menubar.

13. headerTitle: Specify the header title explicitly. Default is 'fields'. It also specifies the title of HelpPopover.

14. resources: For owner-based field categorization, provide an array of objects with id and name properties for each owner. For resource type-based categorization, use an array of objects with label and value properties representing each resource types.

15. headerSize: To specify the header size explicitly. Default is 'small'.

16. canManageFields: Boolean value which overrides the default permission check for managing fields. When not provided, the component checks for neeto_fields_engine.manage_fields permission from global props.

17. onDeleteSuccess: Callback function which is triggered on the success of field deletion.

18. onReorderSuccess: Callback function which is triggered on the success of reordering of fields.

    If no resources are provided, for resource type-based categorization, the menu bar will fetch all resource types. For owner-based categorization, it will fetch and list all owners in the organization.

Usage

1. When Organization is the owner of the fields.

   import { FieldsDashboard } from "@bigbinary/neeto-fields-frontend";
   
   <FieldsDashboard
     allowedKinds={["text", "number", "lookup"]}
     buildColumnData={({ defaultColumns }) => [
       ...defaultColumns,
       {
         dataIndex: "isSystem",
         index: "isSystem",
         title: t("titles.systemField"),
         render: boolVal => (boolVal ? "Yes" : "No"),
       },
     ]}
     fieldStatesTaxonomy={{ active: "Active", inactive: "Deactivated" }}
     paneProps={{
       children: <HostSpecificInputFields />,
       validations: {
         hostSpecificInputName: validationSchema,
       },
       initialValues: {
         hostSpecificInputName: initialValue,
       },
        lookupOptions: [
        { label: "Contact", value: "contact" },
        { label: "Company", value: "company" },
        ],
     }}
     breadcrumbs={[
       {
         link: "/",
         text: "Home",
       },
       {
         link: "/",
         text: "Settings",
       },
     ]}
   />;
   

   Usage in neetoDesk

2. When Organization is not owner of the fields. Let's say the owner is Project.

   import { FieldsDashboard } from "@bigbinary/neeto-fields-frontend";
   
   <FieldsDashboard
     allowedKinds={["text", "number", "lookup"]}
     resourceType="tasks"
     showOwnersInMenu
     fieldStatesTaxonomy={{ active: "Active", inactive: "Deactivated" }}
     paneProps={{
       children: <HostSpecificInputFields />,
       validations: {
         hostSpecificInputName: validationSchema,
       },
       initialValues: {
         hostSpecificInputName: initialValue,
       },
       lookupOptions: [
        { label: "Contact", value: "contact" },
        { label: "Company", value: "company" },
        ],
     }}
     breadcrumbs={[
       {
         link: "/",
         text: "Home",
       },
       {
         link: "/",
         text: "Settings",
       },
     ]}
   />;
   

   Usage in neetoForm

2. FieldsPane

The FieldsPane component handles the Add / Edit operations of the field.

Props

1. isOpen: Boolean state which specifies the open/close state of the pane.
2. onClose: The function to be executed on closing the pane.
3. resourceType: Specifies the resource_type of the field to be created via the pane.
4. allowedKinds: Specifies the list of field kinds allowed to be created.
5. children: Children components for the pane.
6. additionalValidations: Validations for the formik fields in children.
7. initialValues: Initial values for the formik fields in children.
8. selectedField: The field object whose editing is concerned with. If this prop is given, the pane will act as an Edit pane. Else it act as Add pane.
9. hideRequiredSwitch: Specify whether to hide the Is required toggle switch for field in pane.
10. ownerId: The ID of the owner in case the owner is not an organization.
11. onMutationSuccess: The callback function which is triggered on the success of mutation functions( create, update & delete).
12. additionalPayload: For sending additional data in the field creation payload. This object will be merged with the base payload when creating a new field.
13. lookupOptions: Specifies the supported lookup resource types for lookup fields. This prop is required when lookup is included in allowedKinds.
14. allowSelectingAccessType: Boolean value (default false). When set to true, enables selecting field access type (everyone or restricted) and specifying restricted organization roles.

Usage

import { FieldsPane } from "@biginary/neeto-fields-frontend";

const [fieldPaneOpen, setFieldPaneOpen] = useState(false);

<FieldsPane
  isOpen={fieldPaneOpen}
  allowedKinds={["text", "number","lookup"]}
  resourceType="users"
  lookupOptions={[
    { label: "Contact", value: "contact" },
    { label: "Company", value: "company" }
  ]}
  additionalValidations={{
    hostSpecificInputName: validationSchema,
  }}
  initialValues={{ hostSpecificInputName: initialValue }}
  onClose={() => setFieldPaneOpen(false)}
>
  <HostSpecificInputFields />
</FieldsPane>;

3. FieldValuesContainer

The FieldValuesContainer component handles field values associated with a specific resource.

Props

1. resourceType: The type of resource.
2. fieldValues: Field values associated with the resource obtained from the response.
3. fields: Fields associated with resource type. This is an optional prop. If not provided the component will fetch the fields internally.
4. resourceId: The ID of the resource.
5. ownerId:The ID of the owner. This prop is required only if the owner is not an organization.
6. customComponents: If the host application has any extra kind other than the supported ones, you can specify the component to be displayed corresponding to that kind using this prop. It takes the kind name as the key and the component rendering callback function as the value. The callback function can expect the field object as argument.
7. className: Class names for styling.
8. showBorder: Boolean value to specify whether to show or hide borders. Default true.
9. formRefs: A React Ref object that can be used to access the Formik context of the forms corresponding to each field as key value pairs.
10. disabled: Boolean value to specify whether to disable all fields.
11. isRequiredColumnName: The name of column which holds the value which suggests if a field value is a required one or not. Default is isRequired column.
12. fieldClassName: Class names for styling the div containing the input field.
13. onMutate: The callback function which is triggered on the mutations.
14. onMutationSuccess: The callback function which is triggered on the success of mutation functions( create, update & delete).
15. blockNavigation: Boolean value to specify whether to block the navigation if we have unsaved field values entered in field inputs.
16. blockNavigationAlertProps: Props to be passed to the Alert. It accepts the following.
    • title
    • message
    • submitButtonLabel
    • cancelButtonLabel
17. canManageFieldValues: Boolean value which overrides the default permission check for managing field values. When not provided, the component checks for neeto_fields_engine.manage_field_values permission from global props.

Usage

Say the resource over here is a user.

import { FieldValuesContainer } from "@bigbinary/neeto-fields-frontend";

const formRefs = useRef({});
const queryClient = useQueryClient();

<FieldValuesContainer
  blockNavigation
  formRefs={formRefs}
  fieldValues={user.fieldValues} // We expect the user response from host's backend to send associated field_values with it.
  resourceId={user?.id}
  resourceType="users"
  onMutationSuccess={() =>
    queryClient.invalidateQueries({ queryKey: ["users"] })
  }
  onMutate={() => queryClient.setQueriesData({ queryKey: ["users"] }, modifier)}
  customComponents={{
    hostSpecificKindName: field => <HostSpecificInputFields />,
  }}
  blockNavigationProps={{
    title: "Changes not saved!",
    message: "You've not saved the changes made.",
  }}
/>;

4. FieldInputs

The FieldInputs component render the input UI for the fetched fields.

Props

1. fields: An array of all the fetched fields.
2. customComponents: If the host application has any extra kind other than the supported ones, you can specify the component to be displayed corresponding to that kind using this prop. It takes the kind name as the key and the component rendering callback function as the value. The callback function can expect the field object.
3. formRefs: A React Ref object that can be used to access the Formik context of the form.
4. disabled: Boolean value to specify whether to disable all fields.
5. isRequiredColumnName: The name of column which holds the value which suggests if a field value is a required one or not.

:memo: Note:

To initialize the values for this formik fields, you need to use mergeInitialValues function.

To submit the values from this formik form, you need to use transformValues function to capture the right data from neeto-fields.

Usage

import {
  FieldInputs,
  useFetchFields,
  neetoFieldsUtils,
} from "@bigbinary/neeto-fields-frontend";

const formRef = useRef();

const HostForm = () => {
  const {
    data: { fields },
  } = useFetchFields({
    resourceType: "users",
  });

  const initialValues = neetoFieldsUtils.mergeInitialValues({
    initialValues: INITIAL_VALUES,
    fields,
  });
  return (
    <Form
      formikProps={{
        initialValues,
        validationSchema: VALIDATION_SCHEMA,
        onSubmit: values =>
          onSubmit(neetoFieldsUtils.transformValues({ values, fields })),
        enableReinitialize: true,
      }}
    >
      {/* Other host specific input fields */}

      <FieldInputs formRef={formRef} fields={fields} />

      <Button type="submit" label="Submit" />
    </Form>
  );
};

5. InlineFieldValueInput

The InlineFieldValueInput component render the field value input UI.

Props

1. fields: An array of all the fetched fields.
2. fieldValues: Field values associated with the resource.
3. resourceType: The type of resource.
4. resourceId: The ID of the resource.
5. ownerId: The ID of the owner in case the owner is not an organization.
6. onMutate: The callback function which is triggered on the mutations
7. onMutationSuccess: The callback function which is triggered on the success of mutation functions of field value.
8. canManageFieldValues: Boolean value which overrides the default permission check for managing field values. When not provided, the component checks for neeto_fields_engine.manage_field_values permission from global props.

Usage

Usually this is used as a component for inline editing of field values in tables. The example shows one such usage of building the columnData for table with inline editable field value inputs in cell.

const buildColumnDataForFields = (
  fields,
  onFieldValueUpdateSuccess,
  canWriteForm
) =>
  fields.map(field => ({
    dataIndex: "field.id",
    key: field.id,
    title: field.name,
    width: 250,
    render: (_, user) => (
      <InlineFieldValueInput
        {...{ field }}
        fieldValues={user.fieldValues}
        resourceId={user.id}
        resourceType="users"
        onMutationSuccess={onFieldValueUpdateSuccess}
        canManageFieldValues={canWriteForm}
      />
    ),
  }));

6. FieldDeleteAlert

The FieldDeleteAlert component handles delete operation on fields. It accepts the following props:

Props

1. selectedField: The field that needs to be deleted.
2. ownerId: The ID of the owner in case the owner is not an organization.
3. resourceTypeName: The type of resource.
4. isDeleteAlertOpen: Boolean state which specifies whether the alert is open.
5. isDeleting: Boolean state indicating whether the field is being deleted.
6. handleDelete: The callback function responsible for deleting the specified field.
7. handleAlertClose: The callback function to be executed on closing the alert.

Usage

import { FieldDeleteAlert } from "@biginary/neeto-fields-frontend";

const [isDeleteAlertOpen, setIsDeleteAlertOpen] = useState(false);

<FieldDeleteAlert
  selectedField={field}
  ownerId={formId}
  resourceTypeName="submission"
  isDeleteAlertOpen={isDeleteAlertOpen}
  isDeleting={isDeleting}
  handleDelete={handleDelete}
  handleAlertClose={() => setIsDeleteAlertOpen(false)}
/>;

Functions

The package exports the neetoFieldsUtils, which contains two utility functions.

1. neetoFieldsUtils.mergeInitialValues

This function builds the initial values for the Formik form that wraps the <FieldInputs /> component.

Arguments

• initialValues: The initial value object without considering <FieldInputs />
• fields: An array of all the fetched fields.

Usage

import { useFetchFields } from "@bigbinary/neeto-fields-frontend";

const {
  data: { fields },
} = useFetchFields({ resourceType: "users" });

const initialValues = neetoFieldsUtils.mergeInitialValues({
  initialValues: FORMIK_INITIAL_VALUES,
  fields,
});

2. neetoFieldsUtils.transformValues

This function transforms the Formik form values and builds the values object including the data from <FieldInputs />. This transformed object can be passed to the onSubmit function of the Formik form.

Arguments

• values: The Formik form values.

Usage

import { useFetchFields } from "@bigbinary/neeto-fields-frontend";

const {
  data: { fields },
} = useFetchFields({ resourceType: "users" });

<Form
  formikProps={{
    initialValues,
    validationSchema: VALIDATION_SCHEMA,
    onSubmit: values =>
      onSubmit(neetoFieldsUtils.transformValues({ values, fields })),
    enableReinitialize: true,
  }}
>
  {/* Form's children */}
</Form>;

Hooks

1. useFetchFields

This is a React Query hook for fetching all the fields.

Arguments

• resourceType: The resource_type of the fields to be fetched.
• ownerId: The ID of the owner in case the owner is not an organization.

Usage

const {
  data: { fields, count, activeFieldsCount, inactiveFieldsCount },
} = useFetchFields({
  resourceType: "users",
  ownerId: "ownerId",
});

2. useShowField

This is a React Query hook for fetching details of a field.

Arguments

• fieldId: The ID of field for fetching details.
• ownerId: The ID of the owner in case the owner is not an organization.

Usage

const {
  data: { field },
} = useShowField({ fieldId, ownerId });

3. useCreateField

This is a React Query hook for creating a field.

Usage

const { mutate: create } = useCreateField();
const payload = {
  field: { name, kind, resourceType, ownerId, displayOrder, data },
};
create(payload);

4. useUpdateField

This is a React Query hook for updating a field.

Usage

const { mutate: update } = useUpdateField();
const payload = {
  field: { name, kind, resourceType, ownerId, displayOrder, data },
};
update({ fieldId, payload });

5. useDestroyField

This is a React Query hook for deleting a field.

Usage

const { mutate: delete } = useDestroyField();
delete({ fieldId })

Pass the ownerId too with the payload in case the owner is not an organization.

Instructions for Publishing

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

Integrations