@worksafevictoria/wcl7.5 1.1.10 → 1.1.12

package/src/components/SubComponents/FormInstance/stories/Documentation.mdx

@@ -0,0 +1,234 @@
+import { Canvas, Meta } from '@storybook/blocks';
+import * as FormStories from './build.stories';
+
+<Meta of={FormStories} />
+
+## Purpose
+
+This guide describes the process of creating forms by an administrator for accepting data from end-users.
+
+## Components
+
+- Drupal
+  - Back-end CMS product for managing content. [link](https://www.drupal.org/)
+
+- Drupal WebForms
+  - Third-party extension to Drupal which allows administrators to create forms and view submissions. [link](https://www.drupal.org/project/webform)
+
+- Front-End site
+  - End-user site where forms are rendered for end-user to provide data.
+
+- <span>Form.io</span>
+  - Third-party library used by the front-end that takes in forms defined in Drupal WebForms and renders them as regular HTML in the browser. No knowledge of formio is required to be known by the administrator. [link](https://www.form.io/)
+
+
+## Technical Architecture
+
+A  drupal webform is created either by manually building a form or asking a drupal developer to create the form via code/git.
+
+A user requests the form from the browser which invokes a REST call to the drupal webform json-api endpoint called the elements api. What comes back will be a nested JSON structure describing the various fields of the form and their properties.
+
+Custom front-end code is then used to transform this webform json into Form.io library compatible json [link](https://formio.github.io/formio.js/app/builder). 
+
+Form.io offers an open source JS library wherein a JSON data set is inputted and a ready-to-use html form is outputted.
+
+On submitting the formio form in the browser, an api payload is then sent to the drupal webform backend using the submit api.
+
+## User groups
+
+- End-user
+  - The user who view the form on the browser and can submit a form
+- Administrator
+  - Staff member with drupal CMS access. Can build forms andd view submissions using the Drupal CMS interface. It is discouraged to change forms manually using the interface
+- Drupal Developer
+  - Can programatically add, update and delete forms. This is the preferred way of working with forms so as to allow replication to different environments.
+- Front-end Developer
+  - Deals with formio form component rendering. Can configure the look and feel of the form to end-users
+
+
+## Tutorials
+
+You can google for Drupal WebForms tutorial. There are also plenty of good tutorial for it on Youtube. Just ensure that you are viewing it for the right drupal version.
+
+## Form Creation Lifecycle
+
+### Administrator - Create Form
+1. Login to Drupal CMS
+2. Open `Webforms` (Top Menu -> Structure -> webforms)
+3. Click `Add WebForm`
+4. Provide a unique name (key) to the webform
+5. Drag and Drop form elements to new form e.g. textfield, radio, drop-down.
+6. Configure each element by click the edit icon on that row. It should open a sidebar with tabs.
+7. Save form
+
+### End User - View Form
+8. Vist the forms page on the front-end website by going to `http://<public-website>/forms/<form key from step 4>` e.g. https://ws-ui.wsvdigital.com.au/forms/kitchen_sink_formio_v1
+9. Fill up form fields and click submit
+
+
+### Administrator - View Submission
+10. Login to Drupal CMS
+11. Open `Webforms` (Top Menu -> Structure -> webforms)
+12. Locate the row related to the existing form defined in step 3
+13. Click on `results` column link
+
+
+## Form Elements
+
+### Basic Elements
+
+| Name  | Example  |  Description  |
+|---|---|---|
+| Checkbox  | [link](/?path=/story/form-basic-controls--checkbox) | A single checkbox for Yes/No responses |
+| Hidden  | [link](/?path=/story/form-basic-controls--hidden) | A hidden field for storing invisible values such as calculations. The `default value` can be configured to contain drupal tokens such as current date by clicking on `Browse available tokens` or you can supply dynamic values with references to other form elements such as `hey {{ data.number1}} is {{ 1 + 2 }}` which when submitted will appear as `hey 100 is 3`. In this example, `number1` is the key of a number element and `data` is the parent form object |
+| Textfield  | [link](/?path=/story/form-basic-controls--text-field) | A textbox for alpha numeric text |
+| Textarea | [link](/?path=/story/form-basic-controls--text-area) | A large textbox for multi-line text |
+
+### Advanced Elements
+
+| Name  | Example  |  Description  |
+|---|---|---|
+| Autocomplete  | [link](/?path=/story/form-advanced-controls--autocomplete) | A dropdown that matches data from an external api as you type |
+| Codemirror  |  | A hidden control where developer code can be inserted. Custom HTML, CSS and JS code must be added under the description field in source view |
+| Email | [link](/?path=/story/form-advanced-controls--email) | A textfield that only allows email-pattern text |
+| Email Confirm | [link](/?path=/story/form-composite--email-confirm) | Two textfields which asks the user to provide an email and then confirm that email again |
+| Number | [link](/?path=/story/form-advanced-controls--number) | A numeric field. Configure the `step` field with decimal places. A step of 2 allows decimals with two places while empty step will only allow integers |
+| Range | [link](/?path=/story/form-custom-controls--range) | A sliding numeric scale along with a textbox for manual entry |
+| Rating | [link](/?path=/story/form-custom-controls--rating) | A rating scaled comprised of stars  |
+| Same As | [link](/?path=/story/form-advanced-controls--same-as) | Allows the user to display a checkbox to ask if one form value (`source element`) is the same as another (`destination element`). e.g. is home address the same as postal address |
+| Scale | [link](/?path=/story/form-custom-controls--scale) | A rating scaled comprised of numbers |
+| Signature | [link](/?path=/story/form-advanced-controls--signature) | Allows the user to sign the form by using their mouse to draw a pattern |
+| Telephone | [link](/?path=/story/form-advanced-controls--telephone) | A textfield which allows 10 digit phone numbers |
+| URL | [link](/?path=/story/form-advanced-controls--url) | A textfield that accepts urls with or without http(s) prefix |
+| Value  | [link](/?path=/story/form-advanced-controls--value) | Allows the end user to enter rich text such as headings, paragraphs and bolding. Submits it as HTML and which then can be sent in a submission email |
+
+### Composite Elements
+
+| Name  | Example  |  Description  |
+|---|---|---|
+| Address | [link](/?path=/story/form-composite--address) | Allows you to select an address via google maps. It also allows you to manually enter an address. Disable fields in drupal that are not needed in manual mode. If you disable the address manual field, it will then only match postcode suburbs from Google|
+| Custom Composite | [link](/?path=/story/form-composite--custom-composite) | Allows the end-user to create an 'entity' list. An entity can be comprised of one or more form elements defined under `CUSTOM COMPOSITE SETTINGS`. e.g. Entity of `Persons` is comprised of `first name` (textbox) and `is coming?` (checkbox). This control would allow the end-user to add multiple persons as rows in a table. 
+
+### Markup Elements
+
+| Name  | Example  |  Description  |
+|---|---|---|
+| Advanced HTML | [link](/?path=/story/form-markup-controls--advanced-html) | Allows the administrator to enter rich text under `PROCESSED TEXT SETTINGS` such as headings, paragraphs and bolding. |
+| Basic HTML | [link](/?path=/story/form-markup-controls--basic-html) | Same as advanced HTML |
+| Horizontal Rule | [link](/?path=/story/form-markup-controls--horizontal-rule) | A horizontal line is inserted on the form |
+| Label | [link](/?path=/story/form-markup-controls--label) | Creates a new label on the form with some basic text. You can also include HTML |
+| Message | [link](/?path=/story/form-markup-controls--message) | Show alert messages. Set the message status to info, error or warn to render different alert colours.
+| More | [link](/?path=/story/form-markup-controls--more) | Show collapsible help text
+
+### Options Elements
+
+| Name  | Example  |  Description  |
+|---|---|---|
+| Checkboxes | [link](/?path=/story/form-options-controls--checkboxes) | Create a bunch of tickable checkboxes for multiple selection |
+| Checkboxes other | [link](/?path=/story/form-options-controls--checkboxes-other) | Same as checkbox but allows end-user to select `other` option and manually enter value |
+| Likert | [link](/?path=/story/form-options-controls--likert) | Creates a table with rows and columns. For each row, the user must select a column. Good for surveys where row is question and columns are a score from 1 to 10 |
+| Radios | [link](/?path=/story/form-options-controls--radios) | Create a list of radio buttons for single selection |
+| Radios other | [link](/?path=/story/form-options-controls--radios-other) | Same as radios but allows end-user to select `other` option and manually enter value |
+| Select | [link](/?path=/story/form-options-controls--select) | Create a dropdown of for single selection |
+| Select other | [link](/?path=/story/form-options-controls--select-other) | Same as Select but allows end-user to select `other` option and manually enter value |
+| Table Select | [link](/?path=/story/form-options-controls--table-select) | Same as likert but with one column containing a toggle button  |
+
+### Computed Elements
+
+| Name  | Example  |  Description  |
+|---|---|---|
+| Computed token | [link](/?path=/story/form-composite--token) | Read-only display of all the entered values in the form. No configuration necessary beyond label text. Good for showing a page where end-user can review selections before submission |
+| Computed Twig | [link](/?path=/story/form-composite--twig) | Read-only display of computations or dynamic text. Text can be specifiedf under `Computed value/markup`. Anything within the curly braces `{{` `}}` is a javascript computation. All form control values are stored under the `data` object. For example, given two number controls `n1` and `n2`, a twig can have a template of `the sum of two numbers is {{ data.n2 + data.n1 }}`. On render, it will appear as `the sum of two numbers is 5` |
+
+### Container Elements
+
+| Name  | Example  |  Description  |
+|---|---|---|
+| Container | [link](/?path=/story/form-layout-controls--container) | A container is just an invisible grouping of controls. It allows you to show/hide the group without having to show/hide each control in that group |
+| Details | [link](/?path=/story/form-layout-controls--details) | Similar to container but controls are wrapped in a collapsible accordion |
+| Fieldset | [link](/?path=/story/form-layout-controls--fieldset) | Similar to container but allows you to set a title and description for the group |
+| Flexbox | [link](/?path=/story/form-layout-controls--flexbox) | Allows you to create a column-based layout. Add a flexbox and then add elements to the flexbox. Each row is a new column |
+| Section | [link](/?path=/story/form-layout-controls--section) | Similar to container but has a Heading |
+| Table | [link](/?path=/story/form-layout-controls--table) | Similar to Flexbox but in the form of a table with a table header and bordered table columns |
+
+### Date Elements
+
+| Name  | Example  |  Description  |
+|---|---|---|
+| Date | [link](/?path=/story/form-date-controls--date) | Simple date control with a calendar widget and/or manual textbox entry. Weekends can be disabled as well min/max date set. You can set a min or max date using the format dd/mm/yyyy or dd-mm-yyyy. You can also words like 'today', '+2 months', '-10 days' or '+1 years' for dynamic date validation. |
+| Date Time | [link](/?path=/story/form-date-controls--date-time) | Similar to Date control but also provides an option to select time |
+| Time | [link](/?path=/story/form-date-controls--time) | A simple time widget |
+| Date List | [link](/?path=/story/form-date-controls--date-list) | Similar to Date control but uses dropdown for each part of the date. Useful if you want to collect a date without a year or month or day |
+
+## Conditional Rules
+
+Conditional rules allow you to dynamically change the state of form elements. The following actions are available when you configure an element and open the `Conditions` tab
+
+### State
+
+| Name  | Example  |  Description  |
+|---|---|---|
+| Hidden | [link](/?path=/story/form-conditions--hidden) | Will hide a visible element. The element's existing value will still be submitted. If you want to clear the element's value on hide, select the checkbox `Clear value(s) when hidden?`
+| Visible | [link](/?path=/story/form-conditions--visible) | Will make visible an element hidden by default. An element can be made to be hidden by default if you configure an element and click on the `Access` tab and at the bottom unselect `Display element` |
+| Disabled | [link](/?path=/story/form-conditions--disabled) | Will make an element read-only. Read-only values are not submitted`
+| Enabled | [link](/?path=/story/form-conditions--enabled) | Will un-make an element read-only. Read-only values are not submitted`
+| Required  | [link](/?path=/story/form-conditions--required) | Will make an element required for submission
+| Optional  | [link](/?path=/story/form-conditions--required) | Will make an element optional for submission
+
+
+## Validation and Behaviour
+
+You can configure an element to have client-side validation. Configure an elemenet and at the bottom of an element, you can find the following common validators
+
+- Required
+  - Will make a field required for submission. You can add a custom required message
+- Unique
+  - The field value must be unique in relation to previous submissions. This will show an error only on submission
+- Pattern
+  - A javascript pattern for regular expression. This can dynamically apply validation on text strings. e.g. `^[A-Z9]{5}\d{6}[A-Z9]{2}\d[A-Z]{2}$` is drivers license validation with an example accetable value of `FARME100165AB5EW`
+-  Disabled and ReadOnly
+  - This will grey out the element and the value will not be included in submission.
+-  Display (checkbox at the bttom of the Access tab)
+  - This will hide the element when it loads
+-  Default Value (first element under Advanced tab)
+  - You can set a default value here for when the element first renders
+-  Multiple
+  - You can configure for a form element to be a list instead of a single component. Under `ELEMENT SETTINGS` in the general tab, set the `Allowed number of values` to be a number. [example](/?path=/story/form-composite--multiple)
+
+## Custom Styling
+
+- Adding HTML, JS and CSS?
+  - Add a `code mirror` form element. Open source accordion view in form builder. and add your html to the #description property
+  ```
+  '#type': codemirror
+  '#title': global
+  '#description': |-
+    <style>
+    .task__card {
+        position: relative;
+        width: 100%;
+    }
+    </style>
+    <script>
+       window.reload()
+    </script>
+    <div>
+     test
+    </div>
+  ```
+
+- Adding minor CSS styles
+  - Confiuge an element and click on the `Advanced tab`. You can prvovide CSS styles tot the wrapper, element or label. A sample CSS style for a yellow background with extra padding is `background: yellow; padding: 10px;`. [example](/?path=/story/form-custom-style--default) 
+
+## Multi-page
+
+- To create a multi-step form, click on `Add page` button on the form builder. Make sure every new page is the root container element in the form. All controls for a page can be added below the page's row.  [example](/?path=/story/form-wizard--default) 
+
+
+## Submission handling
+
+- View Submissions
+  - You can view form submissions under the `Results` tab in form builder
+
+- Email Submissions
+  - You can configure webforms to send you an email everytime a form is submitted. Go to the `Settings` in form builder and click on Emails/Handlers. Add your email here. Make sure your email is whitelisted in Mailgun (speak to your Drupal Developer about it). 

package/src/components/SubComponents/FormInstance/stories/advanced.stories.js

@@ -0,0 +1,109 @@
+import FormInstance from '../index.vue'
+import autocomplete from './mocks/autocomplete.json'
+import email from './mocks/email.json'
+import number from './mocks/number.json'
+import signature from './mocks/signature.json'
+import telephone from './mocks/telephone.json'
+import url from './mocks/url.json'
+import value from './mocks/value.json'
+import sameas from './mocks/sameas.json'
+
+export default {
+  title: 'Form/Advanced Controls',
+  component: FormInstance,
+  argTypes: {
+    preview: {
+      control: 'boolean',
+      defaultValue: true,
+      table: {
+        disable: true
+      }
+    },
+    contentApiUrl: {
+      control: 'text',
+     defaultValue: process.env.CONTENT_API_URL
+    },
+    processID: {
+      control: 'text',
+      defaultValue: 'proc-id-form-advanced-controls',
+      table: {
+        disable: true
+      }
+    },
+    formid: {
+      control: 'string',
+      defaultValue: '',
+      table: {
+        disable: true
+      }
+    },
+    type: {
+      control: 'text',
+      defaultValue: '',
+      table: {
+        disable: true
+      }
+    },
+    webFormJson: {
+      control: 'object'
+    }
+  },
+  args: {
+    processID: 'proc-id-form-advanced-controls',
+    preview: true,
+    contentApiUrl:process.env.CONTENT_API_URL
+
+  }
+}
+
+export const Autocomplete = {args : {
+  type: 'webform_autocomplete',
+  webFormJson: autocomplete,
+
+}
+}
+
+export const Email = {args : {
+  type: 'email',
+  webFormJson: email
+}
+}
+
+export const Number = {args : {
+  type: 'number',
+  webFormJson: number
+}
+}
+
+export const Signature = {args : {
+  type: 'webform_signature',
+  webFormJson: signature
+}
+}
+
+export const Telephone = {args : {
+  type: 'tel',
+  webFormJson: telephone
+}
+}
+
+export const URL = {args : {
+  type: 'url',
+  webFormJson: url
+}
+}
+
+export const Value = {
+  args : {
+    type: 'value',
+    webFormJson: value
+  }
+}
+
+export const SameAs = {
+  args : {
+    type: 'sameas',
+    webFormJson: sameas
+  }
+}
+

package/src/components/SubComponents/FormInstance/stories/basic.stories.js

@@ -0,0 +1,73 @@
+import FormInstance from '../index.vue'
+import textfield from './mocks/textfield.json'
+import textarea from './mocks/textarea.json'
+import hidden from './mocks/hidden.json'
+import checkbox from './mocks/checkbox.json'
+
+export default {
+    title: 'Form/Basic Controls',
+    component: FormInstance,
+    argTypes: {
+      preview: {
+        control: 'boolean',
+        defaultValue: true,
+        table: {
+          disable: true
+        }
+      },
+      contentApiUrl: {
+        control: 'text',
+       defaultValue: process.env.CONTENT_API_URL
+      },
+      processID: {
+        control: 'text',
+        defaultValue: 'proc-id-form-basic-controls',
+        table: {
+          disable: true
+        }
+      },
+      formid: {
+        control: 'string',
+        defaultValue: '',
+        table: {
+          disable: true
+        }
+      },
+      type: {
+        control: 'text',
+        defaultValue: '',
+        table: {
+          disable: true
+        }
+      },
+      webFormJson: {
+        control: 'object'
+      }
+    },
+    args: {
+      processID: 'proc-id-form-basic-controls',
+      preview: true,
+      contentApiUrl:process.env.CONTENT_API_URL
+    }
+  }
+
+export const TextField = {
+  args : {
+    webFormJson: textfield
+}
+}
+
+export const TextArea = {}
+TextArea.args = {
+  webFormJson: textarea
+}
+
+export const Hidden = {}
+Hidden.args = {
+  webFormJson: hidden
+}
+
+export const Checkbox = {}
+Checkbox.args = {
+  webFormJson: checkbox
+}

package/src/components/SubComponents/FormInstance/stories/build.stories.js

@@ -0,0 +1,27 @@
+import { FormBuilder } from '@formio/vue'
+
+export default {
+    title: 'Form',
+    component: FormBuilder,
+}
+
+const Template = (args) => ({
+    components: { FormBuilder },
+    setup () {
+      return { args }
+    },
+    template: 
+  `  <div>
+      <div>
+          <h3>{{args.heading}}</h3>
+          <form-builder v-bind="args" v-on:change="(schema) => args.message=schema"></form-builder>
+      </div>
+      <textarea class="form-control" rows="20">{{args.message}}</textarea>
+      </div>
+    `
+  })
+
+export const Builder = Template.bind({})
+Builder.args = {
+    message:'No form content'
+}

package/src/components/SubComponents/FormInstance/stories/composite.stories.js

@@ -0,0 +1,90 @@
+import FormInstance from '../index.vue'
+import address from './mocks/address.json'
+import emailconfirm from './mocks/emailconfirm.json'
+import multiple from './mocks/multiple.json'
+import customcomposite from './mocks/customcomposite.json'
+import twig from './mocks/twig.json'
+import token from './mocks/token.json'
+
+export default {
+    title: 'Form/Composite',
+    component: FormInstance,
+    argTypes: {
+      preview: {
+        control: 'boolean',
+        defaultValue: true,
+        table: {
+          disable: true
+        }
+      },
+      contentApiUrl: {
+        control: 'text',
+       defaultValue: process.env.CONTENT_API_URL
+      },
+      processID: {
+        control: 'text',
+        defaultValue: 'proc-id-form-composite',
+        table: {
+          disable: true
+        }
+      },
+      formid: {
+        control: 'string',
+        defaultValue: '',
+        table: {
+          disable: true
+        }
+      },
+      type: {
+        control: 'text',
+        defaultValue: '',
+        table: {
+          disable: true
+        }
+      },
+      webFormJson: {
+        control: 'object'
+      }
+    },
+    args: {
+      processID: 'proc-id-form-composite',
+      preview: true,
+      contentApiUrl:process.env.CONTENT_API_URL
+    }
+}
+
+export const Address = {}
+Address.args = {
+  type: 'address',
+  webFormJson: address
+}
+
+export const EmailConfirm = {}
+EmailConfirm.args = {
+  type: 'webform_email_confirm',
+  webFormJson: emailconfirm
+}
+
+export const Multiple = {}
+Multiple.args = {
+  type: 'multiple',
+  webFormJson: multiple
+}
+
+export const CustomComposite = {}
+CustomComposite.args = {
+  type: 'webform_custom_composite',
+  webFormJson: customcomposite
+}
+
+export const Twig = {}
+Twig.args = {
+  type: 'twig',
+  webFormJson: twig
+}
+
+export const Token = {}
+Token.args = {
+  type: 'token',
+  webFormJson: token
+}

package/src/components/SubComponents/FormInstance/stories/condition.stories.js

@@ -0,0 +1,83 @@
+import FormInstance from '../index.vue'
+import rulehiddenvalue from './mocks/rule-hidden-value.json'
+import rulevisiblevalue from './mocks/rule-visible-value.json'
+import ruleDisabledvalue from './mocks/rule-disabled-value.json'
+import ruleEnabledvalue from './mocks/rule-enabled-value.json'
+import ruleRequiredvalue from './mocks/rule-required-value.json'
+
+export default {
+    title: 'Form/Conditions',
+    component: FormInstance,
+    argTypes: {
+      preview: {
+        control: 'boolean',
+        defaultValue: true,
+        table: {
+          disable: true
+        }
+      },
+      contentApiUrl: {
+        control: 'text',
+       defaultValue: process.env.CONTENT_API_URL
+      },
+      processID: {
+        control: 'text',
+        defaultValue: 'proc-id-form-conditions',
+        table: {
+          disable: true
+        }
+      },
+      formid: {
+        control: 'string',
+        defaultValue: '',
+        table: {
+          disable: true
+        }
+      },
+      type: {
+        control: 'text',
+        defaultValue: '',
+        table: {
+          disable: true
+        }
+      },
+      webFormJson: {
+        control: 'object'
+      }
+    },
+    args: {
+      processID: 'proc-id-form-conditions',
+      preview: true,
+      contentApiUrl:process.env.CONTENT_API_URL
+    }
+}
+
+export const Hidden = {}
+Hidden.args = {
+  type: 'Hidden',
+  webFormJson: rulehiddenvalue
+}
+
+export const Visible = {}
+Visible.args = {
+  type: 'Visible',
+  webFormJson: rulevisiblevalue
+}
+
+export const Disabled = {}
+Disabled.args = {
+  type: 'Disabled',
+  webFormJson: ruleDisabledvalue
+}
+
+export const Enabled = {}
+Enabled.args = {
+  type: 'Enabled',
+  webFormJson: ruleEnabledvalue
+}
+
+export const Required = {}
+Required.args = {
+  type: 'Required',
+  webFormJson: ruleRequiredvalue
+}

package/src/components/SubComponents/FormInstance/stories/custom.stories.js

@@ -0,0 +1,69 @@
+import FormInstance from '../index.vue'
+import rating from './mocks/rating.json'
+import scale from './mocks/scale.json'
+import range from './mocks/range.json'
+
+export default {
+    title: 'Form/Custom Controls',
+    component: FormInstance,
+    argTypes: {
+      preview: {
+        control: 'boolean',
+        defaultValue: true,
+        table: {
+          disable: true
+        }
+      },
+      contentApiUrl: {
+        control: 'text',
+       defaultValue: process.env.CONTENT_API_URL
+      },
+      processID: {
+        control: 'text',
+        defaultValue: 'proc-id-form-custom-controls',
+        table: {
+          disable: true
+        }
+      },
+      formid: {
+        control: 'string',
+        defaultValue: '',
+        table: {
+          disable: true
+        }
+      },
+      type: {
+        control: 'text',
+        defaultValue: '',
+        table: {
+          disable: true
+        }
+      },
+      webFormJson: {
+        control: 'object'
+      }
+    },
+    args: {
+      processID: 'proc-id-form-custom-controls',
+      preview: true,
+      contentApiUrl:process.env.CONTENT_API_URL
+    }
+  }
+
+export const Rating = {}
+Rating.args = {
+  type: 'rating',
+  webFormJson: rating
+}
+
+export const Scale = {}
+Scale.args = {
+  type: 'scale',
+  webFormJson: scale
+}
+
+export const Range = {}
+Range.args = {
+  type: 'range',
+  webFormJson: range
+}