Skip to main content

Extend an existing field

In order to extend an existing field you must subclass a built in field (e.g FieldTextInput, FieldColour) and then modify part of it to fit your needs. Some parts of a field you can modify are:

If you want to create a custom field that does not need behaviour from any built-in field you should subclass Field.

Common extensions​

Most custom fields extend one of these three types:

  • Text Input: If you want your users to type into your field, you should extend FieldTextInput.
  • Number: If you want to store a number, you should extend FieldNumber.
  • Dropdown: If you want to create a dropdown, but you want it to store a different model than the default string or image model, you should extend FieldDropdown. - Caution: Before extending FieldDropdown, check that the dropdown field's customization options cannot fulfill your needs.

Under certain circumstances you may wish to extend a different field type. For example FieldLabelSerializable extends FieldLabel.

Subclassing​

import * as Blockly from 'blockly';

export class MyCustomTextField extends Blockly.FieldTextInput {
  constructor(value, validator, config) {
    super(value, validator, config);
  }
}

The constructor for a field's subclass looks very similar to the constructor for a custom field. The signature of the sub-constructor should generally match the signature of the super-constructor.

JSON and registration​

You should also register the field once:

Blockly.fieldRegistry.register('my_custom_text_field', MyCustomTextField);

and provide an implementation of fromJson in the class so that it works with the JSON format:

static fromJson(options) {
  const value = Blockly.utils.parsing.replaceMessageReferences(options.value);
  return new MyCustomTextField(value);
}

For more information about registering a field see the JSON and registration section in Creating a Custom Field.

Accessibility​

You are responsible for ensuring that your custom fields are WCAG compliant and correctly implement IFocusableNode. That includes having an appropriate ARIA role for your on-block display and making your field editor WCAG compliant.

When the on-block display is focused, its focusable DOM element will have the blocklyActiveFocus or blocklyPassiveFocus CSS class added. Blockly defaults to showing a yellow outline around the focused field. You may override this behaviour as long as you show visible focus.

All fields must have an ARIA type and value, which are used to construct the ARIA label. The ARIA label is generally of the form <ARIA type>: <ARIA value>. When extending a built-in field you will inherit its ARIA type and value logic. You can override the inherited ARIA logic by overriding any of getAriaTypeName, getAriaValue, and computeAriaLabel.

ARIA value vs text​

getAriaValue must return a human-readable, screen reader–appropriate representation of the field’s current value. By default, it returns the result of getText, which is not guaranteed to be informative for assistive technologies. You must override getAriaValue when getText might not produce a meaningful spoken representation (for example, when possible values include symbols, abbreviations, or non-textual representations such as icons or colors). If getAriaValue would return an empty or non-informative value, it must instead return a localized string indicating that the value is empty.