TextElementFactory

TextElementFactory - class to manage text inputs with autocomplete and hidden input support

Generated from source on 2026-08-26. Descriptions come from JSDoc in the file.
Re-run docs_scaffold when the code changes; hand edits are lost on regeneration

Source

• File: Now/js/TextElementFactory.js (2024 lines)
• Form: ES class

Public methods (40)

static applyInitialValuesInContainer(container)

After form data is loaded (values set from server), convert any inputs that have an ID value into display text by looking up the source. This is needed because options may have been set before form data was applied, or vice-versa.

static clearRelatedFields(instance)

Empty every element the last selection filled.

static detectFormat(data)

Detect whether the loaded data uses the new code-as-key format. Code format: top-level values are objects that carry a "name" property.

static escapeAttrValue(value)

Escape a value so it can be used inside an attribute selector.

static extractCustomConfig(element, def, dataset)

Read the autocomplete settings the element declares through data attributes.

static fillRelatedFields(instance, item)

Copy the selected item into the elements that match its property names. Only elements inside the same form are written to, so two forms on one page do not fill each other. Elements filled by the previous selection that this one does not cover are emptied, so no field keeps showing data belonging to an item that is no longer selected.

static getChildren(node)

Return the children of a node, stripping the reserved "name" metadata key. Only needed in code format where each non-leaf node has a {name, ...children} shape.

static getDependsParams(instance)

Get dependent field values as URL parameters

static getGroup(instance)

Find an instance’s group, using the form it sits in as the divider. An input outside any form joins the document.body group, so separate forms on one page keep their own independent hierarchies.

static getInstanceByLevelInGroup(instance, level)

Pick the instance at a given level in the same group.

static getInstancesInGroup(instance)

Every instance in the same group, ordered by hierarchy level.

static getLevelInGroup(instance)

An instance’s level within its group.

static handleReverseSelection(instance, key, value)

Fill every level from the result the user picked in a reverse search. Uses the data reverseSearch parked in _pendingReverseData.

static isReverseSearchSelection(instance)

Check whether this selection came from a reverse search.

static loadData(source)

Load the hierarchy data set into the cache shared across the class. Accepts either a variable name on window or the data itself, then works out whether it is the name form or the code form.

static loadFromAjax(instance, url, query = '')

Fetch options from an endpoint through HttpClient. window.http is required with no fallback — when it is missing an error is logged and the user is told through an alert to refresh the page.

static normalizeOptionValue(value)

Normalize one option into the standard {value, text} shape. The value is looked up as value → id → key, and the text as text → label → name, so differently-shaped API payloads work without conversion.

static normalizeSource(source)

Normalize source data into standard format: Array<{value: string, text: string}> Accepts: Array (objects or primitives), Map, plain Object, or null Returns: Array<{value: string, text: string}> or null

static onSelectionChange(changedInstance)

Clear the levels below when a level above changes. Picking a new province must drop the district and sub-district already chosen, otherwise the combination would be inconsistent.

static parseFillMap(fill)

Read the data-fill setting. Three notations are accepted: - "false" / "none" / "off" → auto-fill disabled for this input - list: "topic, price:unit_price" → field topic takes the item's topic property, field price takes its unit_price property - JSON: '{"topic":"topic","price":"unit_price"}' → same mapping With no data-fill at all the mapping is derived from the item itself: every property is written to the field of the same id or name. false when auto-fill is turned off, null when nothing is declared.

static populateFromOptions(element, optionsData, optionsKey)

Fill one input with options taken from a keyed data set.

static populateFromOptionsInContainer(container, optionsData)

Fill every input carrying data-options-key inside a container. Use it after injecting fresh markup, to populate everything in one pass.

static populateHierarchical(instance, data)

Populate dropdown with hierarchical search results

static readFromDatalist(element)

Read options from the <datalist> the input points at with list.

static register(instance)

Register an instance into its group and start loading data if none is loaded. Registration order is the hierarchy: whoever registers first sits higher.

static resolveFillEntries(instance, item)

Work out which fields the selected item should fill. An explicit data-fill map wins. Without one, the item's own properties are the map: each property fills the field carrying the same id or name, which lets the API decide what a selection fills without touching the markup.

static resolveFillTarget(container, name)

Find the element a fill target name refers to. The id is tried first — that is the element the page author sees — then the visible field, because an autocomplete target renames its own input to name_text and keeps the plain name on its hidden input; writing to the hidden one alone would leave stale text on screen.

static reverseSearch(instance, query, targetLevel, totalLevels)

Search from a lower level upward, filling the levels above automatically. The user can type a sub-district straight away without picking a province and district first; the levels above are filled in from the chosen result.

static search(instance, query)

Search one level’s options, narrowed by what the levels above have selected. The top level (level 0) searches everything; lower levels search only under the values their parents already picked.

static searchHierarchical(instance, query)

Hierarchical search using API endpoint Searches across all related hierarchical data and displays in format: "province => district => subdistrict"

static selectHierarchicalItem(instance, value, text)

Override selectItem for hierarchical selection Populates all related fields (province, district, subdistrict, zipcode) at once

static setFillValue(field, value)

Write one value into a target element. Every element type is handled: a checkbox is ticked by the truthiness of the value, a radio group selects the member whose value matches, a multiple select selects each value in a list, an enhanced field is written through its instance so its own display and hidden value stay in step, and an element that is not a form control receives text — which is how a read-only display node gets filled.

static setInitialValue(instance, initialValue)

Set the input’s initial value and find the text that matches it. The submitted value lives in the hidden input while the visible input shows the text, so the value-text pair has to be resolved from the source first.

static setValueByCode(instance, code)

Set a hierarchy input by code. - In code format: resolves code → display name for the visible field; stores code in the hidden input (the submitted value). - In name format (legacy): treats the value as a display name and sets both fields. - If data has not loaded yet the value is queued and applied once data arrives.

static setupAutocomplete(instance)

Attach the autocomplete system to the input.

static setupElement(instance)

Prepare the input with autocomplete and a hidden input holding the real value. Options set before the element was enhanced are held in data-pending-options and applied here.

static setupEventListeners(instance)

Attach the input handlers, building on ElementFactory.

static syncDataToGroups()

Spread the loaded cache to every group and clear the pending values. A value set before the data arrived waits in _pendingCodeValue and is applied here, so setting a value before loading finishes is never lost.

static unregister(instance)

Unregister an instance from its group (called on destroy).

static updateOptions(element, options)

Replace the input’s option list. Grouped options are flattened first.

Data attributes used

data-autocomplete · data-callback · data-dependent · data-depends · data-fill · data-formatter · data-hierarchical-data · data-hierarchy · data-key · data-level · data-options-key · data-pending-options · data-search-api · data-search-field · data-source

Depends on

DropdownPanel · ElementFactory · ElementManager · EventSystemManager · FormManager · HttpClient · Utils