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
|
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:
- ODK Collect starts supporting an instanceID preload item (or automatic handling of meta->instanceID without binding)
- Pyxforms changes the instanceID binding from calculate to preload (or without binding)
- 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 |