Mike Gerwitz

Activist for User Freedom

path: root/doc
diff options
authorMike Gerwitz <mike.gerwitz@rtspecialty.com>2018-02-06 11:33:44 -0500
committerMike Gerwitz <mike.gerwitz@rtspecialty.com>2018-02-06 12:09:32 -0500
commit6de77f02c060c90be21dd57a43c5ae94717a5e7a (patch)
tree0a1e9de850bd76a1ab63f6265b44536329e67558 /doc
parentffb709dbc48c383d9247e3d5bb46d4b94acb226a (diff)
doc: Begin documentation of DOM abstraction
* doc/program.texi (DOM Abstraction): New section.
Diffstat (limited to 'doc')
1 files changed, 104 insertions, 2 deletions
diff --git a/doc/program.texi b/doc/program.texi
index a806822..248b703 100644
--- a/doc/program.texi
+++ b/doc/program.texi
@@ -45,6 +45,7 @@ Programs are ideally compiled from a @ref{Program XML,,Program@tie{}XML}
@end menu
@node Program UI
@section Program UI
@@ -101,11 +102,13 @@ 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.
+* Group Styles:: Different ways of displaying groups of questions
+ to the user.
+* DOM Abstraction :: Representing and efficiently manipulating the DOM.
@end menu
@node Group Styles
@subsection Group Styles
@@ -187,6 +190,104 @@ A list of available styles is detailed in @ref{t:group-styles}.
+@node DOM Abstraction
+@subsection DOM Abstraction
+@cindex DOM
+@cindex Dojo, History
+@cindex jQuery
+@devnotice{jQuery is still used throughout parts of the framework and
+ is a performance bottleneck@mdash{
+ }it needs to be fully removed and replaced with this
+ DOM@tie{}abstraction.@footnote{
+ See @srcrefraw{src/ui/ElementStyler}.}}
+@trivia{Liza was conceived long before frameworks like React existed.
+ The implementation originally used Dojo because of its
+ broad widget set,
+ but it was later dropped because of extreme performance issues,
+ especially on the browsers of the day
+ (Liza had to support Internet Explorer@tie{}6!);
+ at one point,
+ certain steps took over a minute to load for the
+ most unfortunate of users.
+ jQuery was then used for various parts of the UI and for ease of
+ DOM manipulation,
+ because of the lack of good and universal DOM APIs back then.
+ It too became a bottleneck.
+ Using DOM@tie{}APIs is now easy with modern browsers.}
+Liza's DOM abstraction contains a couple of components:
+@cindex DOM, Context
+@cindex DOM, Field
+@item @dfn{DOM Fields} represent a field on the DOM.
+ Each field has a name and an index associated with the
+ DOM@tie{}node.
+ Nodes are cached in memory after first access and queue requests
+ during lookups to prevent stampeding.
+ Provides basic DOM operations,
+ including styling, containing row, and parent/sibling selecting.
+ See @srcref{src/ui/field}.
+@item @dfn{DOM Context} is a slice of the DOM used for restricting queries.
+ It can attach and detach sections of the DOM,
+ and be further split into a context hierarchy.
+ The @srcrefjs{src/ui/context,DomContext} provides field querying
+ (see @srcrefjs{src/ui/field,DomField}) and caching.
+ See @srcrefraw{src/ui/context}.
+@end itemize
+@tip{It is important to always use these abstractions for any portions
+ of the DOM under control of this abstraction;
+ otherwise, assumptions used for caching may result in
+ unintended behavior.}
+Using DOM contexts,
+ DOM operations can be restricted to small windows (for example,
+ groups or tabs),
+ further reducing the impact of DOM queries.
+The @dfn{root context} is represented by
+ @srcrefjs{src/ui/context,RootDomContext}@mdash{
+ }sub-contexts can be obtained by invoking @jsmethod{slice} on any
+ context,
+ which creates a new context from a subset of the parent.
+Detaching a parent will detach all child contexts.
+Contexts can be manipulated in memory before being re-attached.
+Detach a context from the DOM with @jsmethod{detach},
+ and attach with@tie{}@jsmethod{attach}.
+A context is aware of its parent and will re-attach itself to the DOM
+ in the correct place.
+A child context always attaches to the parent,
+ and so will not be rendered until the parent attaches.
+@tip{Always detach from the DOM before performing extensive manipulations;
+ this prevents the need for expensive re-painting until
+ manipulation is done,
+ at which point the context can be re-attached.}
+* Field Styling:: Styling @srcrefjs{src/ui/field,DomField}.
+@end menu
+@node Field Styling
+@subsubsection Field Styling
+@cindex Field, Styling
+@srcrefjs{src/ui/field,DomField} is styled using field stylers
+ (see @srcrefraw{src/ui/styler}).
+The two most notable stylers are
+ @srcrefjs{src/ui/field/ErrorFieldStyler} and
+ @srcrefjs{src/ui/field/NaFieldStyler},
+ which style fields in error and hide fields that are no applicable
+ respectively.
@node Program XML
@section Program XML
@@ -301,6 +402,7 @@ There is no limit to the number of groups that can share the same link.
fields in the link.}
@node Specifying Predicates
@subsection Specifying Predicates