blockly > Field

Field class

Abstract class for an editable field.

Signature:

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

Implements: IASTNodeLocationSvg, IASTNodeLocationWithBlock, IKeyboardAccessible, IRegistrable, ISerializable

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	static readonly	(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	static readonly	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
applyColour()		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)	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.
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().
repositionForWindowResize()		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.
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, 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.