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 => "/neeto_fields_engine"

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.

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).

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'.

    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"]}
     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,
       },
     }}
     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"]}
     resourceType="tasks"
     showOwnersInMenu
     fieldStatesTaxonomy={{ active: "Active", inactive: "Deactivated" }}
     paneProps={{
       children: <HostSpecificInputFields />,
       validations: {
         hostSpecificInputName: validationSchema,
       },
       initialValues: {
         hostSpecificInputName: initialValue,
       },
     }}
     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).

Usage

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

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

<FieldsPane
  isOpen={fieldPaneOpen}
  allowedKinds={["text", "number"]}
  resourceType="users"
  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. onMutationSuccess: The callback function which is triggered on the success of mutation functions( create, update & delete).
14. blockNavigation: Boolean value to specify whether to block the navigation if we have unsaved field values entered in field inputs.
15. blockNavigationAlertProps: Props to be passed to the Alert. It accepts the following.
    • title
    • message
    • submitButtonLabel
    • cancelButtonLabel

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"]})}
  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.

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) =>
  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}
      />
    ),
  }));

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

| Projects | Integrated | | ------------ | :----------------: | | neetoForm | :white_check_mark: | | neetoDesk | :white_check_mark: | | neetoPlanner | :white_check_mark: | | neetoCrm | :white_check_mark: | | neetoChat | :white_check_mark: | | neetoCal | :white_check_mark: | | neetoTestify | :white_check_mark: |