Attention

You’re viewing an old version of the L’ART Research Assistant documentation. The project has moved to https://lart.readthedocs.io/projects/research-assistant.

lart.forms

Form management utilities for the L’ART Research Client.

This namespace implements an extensive set of utility and helper functions which facilitate the implementation of forms for the L’ART Research Client.

Types

lart.forms.HTMLFormControlElement

type: HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement|RadioNodeList|HTMLMeterElement|HTMLProgressElement|HTMLOutputElement

A HTML form control element.

See also

• {@link lart.forms.HTMLFormControlElementTypes}

• {@link lart.forms.isHTMLFormControlElement}

Attributes

lart.forms.HTMLFormControlElementTypes

type: Set

Set containing all the types recognised as {@link lart.forms.HTMLFormControlElement}.

See also

• {@link lart.forms.HTMLFormControlElement}

• {@link lart.forms.isHTMLFormControlElement}

lart.forms._repeatBlockCounter

type: object

Counter to keep track of the number of repeats of a block.

This counter is used internally by {@link lart.forms.repeatBlock} to keep track of the number of repetitions for a repeated block.

lart.forms.conditionMatcherCondition

type: string

Enum of conditions for {@link lart.forms.conditionMatcherFactory}.

Five condition values are supported:

• EQUAL is equivaluent to actualValue == comparisonValue.

• NOT_EQUAL is equivalent to actualValue != comparisonValue.

• SMALLER is equivalent to actualValue < comparisonValue.

• GREATER is equivalent to actualValue > comparisonValue.

• MATCH is equivalent to actualValue.match(comparisonValue), where comparisonValue is a RegExp.

Functions

static lart.forms.autoFill(formOrId, delay=500)

Auto-fill a form with data from the URL’s query string/search params.

This function will wait for delay (in ms) before attempting to fill all HTMLInputElement, HTMLSelectElement, and HTMLTextAreaElement elements attached to the HTMLForm specified by formOrId.

If the query string/search params include a field called ${formId}.submit (where formId is the HTMLFormElement’s id attribute) and its value is either the string true or 1, then following another wait for delay ms an Event of type click is triggered on the first HTMLElement with a type=”submit” attribute attached to the HTMLForm.

Arguments:

• formOrId (HTMLFormElement|string) – A HTMLFormElement or a string which identifies a HTMLFormElement by its id attribute.

• delay (number) – The delay in milliseconds before autoFilling the form, and if applicable, again before submitting it.

Returns:

null –

static lart.forms.conditionMatcherFactory(controls, comparisonValue, condition)

Condition matching function factory.

Generates a function which checks whether the value of one or more form fields (specified by the nodes argument) evaluates to true or false compared to comparisonValue under condition.

comparisonValue should be a string or number for all condition types except {@linkcode lart.forms.conditionMatcherCondition.MATCH MATCH}, for which a RegExp object should be supplied.

If the condition is {@linkcode lart.forms.conditionMatcherCondition.MATCH MATCH} and the comparisonValue is not a RegExp object, it will be implicitly converted (i.e. comparisonValue = RegExp(comparisonValue);).

For the supported condition types, see {@link lart.forms.conditionMatcherCondition}.

Where controls is a HTMLForm or an iterable of more than a single HTMLElement, the functions is true whenever any of the HTMLFormControlElement elements in nodes satisfy the test condition.

Arguments:

• controls (HTMLFormElement|HTMLFormControlElement|Array.<HTMLFormControlElement>|Set.<HTMLFormControlElement>|HTMLCollection|NodeList) – The HTMLElement or NodeList of HTMLElement targets for which the generated function should check the provided condition.

• comparisonValue (String|Number|RegExp) – The value to which the target should be compared.

• condition (lart.forms.conditionMatcherCondition) – The type of condition to be applied in comparing the actual value of the node(s) to comparisonValue.

Returns:

lart.forms.conditionMatcherFactory~conditionMatcher – Returns a function taking no arguments, which returns true when the specified condition is met on at least one of the controls, and false otherwise.

See also

• {@link lart.forms.conditionMatcherCondition}

