Number fields

  • A number field stores a number as its value and a string as its text.

  • Constraints like minimum value, maximum value, and precision can be set for number fields.

  • Number fields can be created using JSON or JavaScript.

  • Number field values can be serialized in JSON or XML format.

  • Validators can be used with number fields to modify or restrict the input.

A number field stores a number as its value, and a string as its text. Its value is always a valid number as defined by the constraints given to the field at creation; its text could be any string entered into its editor.

Number field

A block with the label "number:" and a number field set to 100.

Number field with editor open

The same block with the field being edited.

Number field on collapsed block

The same block after being collapsed. It has the label "number: 100" and a jagged right edge to show it is collapsed.

Creation

JSON

{
  "type": "example_number",
  "message0": "number: %1",
  "args0": [
    {
      "type": "field_number",
      "name": "FIELDNAME",
      "value": 100,
      "min": 0,
      "max": 100,
      "precision": 10
    }
  ]
}

JavaScript

Blockly.Blocks['example_number'] = {
  init: function() {
    this.appendDummyInput()
        .appendField("number:")
        .appendField(new Blockly.FieldNumber(100, 0, 100, 10), 'FIELDNAME');
  }
};

The number constructor takes in the following:

The value should cast to a number. If it does not 0 will be used.

Serialization

JSON

The JSON for a number field looks like so:

{
  "fields": {
    "FIELDNAME": 0
  }
}

Where FIELDNAME is a string referencing a number 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 number field looks like so:

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

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

Constraints

Constraints can be set in the field definition, or by using the setConstraints function.

Minimum value

The min value sets the smallest/most-negative value the field is allowed to contain.

Maximum value

The max value sets the largest/most-positive value the field is allowed to contain.

Rounding

The precision rounds the value to the nearest multiple of precision. This can be used to make the field only accept multiples of .01, 10, 42, etc.

Common constraints

Positive numbers

To force your field to only accept positive numbers, set the min value to 1.

Integers

To force your field to only accept integers, set the precision to 1.

Creating a number validator

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

Here is an example of a validator that changes the value to be either 0 or 1 depending on if the value was odd or even.

function(newValue) {
  return newValue % 2;
}

An animated GIF showing the validator at work. When the user types 10 and clicks elsewhere, the field is set to 0. When the user types 11 and clicks elsewhere, the field is set to 1.