foundation-field

foundation-field is a vocabulary to standardize the form field. In an application it is possible that we use many form field components from many different vendors. For example, native HTML provides <input> while CoralUI provides <coral-numberinput>. Because of this, the standardization into a normalized API is good way to interact with them, such that the application code can be more independent.

To select a logical field, you can use :-foundation-submittable selector.

Event

foundation-field-change

The event that MUST be triggered when the field value is changed.

The event has the following interface:

interface FoundationFieldChangeEvent {
  (): void;
}

AdaptTo Interface

type
foundation-field
condition
Any field element that can be adapted to this type
returned type
FoundationField
interface FoundationField {
  /**
   * Returns the name that identifies the field when submitting the form.
   */
  getName(): string;

  /**
   * Returns <code>true</code> if the field is disabled; <code>false</code> otherwise.
   */
  isDisabled(): boolean;

  /**
   * Indicates if the field is disabled.
   */
  setDisabled(disabled: boolean): void;

  /**
   * Returns <code>true</code> if the field is invalid in term of UI; <code>false</code> otherwise.
   *
   * The semantic meaning of invalid here means to indicate the field is invalid in term of UI, not necessarily implied to be due to validation.
   * However if the field is invalid in term of validation, it is very likely that this method returns <code>true</code>.
   * To check if the field is valid in term of validation, please check <code>foundation-validation</code>.
   */
  isInvalid(): boolean;

  /**
   * Indicates if the field is invalid in term of UI.
   */
  setInvalid(invalid: boolean): void;

  /**
   * Returns <code>true</code> if the field is mandatory to be filled; <code>false</code> otherwise.
   */
  isRequired(): boolean;

  /**
   * Indicates if the field is required.
   */
  setRequired(required: boolean): void;

  /**
   * Returns the submit value of the field.
   * If the field supports multiple values, the first value is returned.
   * If the field has no value, then <code>null</code> is returned.
   *
   * @see "Understanding Getting and Setting the Value" section
   */
  getValue(): string;

  /**
   * Sets a single value to the field, such that the field changes its internal state to hold that values.
   *
   * @see "Understanding Getting and Setting the Value" section
   */
  setValue(value: string): void;

  /**
   * Returns a space-separated list of element IDs used to label the field.
   */
  getLabelledBy(): string;

  /**
   * Sets a space-separated list of element IDs used to label the field.
   */
  setLabelledBy(value: string): void;

  /**
   * Returns the values of the field.
   * If the field doesn't support multiple values, the array of the single value is returned.
   * If the field has no value, then empty array is returned.
   *
   * @see "Understanding Getting and Setting the Value" section
   */
  getValues(): string[];

  /**
   * Sets multiple values to the field, such that the field changes its internal state to hold that values.
   *
   * @see "Understanding Getting and Setting the Value" section
   */
  setValues(values: string[]): void;
}

Understanding Getting and Setting the Value

It is important to note that the “value” when using getValue, setValue and their plural counterparts is meant to deal with submit value. The submit value is not necessarily meant that the value is indicated by value attribute of an element. This is designed this way as foundation-field is used to get or set the stored value, but not to configure the definition of the form fields themselves.

A good example for this is <input type="checkbox" value="value1">. It has a user semantic that allow the user to check/uncheck to indicate if the value is submitted or not. However the user doesn’t change the definition value when she does that.

So in this case, calling FoundationField#getValue(), it will return value1 when the checkbox is checked, otherwise it is null. Contrast this when you read its native value property, you will get value1 regardless of checked state.

Likewise, when calling FoundationField#setValue(), it will set checked property to true only if its value matches the passed parameter, without modifying its value property. Contrast this when you write its native value property, you will set value1 regardless of checked state.

Example

Given the following HTML:

<fieldset>
  <input name="textfield" value="textfieldOld">

  <input name="checkbox1" value="checkbox">
  <input name="checkbox2" value="checkbox" checked>
  <input name="checkbox3" value="checkbox">

  <select name="select">
    <option value="select1">Select 1</option>
    <option value="select2" selected>Select 2</option>
    <option value="select3">Select 3</option>
  </select>
</fieldset>

Fetching the value of each field using FoundationField#getValue() produces the following results:

  • textfield returns textfieldOld string
  • checkbox1 and checkbox3 returns null because they are unchecked
  • checkbox2 returns checkbox string because it is checked
  • select returns select2 string

Setting the value of each field using FoundationField#setValue() with the following values, match by name:

var values = {
  textfield: "textfield1",
  checkbox1: "checkbox",
  checkbox2: "othervalue",
  checkbox3: ["othervalue", "checkbox"]
  select: "select3"
};

produces the following results:

  • textfield has value of textfield1
  • checkbox1 and checkbox3 are checked, due to the matching value
  • checkbox2 is not checked, due to non matching value
  • Select 3 option is selected, while other options are not