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:
|
||||
|
||||
@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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue