employer
/
liza
1
0
Fork 0
Code Releases Activity

macros.texi (helpwanted): Add macro

master
Mike Gerwitz 2017-03-16 13:23:19 -04:00
parent 9403a1d29b
commit 00e2389a5f
2 changed files with 241 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

246
doc/design.texi
View File

@ -21,15 +21,15 @@ Liza is fundamentally a data collection framework@mdash{
The main components of the system are:
@table @strong
@cindex Assertion
@item Assertions
@cindex Assertions
@item @ref{Assertions}
Basic validations against bucket data,
producing errors and manipulating control flow.
Invokes triggers to manipulate the UI and document.
Assertions are compiled from Program sources.
@cindex Bucket
@item Bucket
@item @ref{Bucket}
The key/value store into which all document data are stored.
Supports staging and rollback of data,
processing deltas,
@ -40,7 +40,7 @@ The main components of the system are:
A small sub-system for calculating bucket values from other values.
@cindex Client
@item Client Interface
@item @ref{Client}
Basic logic for navigating between steps,
prompting for user actions,
display help text and basic document data,
@ -62,27 +62,27 @@ The main components of the system are:
and more.
@cindex Program
@item Program
Internal representation of the program with delegation of events to
@item @ref{Program}
Internal representation of the Program with delegation of events to
the assertion system.
Contains compiled representation of all steps, groups, questions,
assertions, metadata, and others.
@cindex Program, User Interface
@cindex User Interface, Program
@item Program UI
Rendering of elements specific to programs,
@item @ref{Program UI}
Rendering of elements specific to Programs,
such as steps, groups, and questions.
This is the equivalent of an HTML form.
Directly monitors the bucket to perform UI updates.
@cindex Program, XML
@item Program XML
The source code for a program, in XML format.
@item @ref{Program XML}
The source code for a Program, in XML format.
@cindex Server
@item Server
Provides REST API for serving programs; saving data;
Provides REST API for serving Programs; saving data;
revalidating, filtering, and recalculating data;
and other types of processing.
Code is shared with the client,
@ -90,9 +90,231 @@ The main components of the system are:
@cindex Type Validation
@cindex Validation, Type
@item Type Validation
@item @ref{Validation,,Type Validation}
Validates and formats bucket values for specific field (question)
types.
For example, a date field must be in a recognized date format,
and will be normalized for display.
@end table
More information about each can be found in their respective section.
@menu
* Assertions::
* Bucket::
* Client::
* Program::
* Program UI::
* Program XML::
* Validation::
@end menu
@node Assertions
@section Assertions
@helpwanted
@node Bucket
@section Bucket
@helpwanted
@menu
* Value Assignment:Bucket Assignment. Writing data to the Bucket.
@end menu
@c TODO
@node Bucket Assignment
@subsection Bucket Value Assignment
@helpwanted
@node Client
@section Client
@helpwanted
@menu
* Error Handling::
@end menu
@node Error Handling
@subsection Error Handling
There are three layers of error checking:@footnote{
Primarily for legacy reasons.
They are being consolodated as the system is touched.}
@enumerate
@item Required field checking@mdash{
}whether all required questions have been answered.
@item @ref{Validation,,Type Validation}@mdash{
}verify that questions contain valid data according to their
declared type.
@item @ref{Assertions}@mdash{
}arbitrary checks on data.
@end enumerate
Required fields fail serially@mdash{
}the system will notify the user of the required field,
and direct him/her to it (usually through scrolling).
@node Program
@section 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.
@node Program UI
@section Program UI
@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
@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.
@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
@node Program XML
@section Program XML
@helpwanted
@node Validation
@section Validation
@helpwanted
@menu
* Formatting Values::
@end menu
@node Formatting Values
@subsection Formatting Values
@cindex Question
@cindex Question, Value Formatting
@helpwanted

7
doc/macros.texi
View File

@ -20,3 +20,10 @@
—
@end macro
@end ifnottex
@c indicate that help is needed to produce docs
@macro helpwanted{}
@cindex TODO, Missing Docs
@emph{There's nothing here yet. Maybe you can help?}
@end macro