static lart.forms.conditionalDisable(observedControlName, targetElementOrId, value, condition)

Conditionally disable an element depending on the value of a form control.

Observe and conditionally set the disabled attribute on a HTMLElement depending on the value of a HTMLFieldControlElement.

Arguments:

• observedControlName (string) – The name of the {@link lart.forms.HTMLFormControlElement} whose value shall be observed.

• targetElementOrId (string) – The HTMLElement (or a string with its id attribute) which shall be conditionally disabled.

• value (string) – The value of the observed field at which the target element shall be disabled.

• condition (lart.forms.conditionMatcherCondition) – The condition used to compare value with the observed field’s value.

Returns:

null –

static lart.forms.conditionalDisplay(observedControlName, targetElementOrId, value, condition)

Conditionally display an element depending on the value of a form control.

Observe and conditionally set the display property on an HTMLElement depending on the value of an {@link lart.forms.HTMLFormControlElement}.

Arguments:

• observedControlName (string) – The name of the {@link lart.forms.HTMLFormControlElement} whose value shall be observed.

• targetElementOrId (string) – The HTMLElement (or a string with its id attribute) which shall be conditionally displayed.

• value (string) – The value of the observed field at which the target element shall be displayed.

• condition (lart.forms.conditionMatcherCondition) – The condition used to compare value with the observed field’s value.

Returns:

null –

static lart.forms.conditionalRequire(observedControlName, targetControlName, value, condition)

Conditionally require a form control depending on the value of a different control.

Observe and conditionally set the required attribute on a HTMLFieldControlElement depending on the value of a different HTMLFieldControlElement.

Arguments:

• observedControlName (string) – The name of the {@link lart.forms.HTMLFormControlElement} whose value shall be observed.

• targetControlName (string) – The name of the {@link lart.forms.HTMLFormControlElement} which shall be conditionally required.

• value (string) – The value of the observed field at which the target element shall be marked as required.

• condition (lart.forms.conditionMatcherCondition) – The condition used to compare value with the observed field’s value.

Returns:

null –

static lart.forms.getControlValue(controlElement)

Obtain the value of any {@link lart.forms.HTMLFormControlElement}.

Arguments:

• controlElement (lart.forms.HTMLFormControlElement) – The form control element for which the value should be optained.

Returns:

string|Array.<string>|null – The value of the passed form control element, if any. This will be a string for control elements with a single value (e.g. text input), an array of strings for those with multiple values (e.g. multiselect, checkboxes), or null if no value is set for the targeted {@link lart.forms.HTMLFormControlElement}.

static lart.forms.getElementByGreed(ref, root=document)

Greedily and flexibly try to get an element from the DOM.

This function allows for the flexible retrieval of an element from the DOM. It is primarily meant to be called inside other functions needing a reference to an element and there facilitates a more flexible calling pattern to those functions, allowing the element to be referenced either directly as a HTMLElement or RadioNodeList, or by its id or name attribute.

The procedure followed to find an element is as follows:

• If the passed argument is a HTMLElement or RadioNodeList, return it unchanged.

• If the passed argument is a string:

  • If root implements .getElementById, call root.getElementById(ref) and return the HTMLElement, if any.

  • If root implements .getElementsByName, call root.getElementsByName(ref). If the returned NodeList contains only HTMLInputElements of type radio which have both the same name and belong to the same HTMLForm (i.e. that form a radio group), then obtain the relevant RadioNodeList and return it. Otherwise, if the NodeList contains only a single HTMLElement, return it.

  • If root implements .querySelector, call root.querySelector(ref) and return the HTMLElement, if any. Note that this will be the first element inside root which satisfies the ref passed to querySelector.

• If no HTMLElement or RadioNodeList could be found following the above procedure, return null.

The root argument is optional, and can be either a Document root or a HTMLElement node to be used as the root. Note that HTMLElements don’t implement all the supported query methods and will typically default to the HTMLElement.querySelector method. Where root is not specified, it defaults to the global document object. The root is not used where the ref argument already is a HTMLElement or RadioNodeList.

Arguments:

