diff --git a/doc/design.texi b/doc/design.texi index 3de2be8..3eecd40 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -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 diff --git a/doc/macros.texi b/doc/macros.texi index 0224276..a9dd018 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -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