283 lines
8.8 KiB
Plaintext
283 lines
8.8 KiB
Plaintext
@c This document is part of the Liza Data Collection Framework manual.
|
|
@c Copyright (C) 2017 R-T Specialty, LLC.
|
|
@c
|
|
@c Permission is granted to copy, distribute and/or modify this document
|
|
@c under the terms of the GNU Free Documentation License, Version 1.3
|
|
@c or any later version published by the Free Software Foundation;
|
|
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
|
@c Texts. A copy of the license is included in the section entitled ``GNU
|
|
@c Free Documentation License''.
|
|
|
|
|
|
@node Program
|
|
@chapter Program
|
|
@maintstart
|
|
@footnote{
|
|
The @code{Program} class was one of the first prototypes created,
|
|
and has evolved poorly with the rest of the system.
|
|
It is the base class for all compiled programs,
|
|
and it glues together too many other systems with a terrible
|
|
API and little to no encapsulation.
|
|
|
|
With that said, it is one of the least touched classes (thus its
|
|
state); developers rarely have the need to touch @code{Program}.}
|
|
@maintend
|
|
|
|
|
|
@cindex Program
|
|
The @dfn{Program} is a declarative representation of an entire system.
|
|
It is the highest level of abstraction from a data perspective.
|
|
The user observes and interacts with a Program using the
|
|
@ref{Program UI,,Program@tie{}UI}.
|
|
|
|
@cindex Program, XML
|
|
Programs contain a lot of metadata that is not in a convenience
|
|
human-readable (or modifiable) format,
|
|
some of which are redundant.
|
|
Programs are ideally compiled from a @ref{Program XML,,Program@tie{}XML}
|
|
document.
|
|
|
|
@menu
|
|
* Program UI::
|
|
* Program XML::
|
|
* Document Metadata:: Document-level data that cannot be modified by
|
|
the client.
|
|
@end menu
|
|
|
|
|
|
@node Program UI
|
|
@section Program UI
|
|
@maintenance{
|
|
The @code{Ui} class,
|
|
in addition to @srcref{src/client/Client,Client} (@pxref{Client}),
|
|
represent the two monoliths of the system.
|
|
This mediates all UI-related tasks,
|
|
and still has far too many concerns with far too many
|
|
dependencies.
|
|
Code is to be extracted out of this class as it is touched.
|
|
}
|
|
|
|
|
|
@cindex Program, User Interface
|
|
@cindex User Interface, Program
|
|
The @dfn{Program UI} renders a @ref{Program} as a form.
|
|
|
|
@cindex Step
|
|
@cindex Group
|
|
At the highest level,
|
|
steps are rendered in a tab-like manner,
|
|
above the main form content.
|
|
A step contains groups,
|
|
which in turn contain elements such as questions.
|
|
Groups are delimited in some manner defined by their style
|
|
(@pxref{Group Styles}).
|
|
|
|
@cindex Question
|
|
@cindex Question, Value Formatting
|
|
@cindex Bucket, Updating
|
|
Questions are rendered as form fields.
|
|
Any time the respective @ref{Bucket} field is changed,
|
|
the form field is updated to reflect those changes,
|
|
after having first been formatted with the appropriate validator
|
|
(@pxref{Formatting Values}).
|
|
When a question is changed by the user,
|
|
the value is expected to be propagated to the Bucket
|
|
(@pxref{Bucket Assignment}).
|
|
|
|
@cindex Navigation Bar
|
|
@cindex User Interface, Navigation Bar
|
|
@cindex User Interface, Button Navigation
|
|
Navigation between steps can be done via the
|
|
@dfn{Navigation Bar} above the step@tie{}content,
|
|
or using ``Go@tie{}Back'' and ``Continue'' buttons at the foot of the
|
|
step@tie{}content.
|
|
|
|
@cindex Sidebar
|
|
A @dfn{Sidebar} is rendered adjacent to the step content.
|
|
It displays the name of the Program,
|
|
as well as configurable metadata (usually through the @samp{sidebar}
|
|
node of the @ref{Program XML,,Program@tie{}XML}).
|
|
It also displays question help text (also configured through the XML)
|
|
and any error messages (@pxref{Error Handling}).
|
|
|
|
@menu
|
|
* Group Styles:: Different ways of displaying groups of questions to
|
|
the user.
|
|
@end menu
|
|
|
|
|
|
@node Group Styles
|
|
@subsection Group Styles
|
|
@refactor{
|
|
Some group styles still use jQuery;
|
|
they should be modified to use modern formatters and Liza DOM
|
|
abstractions (see @srcrefraw{src/ui/field}
|
|
and @srcrefraw{src/ui/styler}).}
|
|
|
|
@cindex Group, Styling
|
|
Groups support a number of @dfn{group styles} that determine how
|
|
they are delimited from other groups;
|
|
how the elements they contain are rendered and laid out;
|
|
and how multiple indexes are displayed, added, and removed.
|
|
A list of available styles is detailed in @ref{t:group-styles}.
|
|
|
|
@float Table, t:group-styles
|
|
@multitable @columnfractions 0.15 0.65 0.10 0.10
|
|
@headitem Name @tab Description @tab Multi-Index? @tab Add/Remove Index?
|
|
|
|
@item @samp{default}
|
|
@tab
|
|
Groups are unstyled by default@mdash{
|
|
}they render elements as flat fields like a traditional form.
|
|
Only the first index of elements is rendered.
|
|
@tab@center N
|
|
@tab@center N
|
|
|
|
@item @samp{collapsetable}
|
|
@tab
|
|
Renders element label in the leftmost column like @samp{sidetable}.
|
|
Indexes are groups of rows delimited by headings,
|
|
which collapse the respective group of rows when clicked.
|
|
@tab@center Y
|
|
@tab@center Add
|
|
|
|
@item @samp{sidetable}
|
|
@tab
|
|
Renders elements as rows with label in the leftmost column rather
|
|
than the top row.
|
|
Each index is rendered as a column.
|
|
@tab@center Y
|
|
@tab@center Add
|
|
|
|
@item @samp{tabbedblock}
|
|
@tab
|
|
Each group is rendered as a block,
|
|
with each index rendered as a tab to the right of it.
|
|
Clicking a tab toggles the body content to the associated index.
|
|
Elements are rendered within the box.
|
|
@tab@center Y
|
|
@tab@center N
|
|
|
|
@item @samp{tabbed}
|
|
@tab
|
|
Like @samp{default},
|
|
but each index has a tab at the top of the group.
|
|
Clicking a tab toggles the body content to the associated index.
|
|
@tab@center Y
|
|
@tab@center Y
|
|
|
|
@item @samp{table}
|
|
@tab
|
|
A vanilla table with elements as columns,
|
|
their labels across the top row.
|
|
Each index is rendered in its own row.
|
|
@tab@center Y
|
|
@tab@center Y
|
|
@end multitable
|
|
@caption{Group styles and index support}
|
|
@end float
|
|
|
|
|
|
|
|
@node Program XML
|
|
@section Program XML
|
|
@helpwanted
|
|
|
|
@menu
|
|
* Specifying Predicates::
|
|
@end menu
|
|
|
|
|
|
@node Specifying Predicates
|
|
@subsection Specifying Predicates
|
|
|
|
Object predicates (@pxref{Predicate System}) are specified using the
|
|
@xmlattr{when} attribute of certain nodes.
|
|
It must contain a string of references understood by the system
|
|
(see domain of discourse, @ref{Predicate System}),
|
|
all of which much match for the predicate to be true.
|
|
|
|
@float Figure, f:pred-when
|
|
@example
|
|
<question id="describe" type="noyes"
|
|
label="Any special notes for this location?" />
|
|
|
|
<question id="vacant_desc" type="textarea"
|
|
when="q:describe vacant property"
|
|
label="Show only when a vacant property with the
|
|
question 'describe' non-empty and non-zero" />
|
|
@end example
|
|
@caption{Using the @xmlattr{when} attribute}
|
|
@end float
|
|
|
|
In @ref{f:pred-when} above,
|
|
question @samp{vacant_desc} will be applicable when @emph{all} of
|
|
the values of @samp{vacant}, @samp{property},
|
|
and@tie{}@samp{q:describe} are true.@footnote{
|
|
@xref{Predicate System} for what ``true'' means for a particular
|
|
variable in the domain of discourse.}
|
|
Within the context of the @progxml,
|
|
this concretely means that the classifications
|
|
@samp{vacant} and@tie{}@samp{property} are true,
|
|
and that the question @samp{describe} is answered ``yes''.
|
|
It reads as a sentence:
|
|
``@samp{vacant_desc}'' is applicable when we should @tie{}``describe
|
|
a vacant property''.
|
|
|
|
|
|
|
|
@node Document Metadata
|
|
@section Document Metadata
|
|
@dfn{Document metadata} are metadata that describe certain aspects of the document;
|
|
they are stored adjacent to the bucket in @samp{meta}@tie{}on the
|
|
document root.@footnote{
|
|
Terminology note: ``document'' and ``quote'' are the same thing;
|
|
the latter is transitioning to the former for generality.}
|
|
They should be used in place of a bucket field any time
|
|
the client has no business knowing about the data.
|
|
The @samp{meta} record is called the @dfn{Metabucket}.
|
|
|
|
@c don't use a dapi xref here; don't want to confuse the reader by
|
|
@c directing them away from this section before they continue reading
|
|
@tip{Metadata in the Metabucket should@tie{}@emph{not} be
|
|
directly populated by external systems@mdash{
|
|
}@dapi integration should be used instead (see below).}
|
|
|
|
Metadata can be populated using any@tie{}@dapiref@mdash{
|
|
}return data populate the Metabucket in the same way that they
|
|
populate the Bucket.
|
|
Definitions are stored in @code{meta.fields},
|
|
as shown in @ref{f:meta-fields}.
|
|
|
|
@float Figure, f:meta-fields
|
|
@example
|
|
"fields":@{
|
|
["string(name)": @{
|
|
"desc": "string",
|
|
"dapi": @{
|
|
"name": "string",
|
|
"map": @{
|
|
"string(dest field)": "string(source field)"
|
|
@}
|
|
@}
|
|
@}
|
|
@}
|
|
@end example
|
|
@caption{Format of @code{meta.fields}.}
|
|
@end float
|
|
|
|
Further, a key-value mapping of all bucket fields that@mdash{
|
|
}when modified,
|
|
need to result in a metadata API@tie{}call@mdash{
|
|
}are stored in the @code{mapis}@tie{}object;
|
|
this is shown in @ref{f:mapis}.
|
|
|
|
@float Figure, f:mapis
|
|
@example
|
|
"mapis":@{
|
|
["string(field name)"]: [ "string(dapi name)", ... ]
|
|
@}
|
|
@end example
|
|
@caption{Format of @code{mapis}.}
|
|
@end float
|