• ref (HTMLElement|RadioNodeList|string) – A reference to the HTMLElement which should be obtained from the DOM. Can be either a JavaScript object directly representing it, or a string which identifies the element via its id or name attribute, or a string which identifies the element using the querySelector syntax.

• root (Document|HTMLElement) – A Document or HTMLElement to be used as the root for querying. Ignored if ref already is a HTMLElement or RadioNodeList.

Returns:

HTMLElement|RadioNodeList|null – Returns a single HTMLElement, a RadioNodeList, or null, depending on the first suitable item found in the DOM according to the algorithm described above.

static lart.forms.getFormControlElements(formOrId)

Get a pre-processed Set of a form’s control elements.

Convenience function, which obtains a HTMLFormElement’s {@link lart.forms.HTMLFormControlElement}s. In contrast to a HTMLFormControlsCollection, this function returns a Set in which each control is only present once, and where HTMLInputElements of type radio are represented by a RadioNodeList, rather than the individual HTMLInputElements themselves. Additionallly, HTMLFieldSetElements have been removed.

Arguments:

• formOrId (HTMLFormElement|string) – The HTMLFormElement (or a string with its id attribute) for which the HTMLFormControlCollection should be obtained.

Throws:

TypeError – Throws a TypeError if formOrId does not refer to a HTMLFormElement.

Returns:

Set.<lart.forms.HTMLFormControlElement> – Returns a Set of form control elements representing unique instances of form control elements in the targeted form.

static lart.forms.getFormData(formElementOrId)

Assemble all data from a specified form into an object of key-value pairs.

Arguments:

• formElementOrId (HTMLFormElement|string) – A form element to extract data from.

Returns:

object – - Returns a dictionary-like object of key-value pairs, where key is the name (or id as fallback) and value the value of each data field within the specified form.

static lart.forms.getRadioNodeList(radioElement)

Get the RadioNodeList associated with a radio input control.

Arguments:

• radioElement (HTMLInputElement) – The radio input control for which the RadioNodeList should be obtained.

Throws:

TypeError – Throws TypeError if the passed element is not a radio element, not attached to a form, or doesn’t have a name attribute.

Returns:

RadioNodeList –

static lart.forms.getSelectValues(selectElement)

Obtain the selected option values of an HTMLSelectElement.

Arguments:

• selectElement (HTMLSelectElement|string) – The HTMLSelectElement whose values shall be optained, or a string with the HTMLSelectElement’s id or name.

Throws:

TypeError – Throws a TypeError if elementOrId does not refer to an HTMLSelectElement.

Returns:

Array.<string> – A list of values of all selected options inside the select element.

static lart.forms.isHTMLFormControlElement(element)

Check whether an element is a {@link lart.forms.HTMLFormControlElement}.

Arguments:

• element (object) – The object to be checked for implementation of a relevant prototype.

Returns:

boolean – Returns true if the object is a {@link lart.forms.HTMLFormControlElement}, false otherwise.

See also

• {@link lart.formsHTMLFormControlElement}

• {@link lart.forms.HTMLFormControlElementTypes}

static lart.forms.isHTMLRadioInputElement(element)

Check whether a HTMLElement is a radio input control.

Arguments:

• element (HTMLElement) – The Element to be checked.

Returns:

boolean – Returns true if the element is a HTMLInputElement of type ‘radio’, false otherwise.

static lart.forms.pipeData(event, receiver)

Form submission event callback to validate a form and pipe data to another function.

Implements the functionality of {@link lart.forms.registerPipeline} following the triggering of a submit Event on the targeted form. See the documentation there for details of the behaviour.

Can also be called directly rather than as an Event callback to simulate the submission of a form. To do this you should create a new Event (typically of type submit) attached to a HTMLFormElement, and pass this along with the receiver. Note that doing this without actually triggering the event might bypass other registered event listeners.

Arguments:

• event (Event) – An event (typically ‘submit’) on a form element, e.g. as issued by .addEventListener().

• receiver (function) – A callable to which the form data will be passed as a dictionary.

Returns:

