blockly > Field

Field class

Abstract class for an editable field.


export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IASTNodeLocationWithBlock, IKeyboardAccessible, IRegistrable, ISerializable 

Implements: IASTNodeLocationSvg, IASTNodeLocationWithBlock, IKeyboardAccessible, IRegistrable, ISerializable


Constructor Modifiers Description
(constructor)(value, validator, config) Constructs a new instance of the Field class


Property Modifiers Type Description
borderRect_ protected SVGRectElement | null The rendered field's SVG border element.
clickTarget_ protected Element | null The element the click handler is bound to.
constants_ protected ConstantProvider | null Constants associated with the source block's renderer.
CURSOR string Mouse cursor style when over the hotspot that initiates the editor.

To overwrite the default value which is set in **Field**, directly update the prototype.

Example: FieldImage.prototype.DEFAULT_VALUE = null;

EDITABLE boolean Editable fields usually show some sort of UI indicating they are editable. They will also be saved by the serializer.
enabled_ protected boolean Can the field value be changed using the editor on an editable block?
fieldGroup_ protected SVGGElement | null The rendered field's SVG group element.
isDirty_ protected boolean Does this block need to be re-rendered?
maxDisplayLength number Maximum characters of text to display before adding an ellipsis.
name? string (Optional) Name of field. Unique within each block. Static labels are usually unnamed.



(not declared) Non-breaking space.
SERIALIZABLE boolean Serializable fields are saved by the serializer, non-serializable fields are not. Editable fields should also be serializable. This is not the case by default so that SERIALIZABLE is backwards compatible.
size_ protected Size



unique symbol A value used to signal when a field's constructor should *not* set the field's value or run configure_, and should allow a subclass to do that instead.
sourceBlock_ protected Block | null Block this field is attached to. Starts as null, then set in init.
textContent_ protected Text | null The rendered field's text content element.
textElement_ protected SVGTextElement | null The rendered field's SVG text element.
validator_ protected FieldValidator<T> | null Validation function called when user edits an editable field.
value_ protected T | null
visible_ protected boolean Is the field visible, or hidden due to the block being collapsed?


Method Modifiers Description

Updates the field to match the colour/style of the block.

Non-abstract sub-classes may wish to implement this if the colour of the field depends on the colour of the block. It will automatically be called at relevant times, such as when the parent block or renderer changes.

See the field documentation for more information, or FieldDropdown for an example.

bindEvents_() protected Bind events to the field. Can be overridden by subclasses if they need to do custom input handling.
configure_(config) protected Process the configuration map passed to the field.
createBorderRect_() protected Create a field border rect element. Not to be overridden by subclasses. Instead modify the result of the function inside initView, or create a separate function to call.
createTextElement_() protected Create a field text element. Not to be overridden by subclasses. Instead modify the result of the function inside initView, or create a separate function to call.
doClassValidation_(newValue) protected

Validate the changes to a field's value before they are set. See **FieldDropdown** for an example of subclass implementation.

**NOTE:** Validation returns one option between T, null, and undefined. **Field**'s implementation will never return undefined, but it is valid for a subclass to return undefined if the new value is compatible with T.

doClassValidation_(newValue) protected
doValueInvalid_(_invalidValue, _fireChangeEvent) protected Used to notify the field an invalid value was input. Can be overridden by subclasses, see FieldTextInput. No-op by default.
doValueUpdate_(newValue) protected Used to update the value of a field. Can be overridden by subclasses to do custom storage of values/updating of external things.
fromJson(_options) static

Subclasses should reimplement this method to construct their Field subclass from a JSON arg object.

It is an error to attempt to register a field subclass in the FieldRegistry if that subclass has not overridden this method.

getAbsoluteXY_() protected Return the absolute coordinates of the top-left corner of this field. The origin (0,0) is the top-left corner of the page body.
getBorderRect() protected Gets the border rectangle element.
getClickTarget_() protected The element to bind the click handler to. If not set explicitly, defaults to the SVG root of the field. When this element is clicked on an editable field, the editor will open.
getConstants() Get the renderer constant provider.
getDisplayText_() protected Get the text from this field to display on the block. May differ from getText due to ellipsis, and other formatting.
getFlipRtl() Returns whether or not we should flip the field in RTL.

