formio-sfds

--- 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](#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](#data-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](#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](#data-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](#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](./localization.md) 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](#declarative-actions). See formiojs's [hooks documentation](https://github.com/formio/formio.js/wiki/Form-Renderer#hooks) for the list of available hooks. #### `on` option Like `hooks`, the `on` object can be used to specify [declarative actions](#declarative-actions) for any of formiojs's [known form events](https://github.com/formio/formio.js/wiki/Form-Renderer#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](src/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](#on-option) will not be registered. * The [`prefill` option](#prefill-option) will be ignored. ## Form upgrades Unless otherwise noted, all of the upgrades below can be opted out of with the [`formioSFDSOptOut` option](#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](#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: ```json { "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: ```json { "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: ```json { "hooks": { "beforeSubmit": { "values": { "foo": "bar" } } } } ``` ## Icons SFDS icons are rendered using [selector observer](https://github.com/josh/selector-observer) to replace the contents of elements with a `data-icon` attribute with the corresponding SVG icon at runtime, i.e. turning this: ```html <span data-icon="next" aria-label="Next"></span> ``` into this: ```html <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: ```html <i class="fa-info some-class"></i> ``` into this: ```html <i data-icon="info" class="some-class"> <svg ...></svg> </i> ``` See [icons in Figma] and [the source](../src/icons/index.js) for a full list of valid `data-icon` attribute values. [icons in Figma]: https://www.figma.com/file/Eyr2mvPBRMkkecBmbkkGogvP/Assets?node-id=38%3A8 [URLSearchParams]: https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams