FormModel

FormModel

new FormModel(data, optionsopt)

Source:

Class dealing with the XML Model of a form

Parameters:
Name Type Attributes Description
data FormDataObj

data object

options object <optional>

FormModel options

Properties
Name Type Attributes Description
full string <optional>

Whether to initialize the full model or only the primary instance.

Members

bindJsEvaluator :function

Source:

Creates a custom XPath Evaluator to be used for XPath Expresssions that contain custom OpenRosa functions or for browsers that do not have a native evaluator.

Type:
  • function

deprecatedID :string

Source:
Type:
  • string

instanceID :string

Source:
Type:
  • string

instanceName :string

Source:
Type:
  • string

types :object

Source:

Exposed types to facilitate extending with custom types

Type:
  • object

version :string

Source:
Type:
  • string

Methods

addOrdinalAttribute(repeat, firstRepeatInSeries)

Source:
Parameters:
Name Type Description
repeat Element

Set ordinal attribue to this node

firstRepeatInSeries Element

Used to know what the next ordinal attribute value should be. Defaults to repeat node.

addRepeat(repeatPath, repeatSeriesIndex, merge)

Source:

Adds a able instance node in a particular series of a repeat.

Parameters:
Name Type Description
repeatPath string

absolute path of a repeat

repeatSeriesIndex number

index of the repeat series that gets a new repeat (this is always 0 for non-nested repeats)

merge boolean

