Calderajs Form Builder

Install from npmjs > yarn add @calderajs/form-builder

Components for building the Caldera Forms form builder. This library is used in caldera-forms/clients/form-builder/index.js

The boundry between this library and that file should be that in CF, componets interact with the DOM and legacy state. Everything below that, goes here. That's why it's one file.

The components in Caldera Forms core mainly do not render anything, they just bind to DOM events to watch for changes in state.

Usage

Import Components

See src/exports.text.ts for the full list of importable elements.

import {
  SubscribesToFormFields,
  useCurrentFormFields,
  useNotAllowedFields,
  useFormFields,
  SelectFormField,
  Page,
  Section,
  ProcessorConditionalEditor,
  prepareConditionalForSave,
  prepareConditionalsForSave,
  conditionalsFromCfConfig,
  conditionalFromCfConfig,
  useProcessorConditonals,
  useConditionals,
  ConditionalEditor,
  RenderViaPortal,
} from '@calderajs/form-builder';

Use Portals Always

Beacuse this library lives on the same page as legacy code, we will never render on the element provided to ReactDOM. Instead Portals are always used. The RenderViaPortal component should be used for this:

import { RenderViaPortal } from '@calderajs/form-builder';

function SomethingPortal() {
  const node = document.getElmentById(`whatever`);
  if (!node) {
    return <React.Fragment />;
  }
  return (
    <RenderViaPortal domNode={node}>
      <Something />
    </RenderViaPortal>
  );
}

Context Providers

Short Intro To React Context

This package makes use of React's Context API. Context provides shared state and functions to update state between components without passing props. Doing so decouples state logic from position in the (virtual-)DOM.

The component <FormBuilder /> uses all four providers:

• <FormFieldsProvider intitalFields={intitalFields} />
  • State for form fields
• <MagicTagProvider systemValues={systemValues} />
  • Magic tags state. Must be under FormFieldsProvider.
• <ConditionalsProvider initialConditionals={initialConditionals}>
  • Conditional logic state. Must be under FormFieldsProvider and MagicTagProvider providers.
• <ProcessorsProvider initialProcessors={initialProcessors} jQuery=jQuery} />
  • Must be under FormFieldsProvider, MagicTagProvider and ConditionalsProvider providers.

Development

• Install
  • git clone
  • yarn
• Test
  • yarn test --watch
• Build
  • yarn build
• Start Storybook
  • yarn storybook

Storybook

Related documentation

This repo is intentionally isolated from Caldera Forms core to encourage test-driven development and to constrain the boundries.

You can start a Storybook site to visualize the componets.

The yarn storybook command will start a "Storybook" site. You can use this to experiment with the componets. The file .storybook\preview-head.html is used to add style tags that bring in a lot of Caldera Forms' admin styles, using CalderaForms.com. That's a hack, and isn't perfect looking at all, but it's enough for now.

Devloping With Caldera Forms

It reamins neccasary, to test with Caldera Forms. You should use Yarn Link to install this project via symlink in Caldera Forms.

• In this directory, build for production.
  • yarn build
• In this directory, enable other projects to link to this project.
  • yarn link
• In Caldera Forms, link to this project
  • yarn link @calderajs/form-builder
• In Caldera Forms, rebuild clients
  • yarn build:clients

Releasing A Version And Updating In Caldera Forms

Related Docs

Using link to test before releasing an update is strongly encouraged. After doing so, you must unlink the package, release an update and update Caldera Forms.

Before begining, make sure you are logged in to npmjs.com using Yarn's cli. Also, make sure you are Josh or Nico. If you are not Josh or Nico, please open a message in the engineering team in Basecamp and request you be granted acess. Please tag Josh and Nico and include your npmjs.com username in the message.

Please follow these steps:

• In Caldera Forms, unlink
  • yarn unlink @calderajs/form-builder
• In this directory, unlink
  • yarn link
• In this directory, publish
  • yarn publish
  • You will be prompted to provide a new version.
  • Please observer semver
• In Caldera Forms force reinstall old version -- removing symlink totally.
  • yarn install --force
• In Caldera Forms, add the new version
  • yarn add @calderajs/form-builder@<new-version>