@bigbinary/neeto-form-frontend

@bigbinary/neeto-form-frontend

neetoFormEngine-frontend is the library that manages forms across neeto products.

Installation

yarn add @bigbinary/neeto-form-frontend

neetoFormEngine-frontend 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/neetoui @bigbinary/neeto-icons ramda@^0.28.0 classnames@^2.3.1 formik@2.2.9 @bigbinary/neeto-commons-frontend

Import stylesheet from the following location:

@import "@bigbinary/neeto-form-frontend/dist/main.css";

This package relies on the host project's tailwind configuration. So add neeto-form-frontend to your project's tailwind.config.js file:

module.exports = {
  purge: {
    content: [
      // ... other content directories
      "./node_modules/@bigbinary/neeto-form-frontend/**/*.js",
    ],
  },
  // ... other tailwind config options
};

Add NeetoFormProvider to the root of your application:

import React from "react";

import { NeetoFormProvider } from "@bigbinary/neeto-form-frontend";

const App = () => {
  return (
    <>
      <NeetoFormProvider>{/* Other children */}</NeetoFormProvider>
    </>
  );
};

Components

BuildForm component is used to render a form builder.

import { BuildForm } from "@bigbinary/neeto-form-frontend";

prop	type	description
id	string	Form id
onUpdate	function	Callback for form update
buildRequestArgs	object	Arguments for build request
showAddQuestionDivider	boolean	To show add question divider
nonRemovableFields	string[]	Field kinds that cant be deleted from a form. Accepts array of kinds: name, email, phone, rating, checkbox, dropdown
submitButtonProps	object	Props for submit button
cancelButtonProps	object	Props for cancel button
requiredFields	string[]	Fields that are required. Provided fields will be treated as required by default in the External form, the checkbox for toggling required will be hidden for the fields. Accepts array of kinds: name, email, phone, rating, checkbox, dropdown
questionKinds	object[]	To override default question kinds
isKindAlreadyActive	function	To override the logic for equality checking of question kinds. The function will receive activeQuestions and kind as arguments
getActiveKindDetails	function	To override the logic for extracting the details of the specified item. The function will receive allQuestionKinds and item as arguments and returns kind, label, FieldComponent, FieldIcon and isSingular props for the specified item
showLoader	boolean	To specify whether we need to show a page loader while loading questions. If specified as true a page loader will be displayed otherwise placeholder data will be shown while loading questions. The default value will be false
kindUniqueOn	string[]	To specify the prop used for uniquely identifying each question kind. Accepts the path of the prop as a string[]. The default value will be ["type"]
isFieldRequired	(item: Item) => boolean;	To specify whether a question is required or not. The function will receive item as an argument and returns a boolean value. Fields that return true will be treated as required by default in the External form
isFieldLabelDisabled	(item: Item) => boolean;	To specify whether a question label input is disabled or not. The function will receive item as an argument and returns a boolean value.
isQuestionDeletable	(item: Item) => boolean;	To specify whether a question is deletable or not. The function will receive item as an argument and returns a boolean value. Fields that return true cannot be removed from a form.
allowAdditionalGuests	boolean	To specify whether we need to allow additional guests input field in the form. If specified as true a checkbox will be displayed in the form to allow additional guests. The default value will be false. (neetoCal specific)

ExternalForm component is used to render a form.

import { ExternalForm } from "@bigbinary/neeto-form-frontend";

prop	type	description
formId	string	Form id
customSubmitHandler	function	Custom submit handler to be called instead of internal submit handlers
onBeforeSubmit	(responses, formikValues) => updatedResponses	Callback for before form submit, if the form responses needs to be updated, return the updated responses from this callback. The updated responses will be sent to the server. If the callback doesn't return anythong or returns a falsy value, the form will submit with the original responses.
onCreateSuccess	function	Callback for form creation success
showTitle	boolean	To show form title
submitRequestArgs	object	Arguments for form submit request payload
footer	React.Component	To render a Footer Component
submitButtonProps	object	Props for submit button
cancelButtonProps	object	Props for cancel button
resetButtonProps	object	Props for reset button
showPrefixIcons	boolean	To show prefix icons in input fields
displayThankYou	boolean	To show thank you message after form submit
className	string	To apply custom class to the form wrapper
submissionId	string	To set submission id for updating the form
preview	boolean	To show form in preview mode
preserveValues	boolean	To preserve form values in localStorage
formTitle	string	To set form title
titleProps	object	To set props for form title
clearValuesOnSubmit	boolean	To clear local storage values on submit
clearValuesOnReset	boolean	To clear local storage values on reset
formDomProps	object	To set props for form element
initialValues	object	To set initial values for form
editorProps	object	To set neetoEditor props for rich_text input field
onChange	function	Callback for form field values change
customValidator	(question) => Yup.Schema or null	Custom validator for form fields, it should return an yup validation schema based on the question proeprties. To make use of the default validation for a question type, return null

