Text input fields

AI-generated Key Takeaways

• A text input field stores a string value and allows user text input, with the value always being a valid string.

• You can create text input fields using JSON or JavaScript, customizing them with options like spellcheck and validators.

• Text input fields can be serialized and deserialized using JSON or XML, representing the field name and value.

• The setSpellcheck function allows control over individual field spellchecking, while Blockly.FieldTextInput.prototype.spellcheck_ affects all fields.

• Validators for text input fields accept a string and return a modified string, null, or undefined to enforce specific input rules.

A text input field stores a string as its value and a string as its text. Its value is always a valid string, while its text could be any string entered into its editor.

Text input field

Text input field with editor open

Text input field on collapsed block

Creation

JSON

{
  "type": "example_textinput",
  "message0": "text input: %1",
  "args0": [
    {
      "type": "field_input",
      "name": "FIELDNAME",
      "text": "default text",
      "spellcheck": false
    }
  ]
}

JavaScript

Blockly.Blocks['example_textinput'] = {
  init: function() {
    this.appendDummyInput()
        .appendField("text input:")
        .appendField(new Blockly.FieldTextInput('default text'),
            'FIELDNAME');
  }
};

The text input constructor takes in an optional value and an optional validator. The value should cast to a string. If it is null or undefined, an empty string will be used.

The JSON definition also allows you to set the spellcheck option.

Serialization and XML

JSON

The JSON for a text input field looks like so:

{
  "fields": {
    "FIELDNAME": "text"
  }
}

Where FIELDNAME is a string referencing a text input field, and the value is the value to apply to the field. The value follows the same rules as the constructor value.

XML

The XML for a text input field looks like so:

<field name="FIELDNAME">text</field>

Where the field's name attribute contains a string referencing a text input field, and the inner text is the value to apply to the field. The inner text value follows the same rules as the constructor value.

Customization

Spellcheck

The setSpellcheck function can be used to set whether the field spellchecks its input text or not.

Text input fields with and without spellcheck

Spellchecking is on by default.

This applies to individual fields. If you want to modify all fields change the Blockly.FieldTextInput.prototype.spellcheck_ property.

Creating a text input validator

Note: For information on validators in general see Validators.

A text input field's value is a string, so any validators must accept a string and return a string, null, or undefined.

Here is an example of a validator that removes all a characters from the string:

function(newValue) {
  return newValue.replace(/a/g, '');
}