The basic paradigm for the LAS UI is the Dataset --> Variable --> View --> Operation --> Options cascade:
- the LAS installation determines the available Datasets
- the selected Dataset determines the available Variables
- the selected Variable determines the available Views
- the selected View also determines the available Operations
- the selected Operation determines the available Options
Most of this cascade is evident on the Constraints page of the LAS UI which automatically updates selection menus further down the cascade based on choices further up. The details of the dependencies in this cascade are defined in the $TOMCAT_HOME/content/las/conf/server/ui.xml file and other files included by this file.
This document will describe how to configure/customize the behavior or the Constraints page by making modifications to the XML defined in these files.
Basic elements of the ui.xml file
The ui.xml file defines an XML tree with one or more of each of the following elements:
- <default>
- Each <default> contains one <map> for each of the four user interface pieces: LiveMap, Views, Operations, and Options. Each named <default> specifies a particular interface look and feel, potentially modifying the applet image and list of named regions, the list of named views, the list of operations associated with each view, and the list of options associated with each option.
- <map>
- Each <map> is a generic container for a specific component of a <default>. It provides a level of indirection between the <default> and the different user interface components.
- <constraint>
- A map of type ops can contain a list of <constraint>s. A <constraint> is a general purpose user interface element that allows a user greater control over the kind of data returned from a LAS data server. There are three types of constraint elements. A variable constraint element displays a menu of variables for the currently selected dataset. A text constraint displays a menu of text items. A text field displays a HTML text field. The menu items selected or text entered by the user are included in the LAS request (described in the older documentation); it is up to the LAS product server (LPS) to make sense of the tags included in the LAS data request.
- <menu>
- The three selection widgets in the LAS user interface that specify available Views, Operations and Regions are each defined as a <menu>. A menu contains a list of <items> or <ifitems>.
- <ifmenu>
- A map of type ops can have Operations which are dependent upon the selected View and also upon whether the user interface is in comparison mode or not. The <ifmenu> specifies this dependency and links a set of Views and modes with a particular ops menu.
- <item> & <ifitem>
- Each <item> in a <menu> specifies text for a selection choice and some values to return if that choice is selected. The values and how they are used depends upon which type of menu is being defined. A set of <ifitem> definitions within a views menu specifies a complete set of choices which will be subset according to which of the (x,y,z,t) axes actually exist within the grid definition associated with a Variable.
- <ifoption>
- A map of type options can have Options which are dependent upon the 'Operation. Operations are specified in menus of type ops. <ifoption>s specify this dependency. Further information on Options is found in the Options section of the older reference documentation.
- <image>
- Specifies an image to use the the map applet.
For detailed information about each element please see the older reference documentation on customizing UI behavior.
Associating data with a named Constraints page behavior
Because the <lasdata> and the <lasui> XML trees are independent, there needs to be a way to associate a particular dataset or variable with a particular set of UI behavior. By default, all datasets and variables are associated with the unnamed <default>, the default <default> if you will. It is found near the bottom of the ui.xml file and looks like this:
<default> <map href="#DefaultOperations"/> <map href="#DefaultViews"/> <map href="#DefaultLivemap"/> <map href="#DefaultOptions"/> <map href="#DefaultAnalysis"/> </default>
A named <default> looks very similar but contains a name="..." attribute in the <default> tag. Here is the "insitu_demo" <default> from the insitu_demo_ui.xml file.
<default name="insitu_demo"> <map href="#insitu_demo_Operations"/> <map href="#insituProfileViews"/> <map href="#insituLiveMap"/> <map href="#insituColorOptions"/> </default>
The association between a particular Dataset (or Variable) is described in the <properties> section of the dataset configuration file.
<ui> <default>file:ui.xml#insitu_demo</default> </ui>
Adding Constraints to an Operation
What are constraints?
LAS allows the installer to specify additional constraints that will appear on the Constraints page immediately above the plot options. The notion of a constraint is that it provides additional information that will be used to subset the data beyond the XYZT region specification. This notion of constraints maps gracefully onto database queries -- each constraint implies an additional WHERE clause in an SQL statement. Thus, for scattered data stored in a database, constraints provide user interface elements that allow the end user to slightly refine the database queries that are ultimately submitted by the database service.
There are two types of constraints as seen on the Constraints page for the 'Platforms with IDs' in-situ dataset distributed with LAS:
The first row has a variable constraint which allows the end user to pick one of the dataset variables, a comparison operation (<, <=, =, >=, >) and type in a value. If this constraint is applied, the SQL statement generated to retrieve this data which have WHERE SST < # appended to it to only select those data where SST is less than the user specified value.
The second and third rows contain installer defined text constraints that provide additional, dataset specific information that can be used by either the database service or the ferret service to subset the data.
Defining constraints
Constraints are defined in the ui.xml file or in a file included by ui.xml. The constraints for the example above are found in armstrong/conf/server/insitu_demo_ui.xml. First, <menu>s are created to contain all of the selection options:
<menu type="constraint" name="insitu_demo_2_CountryText"> <item values="country">Country</item> </menu> <menu type="constraint" name="insitu_demo_2_CountryOps"> <item values="=">=</item> <item values="!=">!=</item> </menu> <menu type="constraint" name="insitu_demo_2_Countries"> <item values="AU">Australia</item> <item values="JP">Japan</item> <item values="US">United States</item> </menu> <menu type="constraint" name="insitu_demo_2_PlatformText"> <item values="type">Platform</item> </menu> <menu type="constraint" name="insitu_demo_2_PlatformOps"> <item values="=">=</item> <item values="!=">!=</item> </menu> <menu type="constraint" name="insitu_demo_2_Platforms"> <item values="ARGO FLOAT">ARGO float</item> <item values="DRIFTING BUOY">Drifting buoy</item> <item values="MOORED BUOY">Moored buoy</item> <item values="SHIP">Ship</item> </menu>
Then these <menu>s are collected together into named <constraint>s inside of a named <map> of type ops. Note that the <constraint> of type variable does not need to be defined by the installer. LAS creates this for you and includes all of the variables in the dataset.
<map type="ops" name="insitu_demo_2_Operations"> <ifmenu view="xy" href="#Ops_insituProfileXY"/> <ifmenu view="xz" href="#Ops_insituProfileXZ"/> <ifmenu view="xt" href="#Ops_insituProfileXT"/> <ifmenu view="yz" href="#Ops_insituProfileYZ"/> <ifmenu view="yt" href="#Ops_insituProfileYT"/> <ifmenu view="zt" href="#Ops_insituProfileZT"/> <ifmenu view="xyzt" href="#Ops_insituProfileXYZT"/> <ifmenu view="z" href="#Ops_CruiseProfileZ"/> <constraint type="variable"/> <constraint type="text" name="insitu_demo_2_Countries"> <menu href="#insitu_demo_2_CountryText"/> <menu href="#insitu_demo_2_CountryOps"/> <menu href="#insitu_demo_2_Countries"/> </constraint> <constraint type="text" name="insitu_demo_2_Platforms"> <menu href="#insitu_demo_2_PlatformText"/> <menu href="#insitu_demo_2_PlatformOps"/> <menu href="#insitu_demo_2_Platforms"/> </constraint> </map>
Finally the operations <map> containing these constraints is referenced in a new <default>.
<default name="insitu_demo_2"> <map href="#insitu_demo_2_Operations"/> <map href="#insituProfileViews"/> <map href="#insituLiveMap"/> <map href="#insituColorOptions"/> </default>
Once the tomcat server hosting the LAS user interface is restarted, the new constraints will appear in the user interface.