whether this operation is part of a merge operation (won't send dataupdate event, clears all values and will not add ordinal attributes as these should be provided in the record)

addRepeatComments(repeatPath)

Source:
Parameters:
Name Type Description
repeatPath string

path to repeat

addTemplate(repeatPath, repeat, empty)

Source:
Parameters:
Name Type Description
repeatPath string

path to repeat

repeat Element

Target node

empty boolean

whether to empty values before adding the template

convertPullDataFn(expr, selector, index) → {string}

Source:
Parameters:
Name Type Description
expr string

The XPath expression

selector string

context path

index number

index of context node

Returns:

Converted XPath expression

Type
string

createSession(id, sessObjopt)

Source:
Parameters:
Name Type Attributes Description
id string

Instance ID

sessObj object <optional>

session object

determineIndex(element) → {number}

Source:

Determines the index of a repeated node amongst all nodes with the same XPath selector

Parameters:
Name Type Description
element Element

Target node

Returns:

Determined index

Type
number

evaluate(expr, resTypeStropt, selectoropt, indexopt, tryNativeopt) → {number|string|boolean|Array.<Element>}

Source:

Evaluates an XPath Expression using XPathJS_javarosa (not native XPath 1.0 evaluator)

This function does not seem to work properly for nodeset resulttypes otherwise: muliple nodes can be accessed by returned node.snapshotItem(i)(.textContent) a single node can be accessed by returned node(.textContent)

Parameters:
Name Type Attributes Description
expr string

The expression to evaluate

resTypeStr string <optional>

"boolean", "string", "number", "node", "nodes" (best to always supply this)

selector string <optional>

Query selector which will be use to provide the context to the evaluator

index number <optional>

0-based index of selector in document

tryNative boolean <optional>

Whether an attempt to try the Native Evaluator is safe (ie. whether it is certain that there are no date comparisons)

Returns:

The result

Type
number | string | boolean | Array.<Element>

extractFakeTemplates(repeatPaths)

Source:
Parameters:
Name Type Description
repeatPaths Array.<string>

repeat paths

extractTemplates()

Source:

Extracts all templates from the model and stores them in a Javascript object.

getMetaNode(localName) → {Element}

Source:
Parameters:
Name Type Description
localName string

node name without namespace

Returns:

node

Type
Element

getNamespacePrefix(namespace) → {string|undefined}

Source:
Parameters:
Name Type Description
namespace string

Target namespace

Returns:

Namespace prefix

Type
string | undefined

getNsResolver() → {Object}

Source:

Returns a namespace resolver with single lookupNamespaceURI method

Returns:

namespace resolver

Type
Object

getRemovalEventData()

Source:

Placeholder function meant to be overwritten

getRepeatCommentEl(repeatPath, repeatSeriesIndex) → {Element}

Source:
Parameters:
Name Type Description
repeatPath string

path to repeat

repeatSeriesIndex number

index of repeat series

Returns:

node

Type
Element

getRepeatCommentSelector(repeatPath) → {string}

Source:
Parameters:
Name Type Description
repeatPath string

path to repeat

Returns:

selector

Type
string

getRepeatCommentText(path) → {string}

Source:
Parameters:
Name Type Description
path string

path to repeat

Returns:

repeat comment text

Type
string

getRepeatSeries(repeatPath, repeatSeriesIndex) → {Array.<Element>}

Source:

Obtains a single series of repeat element;

Parameters:
Name Type Description
repeatPath string

The absolute path of the repeat.

repeatSeriesIndex number

The index of the series of that repeat.

Returns:

Array of all repeat elements in a series.

Type
Array.<Element>

getSecondaryInstance(id) → {Element|undefined}

Source:

For some unknown reason we cannot use doc.getElementById(id) or doc.querySelector('#'+id) in IE11. This function is a replacement for this specifically to find a secondary instance.

Parameters:
Name Type Description
id string

DOM element id.

Returns:

secondary instance XML element

Type
Element | undefined

getStr() → {string}

Source:

Obtains a cleaned up string of the data instance

Returns:

XML string

Type
string

getTemplateNodes() → {Array.<Element>}

Source:
Returns:

template nodes list

Type
Array.<Element>

getUpdateEventData()

Source:

Placeholder function meant to be overwritten

importNode(node, allChildren)

Source:

Alternative adoptNode on IE11 (http://stackoverflow.com/questions/1811116/ie-support-for-dom-importnode) TODO: remove to be replaced by separate IE11-only polyfill file/service

Parameters:
Name Type Description
node Element

Node to be imported

allChildren Array.<Node>

All children of imported Node

init() → {Array.<string>}

Source:

Initializes FormModel

Returns:

list of initialization errors

Type
Array.<string>

makeBugCompliant(expr, selector, index)

Source:

There is a huge historic issue (stemming from JavaRosa) that has resulted in the usage of incorrect formulae on nodes inside repeat nodes. Those formulae use absolute paths when relative paths should have been used. See more here: http://opendatakit.github.io/odk-xform-spec/#a-big-deviation-with-xforms

Tools such as pyxform also build forms in this incorrect manner. See https://github.com/modilabs/pyxform/issues/91 It will take time to correct this so makeBugCompliant() aims to mimic the incorrect behaviour by injecting the 1-based [position] of repeats into the XPath expressions. The resulting expression will then be evaluated in a way users expect (as if the paths were relative) without having to mess up the XPath Evaluator.

E.g. '/data/rep_a/node_a' could become '/data/rep_a[2]/node_a' if the context is inside the second rep_a repeat.

This function should be removed when we can reasonbly expect not many 'old XForms' to be in use any more.

Already it should leave proper XPaths untouched.

Parameters:
Name Type Description
expr string

The XPath expression

selector string

Selector of the (context) node on which expression is evaluated

index number

Index of the instance node with that selector

mergeXml(recordStr)

Source:

Merges an XML instance string into the XML Model

Parameters:
Name Type Description
recordStr string

The XML record as string

node(selectoropt, indexopt, filteropt) → {Nodeset}

Source:

Returns a new Nodeset instance

Parameters:
Name Type Attributes Description
selector string | null <optional>

simple path to node

index string | number | null <optional>

index of node

filter NodesetFilter | null <optional>

filter to apply

Returns:

Nodeset instance

Type
Nodeset

removeDuplicateEnketoNsDeclarations(xmlStr) → {string}

Source:
Parameters:
Name Type Description
xmlStr string

XML string

Returns:

XML string without duplicates

Type
string

removeOrdinalAttributes(el)

Source:

Removes all ordinal attriubetes from all applicable nodes

Parameters:
Name Type Description
el Element

Target node

replaceCurrentFn(expr, contextSelector) → {string}

Source:

Replaces current() with /absolute/path/to/node to ensure the context is shifted to the primary instance

Doing this here instead of adding a current() function to the XPath evaluator, means we can keep using the much faster native evaluator in most cases!

Root will be shifted later, and repeat positions are already injected into context selector.

Parameters:
Name Type Description
expr string

Original expression

contextSelector string

Context selector

Returns:

New expression

Type
string

replaceIndexedRepeatFn(expr, selector, index) → {string}

Source:

Replaces indexed-repeat(node, path, position, path, position, etc) substrings by converting them to their native XPath equivalents using [position() = x] predicates

Parameters:
Name Type Description
expr string

The XPath expression

selector string

context path

index number

index of context node

Returns:

Converted XPath expression

Type
string

replaceInstanceFn(expr) → {string}

Source:

Replace instance('id') with an absolute path Doing this here instead of adding an instance() function to the XPath evaluator, means we can keep using the much faster native evaluator in most cases!

Parameters:
Name Type Description
expr string

Original expression

Returns:

New expression

Type
string

replacePullDataFn(expr, selector, index) → {string}

Source:
Parameters:
Name Type Description
expr string

The XPath expression

selector string

context path

index number

index of context node

Returns:

Converted XPath expression

Type
string

replaceVersionFn(expr) → {string}

Source:
Parameters:
Name Type Description
expr string

The XPath expression

Returns:

Converted XPath expression

Type
string

setInstanceIdAndDeprecatedId()

Source:

Sets instance ID and deprecated ID

setNamespaces()

Source:

Set namespaces for all nodes

shiftRoot(expr) → {string}

Source:

Shift root to first instance for all absolute paths not starting with /model

Parameters:
Name Type Description
expr string

Original expression

Returns:

New expression

Type
string

throwParserErrors(xmlDoc, xmlStr)

Source:
Parameters:
Name Type Description
xmlDoc Document

XML Document

xmlStr string

XML string

trimValues()

Source:

Trims values of all Form elements