FormDef class final

A parsed form: its controls, instances, binds, translations and submission settings.

Port of org.javarosa.core.model.FormDef. Phase 2 provides what the XForm parser builds; Phase 3 adds recalculation (the TriggerableDag), repeat insertion and deletion, constraints and preloads; navigation is added in Phase 4.

Inheritance

Available extensions

Constructors

FormDef(): Creates an empty form.

Properties

actionController → ActionController: Actions registered on this element, by event.
finalinherited
additionalAttributes → List<TreeElement>: Attributes of the control element not handled by the parser, kept verbatim (e.g. rows, odk:tag).
finalinherited
appearance ↔ String?: The appearance attribute.
getter/setter pairinherited
bind ↔ TreeReference?: The absolute reference this element is bound to (null for a trigger without ref).
getter/setter pairinherited
children → List<FormElement>: Child elements (empty for questions).
no setteroverride
dag → TriggerableDag: The dependency graph of the calculations and conditions.
no setter
deepChildCount → int: Number of questions at or below this element.
no setteroverride
defaultSubmission ↔ SubmissionProfile?: The default submission profile, if any.
getter/setter pair
elementsWithActionTriggeredByToplevelEvent → Set<FormElement>: Elements whose actions listen to top-level events.
no setter
evaluationContext → EvaluationContext: The evaluation context for the form's expressions: the instances, jr:itext, jr:choice-name and custom functions.
no setter
extras → Extras<Object>: Objects plugins attach to the form, at most one per type (e.g. ODK Collect's DynamicPreloadExtra and entities EntityFormExtra).
final
formXmlPath ↔ String?: Where the form XML came from, if known.
getter/setter pair
hashCode → int: The hash code for this object.
no setterinherited
hasMainInstance → bool: Whether the main instance has been set.
no setter
id ↔ int: A form-wide unique id assigned by the parser.
getter/setter pairinherited
labelInnerText ↔ String?: Literal label text (when not localized).
getter/setter pairinherited
lastSavedSrc ↔ String?: The jr://instance/last-saved source it was parsed with, if any.
getter/setter pair
localizer ↔ Localizer?: The translations, if the form has <itext>.
getter/setter pair
mainInstance ↔ FormInstance: The main instance.
getter/setter pair
name ↔ String?: The form name (<meta name> or the title).
getter/setter pair
nonMainInstances → Map<String, DataInstance>: All secondary instances by name.
no setter
outputFragments → List<XPathConditional>: The <output> expressions referenced as ${n} in labels and hints.
final
parseErrors → List<String>: Non-fatal errors found while parsing.
final
parseWarnings → List<String>: Warnings found while parsing.
final
preloader ↔ QuestionPreloader: The jr:preload handlers; replace or extend before initialize.
getter/setter pair
recordAudioListener ↔ RecordAudioListener?: Receives <odk:recordaudio> requests (replaces JavaRosa's static RecordAudioActions listener).
getter/setter pair
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
sourceXml ↔ String?: The XForm XML this form was parsed from (kept for the codec).
getter/setter pair
textId ↔ String?: The itext id of the label. A ;form suffix is stripped, as in JavaRosa.
getter/setter pairinherited
title ↔ String?: The form title (<h:title>).
getter/setter pair
triggerables → List<Triggerable>: The registered triggerables, in registration order.
no setter

Methods

addChild(FormElement child) → void: Adds child. Throws for questions.
override
addEventListener(void listener(EvaluationEvent event)) → void: Receives evaluation events (debugging and tracing). Port of JavaRosa's EventNotifier.
addFilterStrategy(FilterStrategy strategy) → void: Adds a predicate filter strategy tried before the built-in ones.
addFunctionHandler(XPathFunctionHandler handler) → void: Adds a custom XPath function available to the form's expressions.
additionalAttribute(String? namespace, String name) → String?: The value of additional attribute name in namespace, if present.
inherited
addListener(FormElementListener listener) → void: Registers listener (once).
inherited
addNonMainInstance(DataInstance instance) → void: Adds a secondary instance under its name.
addParseError(String error) → void: Adds a non-fatal parse error.
addParseWarning(String warning) → void: Adds a parse warning.
addSubmissionProfile(String id, SubmissionProfile profile) → void: Adds a submission profile with id.
addTriggerable(Triggerable triggerable) → Triggerable: Registers a triggerable, or returns an equal one already registered (whose context then covers both binds).
buildIndex(List<int> indexes, List<int> multiplicities, List<FormElement> elements) → FormIndex?: The index for the given path (multiplicities are kept for repeats only).
canCreateRepeat(TreeReference repeatRef, GroupDef repeat, int currentMultiplicity) → bool: Whether another instance of repeat can be added after currentMultiplicity instances at repeatRef: always, unless the repeat is fixed (noAddRemove), and for a jr:count repeat while the count is larger.
canCreateRepeatAt(TreeReference repeatRef, FormIndex repeatIndex) → bool: Whether a new instance of the repeat at repeatIndex can be added. Port of canCreateRepeat(TreeReference, FormIndex).
childAt(int i) → FormElement?: The child at i, or null if out of range.
inherited
childInstanceRef(FormIndex index) → TreeReference?: The instance reference of the element at index.
childInstanceRefOf(List<FormElement> elements, List<int> multiplicities) → TreeReference?: The instance reference of the last of elements, with the repeat instances given by multiplicities (other steps at multiplicity 0); null if the controls and binds are inconsistent.
collapseIndex(FormIndex index, List<int> indexes, List<int> multiplicities, List<FormElement> elements) → void: Appends the child indices, multiplicities (0 outside repeats) and elements along index to the lists.
copyItemsetAnswer(QuestionDef question, TreeElement targetNode, AnswerValue? data) → void: Deprecated <copy> itemsets: replaces the copies under targetNode with the subtrees of the selected choices (reusing existing copies of still-selected values). Port of copyItemsetAnswer.
createNewRepeat(FormIndex index) → void: Adds the repeat instance at index. Port of createNewRepeat.
createRepeatInstance(TreeReference repeatRef) → TreeElement: Adds a repeat instance at repeatRef (fully qualified, with the new instance's multiplicity) from the repeat's template, preloads it, fires jr-insert and odk-new-repeat, and evaluates what it affects.
deleteRepeat(FormIndex index) → FormIndex: Deletes the repeat instance containing index; returns the index of the deleted instance. Port of deleteRepeat(FormIndex).
deleteRepeatInstance(TreeReference deleteRef) → void: Removes the repeat instance at deleteRef, renumbers the following instances and re-evaluates what depended on it.
descendIntoRepeat(FormIndex index, int repIndex) → FormIndex: The index of instance repIndex of the repeat at index; -1 means the instance about to be created.
elementAt(FormIndex? index) → FormElement: The element at index (the form itself outside the form).
evaluateConstraint(TreeReference ref, AnswerValue? data) → bool: Whether data satisfies the constraint of the node at ref (no answer always does).
explodeIndex(FormIndex index) → List<FormElement>: The elements along index, top level first.
fillTemplateString(String template, TreeReference contextRef, [Map<String, Object?> variables = const {}]) → String: Replaces ${n} placeholders in template with the values of outputFragments, evaluated at contextRef.
finalizeTriggerables() → void: Orders the triggerables for evaluation; throws StateError naming the nodes involved when they depend on each other in a cycle.
hasAction(String name) → bool: Whether the form uses action element name.
initialize({required bool newInstance}) → void: Prepares the form for filling: initializes the instances, preloads a newInstance, picks the default language, fires the load actions and evaluates every calculation and condition.
isRepeatRelevant(TreeReference repeatRef) → bool: Whether the repeat instance at repeatRef is relevant: its own relevance condition, its parent's relevance and its template's.
loadXmlInstance(String instanceXml, {AnswerResolver resolver = defaultAnswerResolver}) → void: Available on FormDef, provided by the XFormInstanceLoading extension
Replaces the main instance with the saved instance instanceXml (typed against the form). Port of XFormParser.loadXmlInstance.
localeChanged(String locale, Localizer localizer) → void: Called when the current locale of localizer becomes locale.
override
nonMainInstance(String name) → DataInstance?: The secondary instance called name, if any.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners(int changes) → void: Notifies listeners of changes.
inherited
numRepetitions(FormIndex index) → int: The number of instances of the repeat at index.
postProcessInstance() → void: Finalization: fires xforms-revalidate and runs the preloads' finalization steps (such as timestamp end).
preloadInstance(TreeElement node) → void: Applies the jr:preload values to node and its descendants (templates excluded).
processSetValue(SetValueAction action, TreeReference? context) → TreeReference?: Performs a <setvalue> (port of SetValueAction.processAction).
publishEvent(EvaluationEvent event) → void: Sends event to the event listeners.
registerAction(String name) → void: Records that the form uses action element name.
registerElementWithActionTriggeredByToplevelEvent(FormElement e) → void: Records an element inside the body whose actions listen to top-level events.
removeEventListener(void listener(EvaluationEvent event)) → void: Stops listener from receiving evaluation events.
removeListener(FormElementListener listener) → void: Unregisters listener.
inherited
replaceChildAt(int i, FormElement child) → void: Replaces child i.
saveActionValue(TreeReference ref, String text) → void: Stores an action-provided text (e.g. a location) at ref.
setAdditionalAttribute(String? namespace, String name, String? value) → void: Sets, adds or removes (with a null value) an additional attribute.
inherited
setAnswer(AnswerValue? value, TreeReference ref) → void: Sets the answer at ref without re-evaluating anything.
setValue(AnswerValue? value, TreeReference ref, {bool midSurvey = true}) → void: Sets value at ref, re-evaluates what depends on it and, when the value changed, fires the question's xforms-value-changed actions.
submissionProfile([String? id]) → SubmissionProfile?: The submission profile with id, or the default one.
toString() → String: A string representation of this object.
override
triggerTriggerables(TreeReference ref) → Set<Triggerable>: Re-evaluates what depends on the node at ref; returns the triggerables evaluated.
validate({bool markCompleted = true}) → ValidateOutcome?: Available on FormDef, provided by the FormDefValidation extension
Re-answers every relevant question with its current answer (running required and constraint checks); the first failure, or null when the form is valid. Port of FormDef.validate / TriggerableDag.validate.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

findQuestionByRef(TreeReference ref, FormElement element) → QuestionDef?: The question bound to ref under element (repeat-agnostic when element is the form).
getAbsRef(TreeReference? ref, TreeReference parentRef) → TreeReference: ref anchored to parentRef (which must be absolute); a missing ref (a <group> without binding) means the parent itself.
updateItemsetReferences(List<FormElement> children) → void: Computes itemset references for all questions under children.