Form

Form

new Form(formEl, data, optionsopt)

Source:

Class: Form

Most methods are prototype method to facilitate customizations outside of enketo-core.

Parameters:
Name Type Attributes Description
formEl Element

HTML form element (a product of Enketo Transformer after transforming a valid ODK XForm)

data FormDataObj

Data object containing XML model, (partial) XML instance-to-load, external data and flag about whether instance-to-load has already been submitted before.

options object <optional>

form options

Properties
Name Type Attributes Description
printRelevantOnly boolean <optional>

If printRelevantOnly is set to true or not set at all, printing the form only includes what is visible, ie. all the groups and questions that do not have a relevant expression or for which the expression evaluates to true.

language string <optional>

Overrides the default languages rules of the XForm itself. Pass any valid and present-in-the-form IANA subtag string, e.g. ar.

Members

(static) requiredTransformerVersion :string

Source:
Default Value:
  • 2.0.0

Static property with required enketo-transformer version.

Type:
  • string

action :string

Source:
Type:
  • string

constraintAttributes :Array.<string>

Source:

To facilitate forks that support multiple constraints per question

Type:
  • Array.<string>

constraintClassesInvalid :Array.<string>

Source:

To facilitate forks that support multiple constraints per question

Type:
  • Array.<string>

currentLanguage :string

Source:
Type:
  • string

deprecatedID :string

Source:
Type:
  • string

editStatus :boolean

Source:
Type:
  • boolean

encryptionKey :string

Source:
Type:
  • string

evaluationCascade :Array

Source:
Type:
  • Array

evaluationCascadeAdditions :Array

Source:
Type:
  • Array

id :string

Source:
Type:
  • string

instanceID :string

Source:
Type:
  • string

instanceName :string

Source:
Type:
  • string

languages :Array.<string>

Source:
Type:
  • Array.<string>

method :string

Source:
Type:
  • string

recordName :string

Source:
Type:
  • string

surveyName :string

Source:
Type:
  • string

version :string

Source:
Type:
  • string

Methods

addModule(module) → {object}

Source:

Returns a module and adds the form property to it.

Parameters:
Name Type Description
module object

Enketo Core module

Returns:

updated module

Type
object

blockPageNavigation()

Source:

Blocks page navigation for a short period. This can be used to ensure that the user sees a new error message before moving to another page.

clearNonRelevant()

Source:

Clears non-relevant values.

filterRadioCheckSiblings(controls) → {Array.<Element>}

Source:
Parameters:
Name Type Description
controls Array.<Element>

radiobutton/checkbox HTML input elements

Returns:

filtered controls without any sibling radiobuttons and checkboxes (only the first)

Type
Array.<Element>

getDataStr(includeopt) → {string}

Source:

Obtains a string of primary instance.

Parameters:
Name Type Attributes Description
include Object <optional>

Optional object items to exclude if false

Returns:

XML string of primary instance

Type
string

getDataStrWithoutIrrelevantNodes() → {string}

Source:

Obtains the XML primary instance as string without nodes that have a relevant that evaluates to false.

Though this function may be slow it is slow when it doesn't matter much (upon saving). The alternative is to add some logic to relevant.update to mark irrelevant nodes in the model but that would slow down form loading and form traversal when it does matter.

Returns:

Data string

Type
string

getGoToTarget(path) → {null|Element}

Source:
Parameters:
Name Type Description
path string

path to HTML form control

Returns:

HTML question element

Type
null | Element

getModelValue($control) → {string|undefined}

Source:
Parameters:
Name Type Description
$control jQuery

HTML form control

Returns:

Value

Type
string | undefined

getQuerySelectorsForLogic(filter, attr, nodeName) → {string}

Source:

Crafts an optimized selector for element attributes that contain an expression with a target node name.

Parameters:
Name Type Description
filter string

The filter to use

attr string

The attribute to target

nodeName string

The XML nodeName to find

Returns:

The selector

Type
string

getRelatedNodes(attr, filteropt, updated) → {jQuery}

Source:

Finds nodes that have attributes with XPath expressions that refer to particular XML elements.

Parameters:
Name Type Attributes Description
attr string

The attribute name to search for

filter string <optional>

The optional filter to append to each selector

updated UpdatedDataNodes

object that contains information on updated nodes

Returns:
  • A jQuery collection of elements
Type
jQuery

goTo(xpath) → {Array.<string>}

Source:
Parameters:
Name Type Description
xpath string

simple path to question

Returns:

A list of errors originated from goToTarget. Empty if everything went fine.

Type
Array.<string>