Returns the height and width of the field.

This should *in general* be the only place render_ gets called from.

getSourceBlock() Get the block this field is attached to.
getSvgRoot() Gets the group element for this editable field. Used for measuring the size and for positioning.
getText_() protected A developer hook to override the returned text of this field. Override if the text representation of the value of this field is not just a string cast of its value. Return null to resort to a string cast.
getText() Get the text from this field. Override getText_ to provide a different behavior than simply casting the value to a string.
getTextContent() protected Gets the text content.
getTextElement() protected Gets the text element.
getTooltip() Returns the tooltip text for this field.
getValidator() Gets the validation function for editable fields, or null if not set.
getValue() Get the current value of the field.
initModel() Initializes the model of the field after it has been installed on a block. No-op by default.
initView() protected Create the block UI for this field.
isClickable() Check whether this field defines the showEditor_ function.
isClickableInFlyout(autoClosingFlyout) Check whether the field should be clickable while the block is in a flyout. The default is that fields are clickable in always-open flyouts such as the simple toolbox, but not in autoclosing flyouts such as the category toolbox. Subclasses may override this function to change this behavior. Note that isClickable must also return true for this to have any effect.
isCurrentlyEditable() Check whether this field is currently editable. Some fields are never EDITABLE (e.g. text labels). Other fields may be EDITABLE but may exist on non-editable blocks or be currently disabled.
isEnabled() Check whether this field's value can be changed using the editor when the source block is editable.
isFullBlockField() protected

Defines whether this field should take up the full block or not.

Be cautious when overriding this function. It may not work as you expect / intend because the behavior was kind of hacked in. If you are thinking about overriding this function, post on the forum with your intended behavior to see if there's another approach.

isSerializable() Check whether this field should be serialized by the XML renderer. Handles the logic for backwards compatibility and incongruous states.
isTabNavigable() Returns whether or not the field is tab navigable.
isVisible() Gets whether this editable field is visible or not.
loadLegacyState(callingClass, state) Loads the given state using either the old XML hooks, if they should be used. Returns true to indicate loading has been handled, false otherwise.
onLocationChange(_) Notifies the field that it has changed locations.
onMouseDown_(e) protected Handle a pointerdown event on a field.
onShortcut(_shortcut) Handles the given keyboard shortcut.
positionBorderRect_() protected Position a field's border rect after a size change.
positionTextElement_(xOffset, contentWidth) protected Position a field's text element after a size change. This handles both LTR and RTL positioning.
render_() protected

Used by getSize() to move/resize any DOM elements, and get the new size.

All rendering that has an effect on the size/shape of the block should be done here, and should be triggered by getSize().


A developer hook to reposition the WidgetDiv during a window resize. You need to define this hook if your field has a WidgetDiv that needs to reposition itself when the window is resized. For example, text input fields define this hook so that the input WidgetDiv can reposition itself on a window resize event. This is especially important when modal inputs have been disabled, as Android devices will fire a window resize event when the soft keyboard opens.

If you want the WidgetDiv to hide itself instead of repositioning, return false. This is the default behavior.

DropdownDivs already handle their own positioning logic, so you do not need to override this function if your field only has a DropdownDiv.

saveLegacyState(callingClass) protected Returns a stringified version of the XML state, if it should be used. Otherwise this returns null, to signal the field should use its own serialization.
setEnabled(enabled) Set whether this field's value can be changed using the editor when the source block is editable.
setSourceBlock(block) Attach this field to a block.
setTooltip(newTip) Sets the tooltip for this field.

Sets a new validation function for editable fields, or clears a previously set validator.

The validator function takes in the new field value, and returns validated value. The validated value could be the input value, a modified version of the input value, or null to abort the change.

If the function does not return anything (or returns undefined) the new value is accepted as valid. This is to allow for fields using the validated function as a field-level change event notification.

setValue(newValue, fireChangeEvent) Used to change the value of the field. Handles validation and events. Subclasses should override doClassValidation_ and doValueUpdate_ rather than this method.
showEditor_(_e) protected A developer hook to create an editor for the field. This is no-op by default, and must be overriden to create an editor.
updateEditable() Add or remove the UI indicating if this field is editable or not.
updateSize_(margin) protected Updates the size of the field based on the text.