Mike Gerwitz

Activist for User Freedom

diff options
Diffstat (limited to 'doc/program.texi')
1 files changed, 282 insertions, 0 deletions
diff --git a/doc/program.texi b/doc/program.texi
new file mode 100644
index 0000000..94a1e12
--- /dev/null
+++ b/doc/program.texi
@@ -0,0 +1,282 @@
+@c This document is part of the Liza Data Collection Framework manual.
+@c Copyright (C) 2017 R-T Specialty, LLC.
+@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
+ 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}.}
+@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.
+* Program UI::
+* Program XML::
+* Document Metadata:: Document-level data that cannot be modified by
+ the client.
+@end menu
+@node Program UI
+@section Program UI
+ 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}).
+* Group Styles:: Different ways of displaying groups of questions to
+ the user.
+@end menu
+@node Group Styles
+@subsection Group Styles
+ 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
+* 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
+ <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
+ ["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
+ ["string(field name)"]: [ "string(dapi name)", ... ]
+@end example
+@caption{Format of @code{mapis}.}
+@end float