goToTarget(target) → {boolean}

Source:

Scrolls to an HTML question or group element, flips to the page it is on and focuses on the nearest form control.

Parameters:
Name Type Description
target HTMLElement

An HTML question or group element to scroll to

Returns:

whether target found

Type
boolean

grosslyViolateStandardComplianceByIgnoringCertainCalcs()

Source:

See https://groups.google.com/forum/?fromgroups=#!topic/opendatakit-developers/oBn7eQNQGTg and http://code.google.com/p/opendatakit/issues/detail?id=706

This is using an aggressive name attribute selector to also find e.g. name="/../orx:meta/orx:instanceID", with ANY namespace prefix.

Once the following is complete this function can and should be removed:

  1. ODK Collect starts supporting an instanceID preload item (or automatic handling of meta->instanceID without binding)
  2. Pyxforms changes the instanceID binding from calculate to preload (or without binding)
  3. Formhub has re-generated all stored XML forms from the stored XLS forms with the updated pyxforms

init() → {Array.<string>}

Source:

Function: init

Initializes the Form instance (XML Model and HTML View).

Returns:

List of initialization errors.

Type
Array.<string>

isValid(node) → (non-null) {boolean}

Source:

Checks whether the question is not currently marked as invalid. If no argument is provided, it checks the whole form.

Parameters:
Name Type Description
node Element

form control HTML element

Returns:

Whether the question/form is not marked as invalid.

Type
boolean

pathToAbsolute(targetPath, contextPath) → {string}

Source:
Parameters:
Name Type Description
targetPath string

simple relative or absolute path

contextPath string

absolute context path

Returns:

absolute path

Type
string

replaceChoiceNameFn(expr, resTypeStr, context, index, tryNative) → {string}

Source:

Implements jr:choice-name TODO: this needs to work for all expressions (relevants, constraints), now it only works for calculated items Ideally this belongs in the form Model, but unfortunately it needs access to the view

Parameters:
Name Type Description
expr string

XPath expression

resTypeStr string

type of result

context string

context path

index number

index of context

tryNative boolean

whether to try the native evaluator, i.e. if there is no risk it would create an incorrect result such as with date comparisons

Returns:

updated expression

Type
string

resetView() → {Element}

Source:

Restores HTML form to pre-initialized state. It is meant to be called before re-initializing with new Form ( .....) and form.init() For this reason, it does not fix event handler, $form, formView.$ etc.! It also does not affect the XML instance!

Returns:

the new form element

Type
Element

setAllVals($group, groupIndex)

Source:

Uses current state of model to set all the values in the form. Since not all data nodes with a value have a corresponding input element, we cycle through the HTML form elements and check for each form element whether data is available.

Parameters:
Name Type Description
$group jQuery

group of elements for which form controls should be updated (with current model values)

groupIndex number

index of the group

setEventHandlers()

Source:

A big function that sets event handlers.

setInvalid(control, typeopt)

Source:

Marks a question as invalid in the form UI.

Parameters:
Name Type Attributes Description
control Element

form control HTML element

type string <optional>

One of "constraint", "required" and "relevant".

setValid(control, typeopt)

Source:

Removes an invalid mark on a question in the form UI.

Parameters:
Name Type Attributes Description
control Element

form control HTML element

type string <optional>

One of "constraint", "required" and "relevant".

updateValidityInUi(control, result)

Source:
Parameters:
Name Type Description
control *

form control HTML element

result *

result object obtained from Nodeset.validate

validate()

Source:

Alias of validateAll

validateAll() → {Promise}

Source:

Clears all non-relevant question values if necessary and then validates all enabled input fields after first resetting everything as valid.

Returns:

wrapping {boolean} whether the form contains any errors

Type
Promise

validateContent($container) → {Promise}

Source:

Validates all enabled input fields in the supplied container, after first resetting everything as valid.

Parameters:
Name Type Description
$container jQuery

HTML container element inside which to validate form controls

Returns:

wrapping {boolean} whether the container contains any errors

Type
Promise

validateInput(control) → {Promise.<(undefined|ValidateInputResolution)>}

Source:

Validates question values.

Parameters:
Name Type Description
control Element

form control HTML element

Returns:

resolves with validation result

Type
Promise.<(undefined|ValidateInputResolution)>

validationUpdate(updated)

Source:

This re-validates questions that have a dependency on a question that has just been updated.

Note: it does not take care of re-validating a question itself after its value has changed due to a calculation update!

Parameters:
Name Type Description
updated UpdatedDataNodes

object that contains information on updated nodes