patches.md

title
Patches

Patches to formio.js

Form options

Our patched version of Formio.createForm() adds support for the following options:

page option

This sets the initial page of the form by its index (position) in the list of visible pages starting from 1 (the first page, 2 is the second, and so on). Also note:

• The data option is applied before page, so if the desired page is conditionally hidden you will need to also provide data that will satisfy the conditions.
• The focus option is applied after page, and will override the page selection if the focused component is on a different page.

focus option

This attempts to focus a specific component by its unique "key" once it's loaded. Use this when testing validations on a specific field, or to scroll to a specific part of the form. Also note:

• The data option is applied before focus, so if components (or their pages) are conditionally hidden you may need to pass data that will satisfy the conditions.
• The page option is applied before focus, but you shouldn't need to use both because the form will set the initial page automatically in order to focus the right component.

data option

If provided, the data option will be passed along as the form's initial submission. See also: the prefill option.

googleTranslate option

If googleTranslate is false, the translate="no" attribute and notranslate class are added to the form element wrapper to prevent Google Translate from touching it. This is preferable (but not required!) when translations are provided via the i18n option, since Google Translate will attempt to translate any element that doesn't have the notranslate class, and may replace a human translation with a machine translation.

i18n option

If the i18n option is a string, it's treated as a JSON URL from which to load localizations (translations of form content and field info). See the localization docs for more info.

hooks option

If the hooks option is an object, any value that isn't a function is converted to a declarative action. See formiojs's hooks documentation for the list of available hooks.

on option

Like hooks, the on object can be used to specify declarative actions for any of formiojs's known form events.

prefill option

The prefill option allows you to pre-fill form inputs with submission data:

• The value querystring will cause pre-fill values to be parsed from window.location.search. E.g. ?foo=bar will initialze the form submission as {foo: 'bar'}.

• The value hash will cause pre-fill values to be parsed from window.location.hash (afer the leading #), so #foo=bar will initialize the form submission as {foo: 'bar'}.

• Otherwise, if prefill is an instance of URLSearchParams, the form submission will be initialized using its entries.

formioSFDSOptOut option

Setting the formioSFDSOptOut option to true disables all of the following customizations for your form:

• Scoped style modifications. Note: template modifications can't be opted out because they're provided at the theme level, so you'll need to style the selectors generated by this theme's templates, not the built-in ones!

• Select components will not be rendered as plain old <select> elements by default, and the autocomplete tag will be ignored.

• Custom event handlers will not be registered.

• The prefill option will be ignored.

Form upgrades

Unless otherwise noted, all of the upgrades below can be opted out of with the formioSFDSOptOut option.

• Detects the form rendering language (locale) by looking for the closest element with a lang attribute.

• Select components are made to always use the html5 "widget" (an HTML <select> element), unless the autocomplete tag also exists on the component (if component.tags.include('autocomplete')).

• Form elements are wrapped in <div class="formio-sfds">, which allows the element itself to receive styles defined in the scoped CSS.

• All components get validateOn: 'blur', which defers validation of fields until the input is blurred. The default is change, which triggers validation whenever an input changes, and can trigger disruptive validation errors while the user is typing.

Declarative actions

The hooks and on options allow you to customize form behaviors using a limited vocabulary of "declarative" actions. Each key of these objects is the name of a hook or event, and its value is an object with a single key that corresponds to one of the following actions:

• redirect takes either a URL string or an object with a url key and redirects (by setting window.location) to the URL. Submission data values may be interpolated in the redirect URL as {key}, where key is the API key of the form input. For example:

  {
    "on": {
      "submit": {
        "redirect": "/confirm?username={username}"
      }
    }
  }

• validateWithService passes the submission data to an HTTP web service for validation. The url is the URL of the web service, and may contain form value interpolations (e.g. {username} expands to form.submission.data.username), method tells it the HTTP verb (default: POST), and messages is an optional object containing custom messages for different types of errors, such as {empty: "error message if the response was empty"}. For instance, you might wish to validate a username field via an external service that would respond with an error if the provided username is already taken:

  {
    "hooks": {
      "beforeSubmit": {
        "validateWithService": {
          "url": "https://some-validation-service.example.com/username/{username}"
        }
      }
    }
  }

  If the web service fails, or if it's successful and the response JSON has an errors or error key, those are reported as errors and will abort beforeSubmit hooks.

• values validates submissions by comparing the value of the submission data with each key in the values object. For instance, to ensure that the foo form input has a value of "bar" before submission:

  {
    "hooks": {
      "beforeSubmit": {
        "values": {
          "foo": "bar"
        }
      }
    }
  }

Icons

SFDS icons are rendered using selector observer to replace the contents of elements with a data-icon attribute with the corresponding SVG icon at runtime, i.e. turning this:

<span data-icon="next" aria-label="Next"></span>

into this:

<span data-icon="next" aria-label="Next">
  <svg ...></svg>
</span>

FontAwesome icons (any element with an fa-* class name) rendered by Formio have the data-icon attribute icon added, which in turn triggers the SVG icon insertion described above, turning this:

<i class="fa-info some-class"></i>

into this:

<i data-icon="info" class="some-class">
  <svg ...></svg>
</i>

See icons in Figma and the source for a full list of valid data-icon attribute values.