## Spec for FormBuilder Package Allows end users and developers to quickly build forms, quizzes, and surveys that capture visitor data • Provides an advanced Form Builder (like wufoo or gravity forms) that can be used in a wide variety of places (e.g. a property window in the Editor Canvas, or by itself in the Quiz Builder) • Presents end users with a pleasant, drag and drop user experience for quickly building advanced forms, quizzes, and surveys • Presents developers with an easy to use react component api for displaying and capturing a variety of form data • Provides multiple ways (through a wide variety of ready-to-use form field types) of collecting user data • (in the future) Conditional logic, calculations, polls, captcha, ## Table of Contents - [Spec for FormBuilder Package](#spec-for-formbuilder-package) - [Table of Contents](#table-of-contents) - [Workflow](#workflow) - [User Stories](#user-stories) - [Test Plan](#test-plan) - [Acceptance Tests](#acceptance-tests) - [Screens / States](#screens--states) - [Components](#components) - [Layouts](#layouts) - [Containers](#containers) - [Components](#components-1) - [Schema](#schema) - [Component Schema](#component-schema) - [FormBuilder](#formbuilder) - [Schema](#schema-1) - [Tests](#tests) - [EditFormField](#editformfield) - [Schema](#schema-2) - [Tests](#tests-1) - [SelectFieldType](#selectfieldtype) - [Schema](#schema-3) - [Tests](#tests-2) - [LiveFormField](#liveformfield) - [Schema](#schema-4) - [Tests](#tests-3) - [TextField](#textfield) - [Schema](#schema-5) - [Tests](#tests-4) - [ContentField](#contentfield) - [Schema](#schema-6) - [Tests](#tests-5) - [TextAreaField](#textareafield) - [Schema](#schema-7) - [Tests](#tests-6) - [DropdownField](#dropdownfield) - [Schema](#schema-8) - [Tests](#tests-7) - [MultipleChoice](#multiplechoice) - [Schema](#schema-9) - [Tests](#tests-8) - [Checkboxes](#checkboxes) - [Schema](#schema-10) - [Tests](#tests-9) - [DateField](#datefield) - [Schema](#schema-11) - [Tests](#tests-10) - [FileUpload](#fileupload) - [Schema](#schema-12) - [Tests](#tests-11) - [LinearScaleField](#linearscalefield) - [Schema](#schema-13) - [Tests](#tests-12) - [Placeholder](#placeholder) - [Schema](#schema-14) - [Tests](#tests-13) - [Description](#description) - [Schema](#schema-15) - [Tests](#tests-14) - [InitialValue](#initialvalue) - [Schema](#schema-16) - [Tests](#tests-15) - [Label](#label) - [Schema](#schema-17) - [Tests](#tests-16) - [FormItemName](#formitemname) - [Schema](#schema-18) - [Tests](#tests-17) - [Columns](#columns) - [Schema](#schema-19) - [Tests](#tests-18) - [Required](#required) - [Schema](#schema-20) - [Tests](#tests-19) - [ValidationCriteria](#validationcriteria) - [Schema](#schema-21) - [Tests](#tests-20) - [AttributeContainer](#attributecontainer) - [Schema](#schema-22) - [Tests](#tests-21) - [FormBuilderEditorObject](#formbuildereditorobject) - [Schema](#schema-23) - [Tests](#tests-22) - [FormBuilderPropertyWindow](#formbuilderpropertywindow) - [Schema](#schema-24) - [Tests](#tests-23) - [FormInputEditorObject](#forminputeditorobject) - [Schema](#schema-25) - [Tests](#tests-24) - [FormInputProperyWindow](#forminputproperywindow) - [Schema](#schema-26) - [Tests](#tests-25) - [Database Schema](#database-schema) - [Store/Reducers](#storereducers) - [APIs/Hook Schema](#apishook-schema) ## Workflow ![](http://ambid-backups.s3.amazonaws.com/screenshots/sandcastle/component_formbuilder_workflow.jpg) ## User Stories - As a user, I would like the ability to quickly create a collection of form fields - As a user, I would like the ability to create, read, update, and delete each field in my form - As a user, I would like the ability to rearrange/re-order fields - As a user, I would like the ability to select from a collection of data input types (e.g. dropdown menus, text fields, etc.) - As a user, I would like the ability to customize/configure each selected form field - As a user, I would like the ability to set validation criteria for my selected form fields - As a developer, I would like to supply a list of fields, their name, type, and validation information in a simple array so that form creation is simple, consistent and fast - As a developer I would like basic control over the look, feel, and capabilities of my form fields ## Test Plan | Scenario | Expected | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | User clicks the [add new] btn | Should see the form builder icon | | User drags it to the canvas | Should see it in the editor canvas | | User loads a editor page with it in the content | Should see it in the editor canvas | | User loads a live page with it in the content | Should see it on the page | | User double-clicks or access form builder property window | Should see appropriate properties window | | Form Builder Properties Window is Open | should be able to crud multiple field types | | Form Builder Properties Window is Open | should be able to re-order the list of field types | | Form Builder Properties Window is Open | should see each field type expand to reveal more options when i click it | | Form Builder Properties Window is Open | should see the component in the canvas update to reflect any change to the option I make | | Form Builder Properties Window is Open | should be able to change the position of the entire form group | | Form Builder Properties Window is Open | should be able to change the padding of the entire form group | | Form Builder Properties Window is Open | should be able to change the width of the entire form group | | Form Builder Properties Window is Open | should be able to change the alignment of the entire form group | | Form Builder Properties Window is Open | should be able to change the every field's font | | Form Builder Properties Window is Open | should be able to change the every field's width | | Form Builder Properties Window is Open | should be able to change the every field's height | | Form Builder Properties Window is Open | should be able to change the every field's border | | Form Builder Properties Window is Open | should be able to change the every field's shadow | | Form Builder Properties Window is Open | should be able to change the every field's position | | Form Builder Properties Window is Open | should be able to change the every field's padding | ## Acceptance Tests (N/A) ## Screens / States ![](http://ambid-backups.s3.amazonaws.com/screenshots/sandcastle/component_formbuilder_google.png) ![](http://ambid-backups.s3.amazonaws.com/screenshots/sandcastle/component_formbuilder.jpg) ![](https://ambid-backups.s3.amazonaws.com/screenshots/sandcastle/components_formlayout.png) ![](http://ambid-backups.s3.amazonaws.com/screenshots/sandcastle/hf_crm.png)) ## Components ### Layouts N/A ### Containers N/A ### Components N/A ## Schema ### Component Schema #### FormBuilder ##### Schema | Name | Type | Description | Schema Type | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | mode | EditorMode | Establishes which version of the FormBuilder components should show | prop | | data | LiveFormFieldProps[] | The list of form fields that the form builder shows | prop | | sortableSettingsOverride | type:SortableListProps | the props to use for the SortableList component | prop | | globalFieldStyle | { labelStyle: React.CSSProperties, inputStyle: React.CSSProperties, containerStyle: React.CSSProperties, validationStyle: React.CSSProperties } | The style to use on all form field | prop | | validationSchema | yup.InferType | A Yup schema or a function that returns a Yup schema. | prop | | onChange | () => void | Triggers when one of the fields change • returns the item that changed, the complete mutated data array, and the validation status | prop | | onBlur | () => void | Triggers when one of the fields triggers a blur event • returns the item that changed, the complete mutated data array, and the validation status | prop | ##### Tests | It | Type | | ------------------------------------------------------------------------------------------------------------------------------ | ----------- | | (Rendering) Should render component in dom | Integration | | (Rendering) The list of or displayed should match number of fields in data array | Integration | | (Rendering) Should use when in edit mode | Integration | | (Rendering) Should use when in live mode | Integration | | (Rendering) Should use the "validationSchema" prop to determine the Yup validation schema | Integration | | (Rendering) Should use the items in the "globalFieldStyle" prop to determine the style to use each of the input field elements | Integration | | (Events) Should trigger the "onChange" event when one of the fields change | Integration | | (Events) Should trigger the "onBlur" event when one of the fields triggers a blur event | Integration | #### EditFormField ##### Schema | Name | Type | Description | Schema Type | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------- | | type | FormFieldTypes | The type of form field being edited | prop | | fieldData | LiveFormFieldProps | The form field attributes to use for that form field (e.g. placeholder, value, etc.) | prop | | showPreview | boolean | Whether or not to show the as a preview | prop | | isExpanded | boolean | Whether or not the component is showing in full, expanded view | prop | | caption | string | The label/caption to show for the component | prop | | globalFieldStyle | { labelStyle: React.CSSProperties, inputStyle: React.CSSProperties, containerStyle: React.CSSProperties, validationStyle: React.CSSProperties } | The style to use on all form field | prop | | onChange | (value: LiveFormFieldProps) => void | Triggers when the payload has changed in some way | prop | | onClick | () => void | Triggers when the container has been clicked | prop | | handleChange | (value: LiveFormFieldProps) => void | Performs any cleanups/combining of data (if any) before triggering the onChange event | method | ##### Tests | It | Type | | ---------------------------------------------------------------------------------------------------------------- | ----------- | | (Rendering) Should show the when the type prop is TEXT | Integration | | (Rendering) Should show the when the type prop is DATE | Integration | | (Rendering) Should show the input when the type prop is NUMBER | Integration | | (Rendering) Should show the when the type prop is CURRENCY | Integration | | (Rendering) Should show menu when the type prop is DROPDOWN | Integration | | (Rendering) Should show a checkbox & label ( the when type prop is CHECKBOX | Integration | | (Rendering) Should show radio input fields ( the when type prop is MULTIPLECHOICE | Integration | | (Rendering) Should show a the when type prop is TYPOGRAPHY | Integration | | (Rendering) Should show a component when the type prop is FILEUPLOAD | Integration | | (Rendering) Should show a component when the type prop is LINEARSCALE | Integration | | (Rendering) Should show an icon in the dom that reflects the item being loaded | Integration | | (Rendering) Show in expanded state when isExpanded is true | Integration | | (Rendering) Should show the LIVE preview of the component when showPreview is true | Integration | | (Rendering) Should show the caption provided in the dom | Integration | | (Events) Should trigger the onChange event when any change occurs in the form field | Integration | | (Events) Should pass an object that matches the the shape of the LiveFormFieldProps type when onChange is called | Integration | | (Events) Should trigger the onClick method when the container is clicked | Integration | | (Actions) Should toggle the expansion or collapsing of the container when clicked | Integration | #### SelectFieldType ##### Schema | Name | Type | Description | Schema Type | | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | value | FieldTypePayload | The currently selected choice | prop | | onChange | FieldTypePayload | • Triggered when a selection is made • Send as a payload you can send to the , the specific form field, and the attributes | prop | ##### Tests | It | Type | | ---------------------------------------------------------------------------------------------------------------------- | ----------- | | (Rendering) Should renders in the dom | Integration | | (Rendering) Should show a list of common choices in the selection menu | Integration | | (Rendering) Should show a list of custom field types in the selection menu | Integration | | (Rendering) Should shows the value provided in props as a label in the dom | Integration | | (Events) Should trigger the onChange event when a selection is made | Integration | | (Events) Should pass along the selected payload to the onChange event when the selection is made | Integration | | (Actions) Should populate the AttributeContainer with pre-filled out content when selection of a common choice is made | Integration | #### LiveFormField ##### Schema | Name | Type | Schema Type | Description | | ------------ | ------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | type | FormFieldTypes enum(input,date,number,currency,dropdown,checkbox,radio,typography,button,submit) | prop | The type of form field to be rendered. | | name | string | prop | name to use for the form field | | placeholder | string | prop | placeholder to use for the form field | | items | any[] | prop | the list of items to use where there are multiple options needed (e.g. a dropdown menu, multiple choice array) | | label | string | prop | the label to show next to the form field | | description | string | prop | the description to show next to the form field | | value | string | prop | the value to use for the form field | | styles | { labelStyle, inputStyle, containerStyle, validationStyle } | prop | the style to use for the default form field • an object of styles to use for the different aspects of the form field (e.g. validation container, the input field, the main container, the label, etc.) | | disabled | boolean | prop | whether or not the field is disabled | | icon | IconTypes | prop | the icon to use in this form field | | columns | number | prop | The number of columns (out of 12) to consume | | onChange | (payload: LiveFormFieldProps) => void | prop | function to trigger when the form field changes. returns a mutated version of the current LiveFormFieldProps payload | | onKeyUp | (evt: React.KeyboardEvent, payload: LiveFormFieldProps) => void | prop | function to trigger when a keyUp event occurs with the form field | | onClick | () => void | prop | function to trigger when a click event occurs with the form field | | handleChange | (payload: LiveFormFieldProps) => void | method | deal with any changes that come from the various form fields that I loads | ##### Tests | It | Type | | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | (Rendering) Should show the when the type prop is TEXT | Integration | | (Rendering) Should show the when the type prop is DATE | Integration | | (Rendering) Should show the input when the type prop is NUMBER | Integration | | (Rendering) Should show the when the type prop is CURRENCY | Integration | | (Rendering) Should show menu when the type prop is DROPDOWN | Integration | | (Rendering) Should show a checkbox & label ( the when type prop is CHECKBOX | Integration | | (Rendering) Should show radio input fields ( the when type prop is MULTIPLECHOICE | Integration | | (Rendering) Should show a the when type prop is TYPOGRAPHY | Integration | | (Rendering) Should show a component when the type prop is FILEUPLOAD | Integration | | (Rendering) Should show a component when the type prop is LINEARSCALE | Integration | | (Rendering) Should use the "placeholder" property found in a data array object as the placeholder for the form field | Integration | | (Rendering) Should use the "disabled" property found in a data array object determine whether or not the field is disabled | Integration | | (Rendering) Should use the "style" property found in a data array object to determine the style to use for the default form field | Integration | | (Rendering) Should use the "icon" property found in a data array object to determine the icon to use in this form field | Integration | | (Rendering) Should use the "label" property found in a data array object to determine the label to show next to the form field | Integration | | (Rendering) Should use the "value" property found in a data array object to determinethe value to use for the form field | Integration | | (Rendering) Should use the "description" property found in a data array object to determine the description to show next to the form field | Integration | | (Rendering) Should use the "(items)" property found in a data array object to determine the list of items to include in a dropdown menu field | Integration | | (Rendering) Should use the "values" prop to determine the field values to use for the form | Integration | | (Events) Should trigger the "onChange" property found in a data array object when the form field changes | Integration | | (Events) Should onChange should send back the original payload it received, but mutated) | Integration | | (Events) Should trigger the "onClick" property found in a data array object when a click event occurs with the form field | Integration | | (Events) Should trigger the "onKeyUp" property found in a data array object when a keyUp event occurs with the form field | Integration | #### TextField ##### Schema | Name | Type | Schema Type | Description | | ------------ | -------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | mode | EditorMode | prop | Establishes which version of the component to show | | onChange | (typeOfChange, updatedPayload) => void | prop | Triggers when the text field is updated • Sends back an updated version of the LiveFormFieldProps payload (e.g. if in live mode, the value would be changed, but if in edit mode, any of the other attributes might be changed) | | handleChange | (data: LiveFormFieldProps) => void | method | • Deals with any changes that comes from the various attributes that are loaded • Converts to LiveFormFieldProps shape • Triggers (and passes along the mutated LiveFormFieldProps payload to) the onChange event | ##### Tests | It | Type | | -------------------------------------------------------------------------------------------------------------------- | ----------- | | (Rendering) Should render in the dom | Integration | | (Rendering) Should render an EDITOR or LIVE version of the component based on the value of the mode prop | Integration | | (Rendering) Should render a regular text input field when the mode is live | Integration | | (Rendering) Should render the AttributeContainer component when the mode is edit | Integration | | (Rendering) Should see that the