blockly > Field

Field class

Abstract class for an editable field.


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

Implements: IASTNodeLocationSvg, IASTNodeLocationWithBlock, IKeyboardAccessible, IRegistrable


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.


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. | | NBSP |



| (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 | | | SKIP_SETUP |



| 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
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) 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.
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.
isClickable() Check whether this field defines the showEditor_ function.
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.
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.
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().

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) 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.