blockly > Field

Field class

Abstract class for an editable field.

Signature:

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

Implements: IASTNodeLocationSvg, IASTNodeLocationWithBlock, IKeyboardAccessible, IRegistrable

Constructors

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

Properties

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.
DEFAULT_VALUE		T | null	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. | | NBSP |

readonly

static

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

readonly

static

| 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? |

Methods

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.
getSize()		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.
setValidator(handler)		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.