Sierra Labs Forms UI

Sierra Labs Forms React UI Library for managing form schemas, form templates, and form data capture.

Getting Started

Install the @sierralabs/forms-ui package along with peer dependencies

# for npm
$ npm install @sierralabs/core @sierralabs/forms-core @sierralabs/track-changes @sierralabs/state-machine @sierralabs/react-material-ui @sierralabs/react-material-ui-formik @sierralabs/forms-ui

# or for yarn
$ yarn add @sierralabs/core @sierralabs/forms-core @sierralabs/track-changes @sierralabs/state-machine @sierralabs/react-material-ui @sierralabs/react-material-ui-formik @sierralabs/forms-ui

# forms-ui is also dependent on react, material-ui, date-fns, js-cookie, styled-components, formik, yup, use-query-arams, react-router-dom, react-number-format, @tinymce/tinymce-react, react-beautiful-dnd

$ yarn add @material-ui/core @material-ui/icons @material-ui/lab @material-ui/pickers @tinymce/tinymce-react date-fns formik js-cookie react-beautiful-dnd react-number-format react-router-dom styled-components use-query-params yup # or npm install

Form Schema and Template Editors

Add the following Routes to your project for the form schema and form template editors. These components integrate with the @sierralabs/forms-api provided endpoints.

<Switch>
  <Route
    exact
    path='/portal/admin/form-templates'
    component={FormTemplateListPage}
  />
  <Route
    path='/portal/admin/form-templates/:formTemplateId'
    component={FormTemplateDetailPage}
  />
</Switch>

Form Component

You can integrate the Form component into your project and build custom logic around handling of form data captured through the UI.

const CustomForm: React.FC = () => {
  // Pass in the form Entity Schema JSON definiition
  const entitySchema = {...};
  // Pass in the form template JSON definition
  const formStateNode = {...};
  return (
    <FormProvider
      entitySchema={entitySchema}
      formStateNode={formStateNode}
      onChange={values => {
        /* when form data is entered `values` contains the user data */
      }}
    >
      // Render the form UI
      <Form />
    </FormProvider>
  )
};

TODO: Document Form component configurations (i.e. appendSectionControls, etc.)

Form Hooks

The following are Form related hooks to interface with the @sierralabs/forms-api:

• useFindFormSchemas - Get a list of form schemas
• useFindFormSchemaDeltas - Get history of form schema changes
• useApplyFormSchemaDelta - Apply a change to the form schema
• useCreateFormTemplate- Create a form template
• useUpdateFormTemplate - Update a form template
• useUpdateFormTemplateConfig - Updating a Form Template config
• usePublishFormTemplate - Publish a form template version
• useFindFormTemplates - Get a list of form templates
• useFindFormTemplate - Get a single form template and its config
• useGetFormTemplateVersions - Get all published versions for a form template

Development & Contributing

For fast development leveraging React's fast refresh capabilities you can develop using the forms-ui-example project located in the "examples" folder.

# Start the @sierralabs/forms-ui in watch mode
forms-ui $ yarn start

# Start the forms example project
forms-ui-example $ yarn start

# Now all changes in @sierralabs/forms-ui will get automatically compiled and leverage React's fast browser refresh capabilities.

Development from an outside project

To develop and contribute to the @sierralabs/forms-ui project from another project that has a dependency on this module you can use Yalc. Yalc works better then yarn/npm link due to node_module dependency issues with symlinking that impact modules like react.

# Install yalc if you don't already have it installed
$ npm install -g yalc

# Publish `@sierralabs/forms-ui` into your local yalc repo
$ yalc publish

# On the project that is using `@sierralabs/forms-api` run
dependent-project $ yalc link @sierralabs/forms-api

# Now back on the `@sierralabs/forms-ui` folder you can make code changes and push changes to the linked projects by
$ yalc push

# Lastly, to undo the yalc link reference, you'll need to force the package install on the dependent project
dependent-project $ yarn install --force