Submission component is used to render a form result.

import { Submission } from "@bigbinary/neeto-form-frontend";

prop	type	description
formId	string	Form id
submissionId	string	Submission id
className	string	To apply custom class component wrapper
questionLabelProps	object	To override props for question label
answerProps	object	To override props for answer text

Fields component provides access to all the components used in building forms.

import { Fields } from "@bigbinary/neeto-form-frontend";

const {
  Email,
  Dropdown,
  ShortText,
  LongText,
  MultipleChoice,
  SingleChoice,
  Phone,
  Rating,
  Terms,
  StarRating,
} = Fields;

Following components are currently available:

• Email
• Dropdown
• ShortText
• LongText
• MultipleChoice
• SingleChoice
• Phone
• Rating
• Terms
• StarRating
• Additional guests (neetoCal specific)
• Condition

Hooks

useBuildFormState hook is used to get the form state.

import { useBuildFormState, BuildForm } from "@bigbinary/neeto-form-frontend";

const FormBuilder = () => {
  const {
    values,
    dirty,
    isSubmitting,
    isValid,
    submitForm,
    resetForm,
    errors,
  } = useBuildFormState();

  return <BuildForm />;
};

useFormSubmission hook is used to fetch the form submission data.

import { useFormSubmission } from "@bigbinary/neeto-form-frontend";

const Component = () => {
  const { submission, isLoading } = useFormSubmission({
    formId: "form-id",
    submissionId: "submission-id",
  });

  return <></>;
};

useForms hook is used to fetch all the forms.

useForm hook is used to fetch all details of a form.

useCreateForm hooks is used to create a form.

useUpdateForm hooks is used to update a form.

useDeleteForm hooks is used to delete a form.

The usage is as follows.

import {
  useForm,
  useForm,
  useCreateForm,
  useUpdateForm,
  useDeleteForm,
} from "@bigbinary/neeto-form-frontend";

const Component = () => {
  const { data: forms, isLoading } = useForms();
  const { data: form, isLoading } = useForm({ formId: "form-id" });

  const { mutate: createForm, isLoading } = useCreateForm();
  createForm(payload);

  const { mutate: updateForm, isLoading } = useUpdateForm();
  updateForm({ id: "form-id", values: payload });

  const { mutate: deleteForm, isLoading } = useDeleteForm();
  deleteForm("form-id");

  return <></>;
};

useCreate, useUpdate & useDelete uses react-query's useMutation hook under the hood.

useForm & useForms uses react-query's useQuery hook under the hood.

We can pass in extra options supported by react-query to these hooks. We can also destructure all react-query supported props from the response.

Development

Install all the dependencies by executing the following command

yarn install

To test run and test the package locally, first configure neeto-form-engine in the host application.

Build the application locally:

yarn build

Use yalc to link the package locally.

Run yalc push on the package root directory.

Then run the below command on the host application root directory

yalc add @bigbinary/neeto-form-frontend

Building and releasing.

The @bigbinary/neeto-form-frontend package gets published to NPM when we merge a PR with patch, minor or major label to the main branch. The patch label is used for bug fixes, minor label is used for new features and major label is used for breaking changes. You can checkout the Create and publish releases workflow in GitHub Actions to get a live update.

In case if you missed to add the label, you can manually publish the package. For that first you need to create a PR to update the version number in the package.json file and merge it to the main branch. After merging the PR, you need to create a new github release from main branch. Whenever a new release is created with a new version number, the github actions will automatically publish the built package to npm. You can checkout the Publish to npm workflow in GitHub Actions to get a live update.

Please note that before publishing the package, you need to verify the functionality in some of the neeto web-apps locally using yalc package manager. The usage of yalc is explained in this video: https://youtu.be/QBiYGP0Rhe0

Used in

• neetoCal
• neetoCRM