boolean – Returns true if the receiver function returns a truthy value, false if validation fails or the receiver function returns a falsy value.

static lart.forms.registerPipeline(formElementOrId, receiver)

Register a pipeline to submit a form’s data to a JavaScript function instead of an HTTP request.

Registers an event handler on the form specified by formElementOrId so that the data inside the form will be piped to the function specified by receiver and the further propagation of the submission event will be halted. Thus, no HTTP request will be issued and the page with the form won’t advance to the specified target or reload; if this is desired then the receiver of the data should manually direct the user to the new page.

Data will only be piped to the receiver if the form passes client-side validation via the JavaScript validation API. If you intend to also register a custom function to the submit event of the form to validate (e.g. requireValidation), then you should register the validation function before registering the pipeline, so that a failure to pipe an invalid form won’t block the validation function callback.

Normally the function as written here will be used to pipe data to a function exposed via Python’s eel module (marked @eel.expose in Python) via a JavaScript wrapper, but it could of course also be used in other scenarios where it is desirable to simply process the submitted data client-side.

After registering a pipeline callback, roughly the following behaviour ensues:

• A submit EvenListener is registered on the form.

• Following a submit event on the form, the default submittion/event’s default behaviour is prevented and propagation of the event is stopped.

• If the form fails to validate (i.e. if form.checkValidity() == false), then nothing happens.

• If the form validates, the form’s data is obtained via {@lart.forms.getData}.

• receiver is called with this data as the only argument.

Arguments:

• formElementOrId (HTMLFormElement|String) – A HTMLFormElement or its id for which data is to be piped to receiver.

• receiver (function) – The callback function that should receive the the form data upon submission and passed validation.

static lart.forms.repeatBlock(elementOrId, pattern)

Note

Deprecated: It’s better to use HTMLTemplateElements for this functionality.

Repeat a HTMLElement and use a regular expression to replace strings inside with a running counter.

Note: This function is now deprecated and should not be used in implementing any new functionality. Instead use the HTMLTemplateElement together with a slot and then insert copies of the template dynamically as required. This function will be removed from the library once all currently implemented functionality has been transitioned to the use of HTML templates.

Arguments:

• elementOrId (HTMLElement|string) – A HTMLElement or a string with an id or unique name attribute to identify a HTMLElement which shall be repeated. Usually this is a block-level element.

• pattern (RegExp) – A regular expression pattern to match which will be appended with a counter for each repetition of the block.

Returns:

null –

static lart.forms.requireValidation(novalidate)

Require all forms marked .needs-validation to pass client-side validation before submitting.

This function will register an event on all forms with the CSS class .needs-validation which prevents submission if there are any invalid fields according to the JavaScript Validation API. Forms will be marked by adding the class .was-validated after the first attempt to submit, which will enable Bootstrap to show custom user feedback messages.

If the option novalidate is set to true (default false) then the function will automatically set the attribute novalidate on all the forms it attaches to. This is needed to display Bootstrap form validation feedback instead of the browser’s built-in feedback, so should usually be specified true where Bootstrap-type user feedback messages are provided.

Arguments:

• novalidate (bool) – Whether to mark affected forms ‘novalidate’ to suppress browsers’ built-in feedback.

Returns:

null –

static lart.forms.validateRangeInputs(targetZoneElementOrId)

Add validation to HTMLInputElements of type range.

Attach a validation observer to all HTMLInputElements of type range which are children of the HTMLElement indicated by targetZoneElementOrId and which have the required attribute set.

The observed range inputs will pass (client-side) validation only if their slider has been moved at least once, irrespective of their value.

The method employed to do this involves setting a custom data attribute (data-lart-range-moved) on the HTMLInputElement and checking this as part of the elements custom validation. An event listener is attached to the element to monitor for input and adjust the data attribute accordingly. A MutatioObserver is further attached to the target zone to monitor for the insertion of any further range controls.

Arguments:

• targetZoneElementOrId (HTMLElement|String) – A HTMLElement, or a string refering to an id or name attribute identifying an HTMLElement which is the parent of the range input controls to be validated.

Returns:

null –