macros.texi (helpwanted): Add macro
parent
9403a1d29b
commit
00e2389a5f
246
doc/design.texi
246
doc/design.texi
|
@ -21,15 +21,15 @@ Liza is fundamentally a data collection framework@mdash{
|
||||||
The main components of the system are:
|
The main components of the system are:
|
||||||
|
|
||||||
@table @strong
|
@table @strong
|
||||||
@cindex Assertion
|
@cindex Assertions
|
||||||
@item Assertions
|
@item @ref{Assertions}
|
||||||
Basic validations against bucket data,
|
Basic validations against bucket data,
|
||||||
producing errors and manipulating control flow.
|
producing errors and manipulating control flow.
|
||||||
Invokes triggers to manipulate the UI and document.
|
Invokes triggers to manipulate the UI and document.
|
||||||
Assertions are compiled from Program sources.
|
Assertions are compiled from Program sources.
|
||||||
|
|
||||||
@cindex Bucket
|
@cindex Bucket
|
||||||
@item Bucket
|
@item @ref{Bucket}
|
||||||
The key/value store into which all document data are stored.
|
The key/value store into which all document data are stored.
|
||||||
Supports staging and rollback of data,
|
Supports staging and rollback of data,
|
||||||
processing deltas,
|
processing deltas,
|
||||||
|
@ -40,7 +40,7 @@ The main components of the system are:
|
||||||
A small sub-system for calculating bucket values from other values.
|
A small sub-system for calculating bucket values from other values.
|
||||||
|
|
||||||
@cindex Client
|
@cindex Client
|
||||||
@item Client Interface
|
@item @ref{Client}
|
||||||
Basic logic for navigating between steps,
|
Basic logic for navigating between steps,
|
||||||
prompting for user actions,
|
prompting for user actions,
|
||||||
display help text and basic document data,
|
display help text and basic document data,
|
||||||
|
@ -62,27 +62,27 @@ The main components of the system are:
|
||||||
and more.
|
and more.
|
||||||
|
|
||||||
@cindex Program
|
@cindex Program
|
||||||
@item Program
|
@item @ref{Program}
|
||||||
Internal representation of the program with delegation of events to
|
Internal representation of the Program with delegation of events to
|
||||||
the assertion system.
|
the assertion system.
|
||||||
Contains compiled representation of all steps, groups, questions,
|
Contains compiled representation of all steps, groups, questions,
|
||||||
assertions, metadata, and others.
|
assertions, metadata, and others.
|
||||||
|
|
||||||
@cindex Program, User Interface
|
@cindex Program, User Interface
|
||||||
@cindex User Interface, Program
|
@cindex User Interface, Program
|
||||||
@item Program UI
|
@item @ref{Program UI}
|
||||||
Rendering of elements specific to programs,
|
Rendering of elements specific to Programs,
|
||||||
such as steps, groups, and questions.
|
such as steps, groups, and questions.
|
||||||
This is the equivalent of an HTML form.
|
This is the equivalent of an HTML form.
|
||||||
Directly monitors the bucket to perform UI updates.
|
Directly monitors the bucket to perform UI updates.
|
||||||
|
|
||||||
@cindex Program, XML
|
@cindex Program, XML
|
||||||
@item Program XML
|
@item @ref{Program XML}
|
||||||
The source code for a program, in XML format.
|
The source code for a Program, in XML format.
|
||||||
|
|
||||||
@cindex Server
|
@cindex Server
|
||||||
@item Server
|
@item Server
|
||||||
Provides REST API for serving programs; saving data;
|
Provides REST API for serving Programs; saving data;
|
||||||
revalidating, filtering, and recalculating data;
|
revalidating, filtering, and recalculating data;
|
||||||
and other types of processing.
|
and other types of processing.
|
||||||
Code is shared with the client,
|
Code is shared with the client,
|
||||||
|
@ -90,9 +90,231 @@ The main components of the system are:
|
||||||
|
|
||||||
@cindex Type Validation
|
@cindex Type Validation
|
||||||
@cindex Validation, Type
|
@cindex Validation, Type
|
||||||
@item Type Validation
|
@item @ref{Validation,,Type Validation}
|
||||||
Validates and formats bucket values for specific field (question)
|
Validates and formats bucket values for specific field (question)
|
||||||
types.
|
types.
|
||||||
For example, a date field must be in a recognized date format,
|
For example, a date field must be in a recognized date format,
|
||||||
and will be normalized for display.
|
and will be normalized for display.
|
||||||
@end table
|
@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
|
||||||
|
|
|
@ -20,3 +20,10 @@
|
||||||
—
|
—
|
||||||
@end macro
|
@end macro
|
||||||
@end ifnottex
|
@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
|
||||||
|
|
Loading…
Reference in New Issue