@bigbinary/neeto-fields-frontend

neeto-fields-nano

neeto-fields-nano enables the management of dynamically added fields (often referred as custom fields) for the resources across neeto products.

Index

• General information
• Installation instructions
  • Engine Installation
  • Frontend package Installation
• Frontend package exports
  • Components
    • FieldsDashBoard
    • AddField
    • FieldValuesContainer
    • FieldInputs
  • Functions
    • mergeInitialValues
    • transformValues
  • Hooks
    • useFetchFields
• Customizability
  • Engine customizability
• Development instructions
  • Engine development
  • Frontend package development

General information

• This nano deals with fields and field values.

• Field has a name, kind, resource_type and owner.

• Field value has a field and resource item associated to it.

• resource_type is the type of resource for which we are creating the field. It is used for the categorized fetching and rendering of the fields. eg: users, tickets, deals, etc

• owner is basically scope of a field. It is whom to the field belongs. eg: Organization, Project, etc

• kind is the nature of the data meant as value for the field. All available kinds are:

  text, number, monetary, single_option, multi_option, date, time, date_range, time_range, text_area, person, checkbox, regex, integer, decimal, datetime.

Installation instructions

Engine 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. Add required migrations in the db/migrate folder. Run the following commands to generate the migrations.

rails g neeto_fields_engine:install

This will generate the migration to create the neeto_fields_engine_fields table (which holds the fields) and neeto_fields_engine_field_values table (which holds the value for the fields).

1. Run the following command to create the tables.

  rails db:migrate

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

• Owner: It is the ultimate owner of the fields being added. It can be Organization, Project, etc depending on the business logic. The field will belongs_to Owner.

• Resource: These are the models, to which we want the dynamic fields to be attached with. This case be anything like Ticket, Deal, etc depending on the business logic. The field_value belongs_to each Resource.

Once you enter the appropriate entries for the prompts asked. It will create an initializer file, which is required for the functioning of the engine.

It will also add necessary associations to respective models, which were considered as Owner and Resources.

Note: You might need to re-arrange the associations statements which are normally inserted to top most lines of the file, to satisfy the Rails standards.

Once you have completed these steps, you are ready to use the neeto-fields-engine.

Frontend package installation

Install the latest neetoFields nano package using the below command:

yarn add @bigbinary/neeto-fields-frontend

The frontend package exports 4 components, 2 utility functions and a hook.

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 children to be rendered inside the pane and validations for the formik input fields in the children. validations must be provided as a map with the field name as key and the corresponding yup validation schema as the value. initialValues must also be provided as a map with the field name as key and the corresponding value.
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.

Usage:

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",
    },
  ]}
/>;

When Organization is not owner of the fields. Lets say the owner is Project.

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

<FieldsDashboard
  allowedKinds={["text", "number"]}
  ownerId={projectId}
  resourceType="tasks"
  showOwnersInMenu
  fieldStatesTaxonomy={{ active: "Active", inactive: "Deactivated" }}
  paneProps={{
    children: <HostSpecificInputFields />,
    validations: {
      hostSpecificInputName: validationSchema,
    },
    initialValues: {
      hostSpecificInputName: initialValue,
    },
  }}
  breadcrumbs={[
    {
      link: "/",
      text: "Home",
    },
    {
      link: "/",
      text: "Settings",
    },
  ]}
/>;

2. AddField

The AddField component consists of a button and a pane that opens when the button is clicked.

Props:

1. resourceType: Specifies the resource_type of the field to be created via the pane.
2. allowedKinds: Specifies the list of field kinds allowed to be created.
3. children: Children components for the pane.
4. additionalValidations: Validations for the formik fields in children.
5. initialValues: Initial values for the formik fields in children.

Usage:

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

<AddField
  allowedKinds={["text", "number"]}
  resourceType="users"
  additionalValidations={{
    hostSpecificInputName: validationSchema,
  }}
  initialValues={{ hostSpecificInputName: initialValue }}
>
  <HostSpecificInputFields />
</AddField>;

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. resourceId: The ID of the resource.
4. ownerId:The ID of the owner. This prop is required only if the owner is not an organization.
5. queryKeysToBeInvalidatedOnSuccess: An array of queryKeys that should be invalidated when changing the field value.
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.

Usage:

Say the resource over here is a user.

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

<FieldValuesContainer
  fieldValues={user.fieldValues} // We expect the user response from host's backend to send associated field_values with it.
  queryKeysToBeInvalidatedOnSuccess={["users"]}
  resourceId={user?.id}
  resourceType="users"
  customComponents={{
    hostSpecificKindName: field => <HostSpecificInputFields />,
  }}
/>;

4. FieldInputs

The FieldInputs component render the input UI for the fetched fields. It accepts the following props:

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.

: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 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 fields={fields} />

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

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 },
} = useFetchFields({
  resourceType: "users",
  ownerId: "ownerId",
});

Customizability

Engine customizability

In order to customize the engine's default behavior, we have several ways.

• For improving the customizability, we've made every actions' duties into separate services, which can be overridden from the host apps as and when required.
• If you wish to perform anything before or after the core logic of an action, we have provision to do it as a single transaction.
• Every action has before_{action}_process method invoked before the core action logic and after_{action}_process method invoked after the core action logic.
• These methods can be overridden by defining them in the concern NeetoFieldsEngine::Fields::Customizable or NeetoFieldsEngine::FieldValues::Customizable depending on the context.

Eg: If you want to do something before update action of FieldsController, then define it in before_update_process method inside the NeetoFieldsEngine::Fields::Customizable concern.

Development instructions

Engine development

1. Add this line to your application's Gemfile (replace the path to the local copy of neeto-fields-engine):

   gem 'neeto-fields-engine', path: '../neeto-fields-engine'
   

2. And then execute:

   bundle install
   

3. Refer engine installation steps 3 and onwards.

Frontend package development

The usage of yalc is explained in this video: https://www.youtube.com/watch?v=QBiYGP0Rhe0

1. See the changes in the host app by executing the following command
   
   Use this command if releasing package for the first time.

   yarn build && yalc publish
   

   Use this command to see changes after the initial publish.

   yarn release
   

Setup dummy host app

Setup Instructions.

Visit http://spinkart.lvh.me:9100 and login with email [e-mail] and password welcome.

Additional instructions

• Run yarn build to bundle the app.

Read about building and releasing