Field settings

Generic field settings

Generic field settings are those which apply to all form fields, regardless of the type of field or the internal markup which is rendered within it.

The default settings are listed below with their values.

Generic field settings can be tweaked for all the fields in one instance of a changesetWebform component, in the fieldSettings object at the root of your formSchema.

Note that any of these settings can be overridden in one of the field objects in the formSchema.fields array.

    validationRules: [], // Array of objects defining validation rules. See "Validation".
    validatesOn: ['submit', 'pushErrors'], // Array of strings, specifing the names of events which should triggger validation.
    showValidationWhenFocussed: null, // Boolean - unless this is true, validation colours, icons and messages will be omitted for as long as the "focussed" prop of a field is true. The build in input and textarea fields set focussed to true when the user focuesses the element.
    omitted: false, // Boolean - or object - if true, the field is omitted and also ignored when validating or submitting the form. Can also be an object which defines rules for dynamic omission/inclusion. See /docs/hiding-and-showing-fields.
    defaultValue: null, // Any - auto set the changeset property for the field to this value when the ChangesetWebform component is rendered and the changeset is created. This value will be overridden by a corresponding property in the data object that is passed to the ChangesetWebform component.
    labelComponent: null, // Object with { componentClass, props }.
    // If set, fieldLabel becomes null.
    // `componentClass` is the imported class of the component to show inside the field label element.
    // `props` can be included to pass state or data to the component, accessible as {{@props}}.
    // `@changesetWebform, and @formField are passed to the component.
    labelMarkdown: null, // String - a markdown string to render as HTML within the label element.
    hideLabel: null, // Boolean - Hide the label from the user
    disabled: false, // Boolean - disable the field, but do not hide it. It will still be validated [TODO check] and included when the form is submitted
    resetWhenOmitted: true, // Boolean - reset the field value and validation when the field is omitted from the form.
    attrsFromConfig: {
      classNames: {}, // Object - keys can correspond to those in the classNames settings. See /docs/configure-classnames
    },
    cloneActionsPosition: 'fieldActions', // String - where to place the remove clone button in relation to the cloned field. Can be [TODO]
    includeLabelForAttr: false, // Boolean - if true, the label element will have a 'for' attribute that matches the input element's 'id' attribute.
    isFieldset: false, // Boolean - if true, the field options are wrapped in a fieldset element, and the field label is wrapped in a legend element.
    requiresAriaLabelledBy: false, // Boolean - if true, the field will have an aria-labelledby attribute that points to the field label. This is not required if the field uses semantic element/s such as inputs or textareas, and the "for" attribute of the label correctly points to the semantic element/s.

Custom parsers can be used to manipulate field definitions that are passed to the fields array in a formSchema. The customParser method is run at the very end of generating the form field instance, after all defaults have been applied.

It receives a single argument, field and must also return the field.

You can define a customParser method for all fields by adding it to the changesetWebformsDefaults.fieldSettings in services/ember-changeset-webforms.js.

You can also define customParser for a specific field type, in the relevant object in changesetWebformsDefaults.fieldTypes in services/ember-changeset-webforms.

These buttons are outside of the ChangesetWebform component

    // In the changesetWebformsDefaults object at changesetWebformsDefaults.fieldTypes
    {
      fieldType: 'input',
      customParser(field) {
        if (field.inputType === 'email') {
          field.validationRules = field.validationRules || [];
          const existing = field.validationRules.find((rule) => rule.validationMethod === 'validateFormat' && rule.arguments?.type === 'email');
          if (!existing) {
            field.validationRules.push({
              validationMethod: 'validateFormat',
              arguments: { type: 'email' },
            });
          }
        }
        return field;
      },
    },

Field settings

Generic field settings

The customParser method

The `customParser` method