A generic object maintenance user interface for Maintainable types.
Dataview provides a complete web-based user interface without the need
to code any HTML. Instead, a simple XML file is used to specify
properties necessary to construct a user interface for a type.
For more information, see the
Dataview DTD.
Type Requirements
To be maintainable through this facility, a type must satisfy the
following requirements:
- It must be a JavaBean, complying with all JavaBean naming
conventions.
- It must be {@link gov.va.med.term.access.maint.util.Maintainable Maintainable}.
- It must be gov.va.med.term.access.types.Referenceable.
- All attributes of user-defined type must be
gov.va.med.term.access.types.Referenceable.
The best way to understand how to construct types that can be managed
by Dataview is to define types using Datagen.
Major User Interface Concepts
- Meaningful URL Scheme
- Resources available on the web should be available through
meaningful and permanent URLs. Consequently Dataview uses a meaningful
URL scheme. The Dataview URL scheme is:
<function>/<Type>{/<object-id>{/<attr-name>}}*
The Dataview URL scheme has these essential properties:
- It provides a permanent address for each operation on each resource.
- It is usable, because it is short, descriptive, easy to enter, and
easy to learn.
- It is technology-independent (i.e. no '.jsp').
- Canonical HTTP Interaction Patterns
-
GET is used only for queries. GET requests are idempotent.
POST is used only for commands.
If a POST request cannot be satisfied (usually because of a user
error), the response to the POST is the form submission page with
error information.
If a POST request is successful, the response to the POST is an HTTP
redirect, so that the next page visible in the browser is the result of
an HTTP GET.
Form processing employs both of these patterns, as shown in
this sequence diagram.
- User Interface Configurability
-
The appearance of the Dataview web application user interface is fully
configurable using CSS. Applications may substitute their own style
sheet by placing it in the classpath before the Dataman JAR at
/gov/va/med/term/access/maint/ui/dataview/content/style.css.
- User Interface Consistency
-
The structure and behavior of the Dataview user interface is completely
controlled by Dataview based on metadata provided by applications.
Dataview takes responsibility for implementing the appropriate UI
design patterns based on the structure of application data.
Ensuring complete consistency across all application datatypes and
even across all applications that use Dataview increases end user
productivity and task effectiveness.
Occasionally the Dataview interface for a given datatype may appear
sub-optimal. This is to be expected with a generic approach, and is a
reasonable tradeoff for consistency. In such a case it may be possible
to enhance Dataview's logic or metamodel to support the desired
behavior.
Major Domain Model Concepts
- Application
- An application is a set of types defined to Dataview. Each
application must be defined as a separate web application to the
servlet container.
An application is identified by its root package. Each application is
assumed to have a unique root package. The application's root package
is defined in the application's web.xml file using a context-param
named "application-package".
- Ownership
- Ownership is equivalent to existence-dependence. If type A owns
type B, type B is existence-dependent on type A. The database
representation of type B has a foreign key to type A. In a UML model,
ownership appears either as a composition relationship (the composite
owns the component) or as an association class (the association class
is owned by each association relationship participant).
Owned types are not displayed on the main menu generated by Dataview
for an application. Instead, they are displayed as tabs on the view
and edit pages for the owning type.
- Selection Availability
- When an attribute is of a user-defined type, it is sometimes
desirable to restrict the set of values available for selection. This
is particularly true for owned types. Consider a type A that
participates in an association relationship with type B. Assume that
there can be a maximum of one association between any given objects 'a'
and 'b'. When editing 'a', the set of instances of
B that are already related to 'a' through this association
should be excluded from the set of values available for selection.
Types control availability by providing an optional method named
'availableAttributeNameSelections' that takes an optional
'parent' argument used for owned types to indicate the known owning
object. For an association class, the parent argument is
the parent from which this object was traversed to.
- Constraining Selections
- A constraining selection is a selection that constrains the values
available for another selection. Consider a type that has two
attributes, 'a' and 'b', of types A and B, where type A owns type B.
A selection for attribute 'a' constrains the selections available for
attribute 'b' to those instances of B that are owned by the instance of
A selected. (Example: Address has attributes Country and State. The
selections for State are constrained by the selection of Country.)
Constraining selections are implemented in client-side Javascript
so that no server interaction is required.
Major Design Concepts
- Framework Architecture
-
Dataview is designed to be used as a black-box framework.
Dataview is not an application: applications use Dataview.
To deploy a data administration application, an application that uses
Dataview must create a web application archive file that includes the
Dataman JAR.
A key design objective for Dataview as a black-box framework is that
the only actions needed to incorporate Dataview should be to
include the Dataman JAR in the application's WAR file and to configure
the deployment descriptor to serve Dataview resources.
This design objective has several key impacts on user interface
component design.
- Static Content Servlet
-
The Java web application deployment model does not support web
application frameworks. Static content is expected to be placed
into a directory structure whose root corresponds with the
application's document root. This would require a framework to provide
a directory tree of static content so that a client application could
copy that tree into the directory structure of the web application
archive. This is not a framework interface.
To enable a framework interface, Dataview static content is served
using the
{@link gov.va.med.term.access.maint.ui.servlet.ContentServlet ContentServlet} or
{@link gov.va.med.term.access.maint.ui.servlet.CachingContentServlet CachingContentServlet},
both of which serve content residing in the classpath. Use of these
servlets allows all static content to be delivered in the Dataman JAR.
- Page Templates
-
The Java web application deployment model expects JSP files to reside
in the same directory structure as static content.
This makes JSP ineligible for use by an application framework, since
there appears to be no way to obtain a RequestDispatcher for a JSP that
resides only in the classpath.
Instead, Dataview uses page templates: program modules that output
HTML. These modules can be incorporated into a JAR file because they
are normal Java classes.
Each page template is an {@link gov.va.med.term.access.maint.ui.Outputter Outputter}.
- Dynamator
-
Page templates are generated using
Dynamator from pure HTML
and program logic files.
Dynamator provides a number of benefits.
It enables absolute separation of program logic from static content.
It enables reuse of program logic both within and across
pages.
It makes validation of the user interface as easy as validating a
static web site.
Without Dynamator, the use of page templates as Outputters
would introduce unacceptable maintenance overhead.
While it would be possible to use a third-party template engine such as
Velocity or Freemarker, this would add an unnecessary runtime
dependency without achieving any of the additional benefits provided by
Dynamator.
Dynamator adds no runtime dependency because it
is used only in the development environment.
User Interface Design
- Page Navigation
-
The basic Dataview page navigation model is
here.
This model shows page navigation for a simple datatype that does not
have dependents.
The navigation model for types with dependents is hierarchical and
recursive. A tab is displayed for each dependent type. When the tab
is selected, a list of dependents is displayed within the tab pane.
Navigation within the tab pane follows the same pattern as the basic
navigation model.
Dataview's add page is designed to support bulk add: after an object
has been added, the add page is redisplayed to allow another object to
be added.
- HTML Design
-
- The user interface is Section 508 compliant.
- HTML is XHTML 4.01 Transitional.
- Pages are styled using a limited subset of CSS 2.
- Pages are tested under the current versions of Internet Explorer
(6), Mozilla (1.3), and Opera (7).
- Pages are designed to gracefully degrade in older and less
capable browsers.
- Pages are validated using both the XHTML 4.01 DTD and
HTML Tidy (actually,
JTidy).
- The interface is almost exclusively text-based.
All images are non-essential. Currently the only use of images is
in association with a Javascript function.
- Javascript is used only to enhance behavior.
The user interface can be operated with Javascript disabled.
Features lost when Javascript is disabled are not critical to
application functionality. Examples include the ability to display a
date chooser (not implemented), the ability the sort lists on the
client (may be removed once large datasets are available), and the
ability to constrain selection lists based on user input.
- Currently, no form input editing is performed on the client.
Should this be provided in a subsequent release, all edits will
be performed on the server regardless of whether they are performed on
the client.
Configuration
To configure Dataview for use in a servlet container, see the
{@link gov.va.med.term.access.maint.ui.dataview.servlets.DataViewServlet DataViewServlet}.
@.maintenance
Classes in this package whose names begin with "Page" support
URL-based UIs. The other classes in this package are sufficiently
general to support any UI.
Implementation Design
A high-level structure model of the implementation is
here.
A {@link gov.va.med.term.access.maint.ui.dataview.PageStack PageStack}
object is created for each request. The interaction model for
PageStack creation is shown
here.
A high-level interaction model for GET request fulfillment is
here.
A high-level interaction model for POST request fulfillment is
here.
File Locations
HTML files are in dataman/html.
The files in that directory are complete, valid HTML, but do not
comprise a static demo site. (A static demo site is a set of files
that can be displayed in a browser to show the appearance of the site
without requiring server interaction.) To create a static demo site,
run 'ant create-demosite'; the static demo site is created in directory
dataman/demosite.
Dynamator files are in dataman/dynjava.