XNAT: Customizing XNAT

FAQ

Customizing XNAT

XDAT manages data display through two primary forms, listings and reports. Listings are used to display multiple instances of the same data type in a tabular format. Reports are used to display a single instance of a data type. Listings are built using XML display documents. Reports are built using Velocity templates and corresponding Java Classes. Display documents, Java classes, and velocity templates are generated by the XDAT setup or update script. However, an administrator will usually want to customize these generated documents to make the site more user-friendly.

Listings

A great deal of information can be gained from an XML Schema to determine what data should be stored or processed by XDAT. However, when the user desires straight forward representations of their data in more user-friendly formats, the additional forms of meta-data are needed. For example, without additional meta-data, a tabular representation of a Schema Element would contain every possible field for that element without any formatting and without any derived data. In order to display data in a user-friendly format, we’ve created a system of xml-based meta-data documents which provide additional information about how Schema Elements should be displayed.

Through xml-based meta-data documents, or display documents, a site manager is able to define which individual fields are visible to outside users, what formatting should be done on those columns, what additional derived data can be visible to a user, and what fields are searchable.

Site managers can create a collection of custom Display documents to detail the searches and listings available to users. For any visible Schema Elements, site managers are encouraged to build separate Display documents which will define the specific columns available for presentation (DisplayFields), the different patterns of columns available for different situations (DisplayVersions), and additional database views which will allow for more robust listing information.

The meta-data defined in the Display documents is used to generate database views which will be used by the XDAT search engine. For any ‘displayable’ element several views are created, including the schemalink views (which contain the available fields for the specified element including all fields from any additional elements which can be joined to the displayable element), linked views (which contain the fields from the schemalink view with the fields defined through custom views), and displayfields views which contain all of the DisplayFields defined in the display document.

<Displays>

A Display document contains one <Displays> element. This <Displays> element can contain <DisplayField>, <DisplayVersion>, <SchemaLink>, <ViewLink>, and <SQLView> elements. Each <Displays> element maps to one and only one element from the XML Schema. The <Displays> element must have a schema-element attribute which identifies which XML Schema element this <Displays> is associated with. The optional value_field, display_field, and display_label attributes are used to identify the default label for this element, id/value fields for this element.

<DisplayField>
The most important elements in the <Displays> element are the <DisplayField> elements. These elements define what schema fields are available to be used in listings and searches. They can be simple representations of one schema field’s value or a complex combination of multiple schema fields. A <DisplayField> can have the following attributes:

Id (required) : This is a UNIQUE string which identifies this field.
Header (required) : This is the header which will be displayed in the event this field is used in a listing.
Image (optional) : true if this field should be an <IMAGE>, otherwise false.
Sort-by (optional) : default: sorts by itself, otherwise a different <DisplayField>’s id is specified for sorting.
Sort-order (optional) : ASC OR DESC
Searchable (optional) : true if this field should show up in dynamic search pages.
Data-type (optional) : specifies the XML data type of this field, necessary if the <DisplayField> involves some reformatting.

A <DisplayField> can have several child elements.

DisplayFieldElement: used to specify the schema field(s) or view column(s) used in this <DisplayField>.
Content: Specifies the formatting which will be done to the specified DisplayFieldElements.
HTML-Link: Specifies that an <A> (HTML-Anchor) should be used for this field.
HTML-Cell: Specifies the formatting of the HTML Cell surrounding this field.
HTML-Image: Specifies the options for the surrounding <IMAGE> tag.

A <DisplayField> element must be defined for every field which the site manager wants to be displayed in the application.

Example:
<DisplayField id="SUBJECTID" header="Subject" visible="true">
             <DisplayFieldElement name="Field1" schema-element="oas:subjectType.subjectData.ID"/>
             <HTML-Link>
                    <Property name="HREF" value="none"/>
                    <Property name="ONCLICK" value="return rpt('@Field1','oas:subjectType','oas:subjectType.subjectData.ID');">
                           <InsertValue id="Field1" field="SUBJECTID"/>
                    </Property>
             </HTML-Link>
       </DisplayField>
       <DisplayField id="AGE" header="Age" visible="true">
             <DisplayFieldElement name="Field1" schema-element="oas:subjectType.subjectData.age"/>
       </DisplayField>
       <DisplayField id="GENDER" header="Gender" visible="true">
             <DisplayFieldElement name="Field1" schema-element="oas:subjectType.subjectData.gender"/>
       </DisplayField>
       <DisplayField id="STATUS" header="Status" visible="true">
             <DisplayFieldElement name="Field1" schema-element="oas:visitData.clinicalAssessmentData.CDR.score"/>
             <Content type="sql">CASE WHEN @Field1 IS NULL THEN 'young' WHEN @Field1 >0 THEN 'dat' ELSE 'normal' END</Content>
       </DisplayField>
       <DisplayField id="WBV" header="WBV" visible="true">
             <DisplayFieldElement name="Field1" viewName="SUBJECT_FSL_VIEW" viewColumn="volumes_brain_percent"/>
       </DisplayField>
       <DisplayField id="ETIV" header="eTIV" visible="true">
             <DisplayFieldElement name="Field1" viewName="SUBJECT_ASF_VIEW" viewColumn="etiv"/>
       </DisplayField>
       <DisplayField id="CLIN_DELAY" header="Clin. Delay" visible="true">
             <DisplayFieldElement name="Field1" schema-element="oas:visitData.clinicalAssessmentData.delayFromMr"/>
       </DisplayField>
       <DisplayField id="CDR" header="CDR" visible="true">
             <DisplayFieldElement name="Field1" schema-element="oas:visitData.clinicalAssessmentData.CDR.score"/>
       </DisplayField>
       <DisplayField id="MMSE" header="MMSE" visible="true">
             <DisplayFieldElement name="Field1" schema-element="oas:visitData.clinicalAssessmentData.MMSE"/>
</DisplayField>

<DisplayVersion>

The <DisplayVersion> elements specify the different combination of <DisplayField>s. A <DisplayVersion> can have the following attributes:

versionName:

Each <DisplayVersion> must have a unique versionName. The first defined <DispayVersion> will be considered the default version. The primary html version is expected to be called ‘listing’. Also, smaller sub-sets of the fields can be defined in ‘brief’ and ‘detailed’ which will be used in Super Searches. It is recommended that the developer create separate versions of HTML <DisplayVersion>s to be used for CSV output of those versions. The CSV versionName should be titled the same as its matching HTML listing with ‘_csv’ appended to the end. So the name of the primary listing’s CSV version would be ‘listing_csv’. Similarly, ‘brief_csv’ and ‘detailed_csv’ can be defined.

Default-order-by: This is the DisplayField which will be used in the ORDER BY statement, if no ORDER BY is defined.
Brief-description: Description used in the Browse/Search/Listin menus to identify this element.
Dark-color/Light-color: Alternating colors to be used in alternating rows in HTML listings.

The <DisplayVersion> uses child <DisplayFieldRef> elements to define which <DisplayField>s are included in this listing. The <DisplayFieldRef> identifies the <DispayField> with its id attribute. A new header can be defined in the header attribute which will overrule the header defined in the <DisplayField>.

Example:
<DisplayVersion versionName="listing" default-order-by="SUBJECTID" brief-description="Subject Data" dark-color="DEDEDE" light-color="FFFFFF">
             <DisplayFieldRef id="SUBJECTID"/>
             <DisplayFieldRef id="AGE"/>
             <DisplayFieldRef id="GENDER"/>
             <DisplayFieldRef id="STATUS"/>
             <DisplayFieldRef id="WBV"/>
             <DisplayFieldRef id="ETIV"/>
             <DisplayFieldRef id="CLIN_DELAY"/>
             <DisplayFieldRef id="CDR"/>
             <DisplayFieldRef id="MMSE"/>
</DisplayVersion>

<SchemaLink>

In some situations, the developer may want to include fields from another Schema Element, whose relation to the Display element is not clear from the XML Schema. In this instance, a <SchemaLink> element is used to specify the relation between the two elements. This involves defining a mapping between the two elements (usually involving a database table or view which maps the two elements). The developer defines <MappingColumn> elements to define how the root element and the linked element relate to the mapping table.

For example:

This element can then be used in <DisplayField> elements as if it is the displayable element. An alias can be defined for the schema link, and used in place of the element name in the DisplayFields to allow the site manager to link to multiple instances of the same schema element.

<SQLView>

To allow for the display of more complicated fields, a site manager may need to create custom Database views. One common need for SQLViews comes from the inability to display all of a schema element’s fields. In order to maintain one row per element in the tabular structure, fields which have multiple references (maxOccurs=unbounded) are not included in the searched views. In order to display information about the multiple references, a site manager must create database views which map the results to one row per element. These views are specified in the <SQLView> tags and can be joined to the displayable element via a <ViewLink>. SQLViews only have two attributes; name (name of view in database) and sql (the SELECT statement used to create the view). The CREATE VIEW statement is generated with the other sql.

Example:

<ViewLink>

ViewLinks are defined to join custom views to the displayable element. They specify the view to be joined through the TableName attribute. MappingColumns are then used to connect the view to the schema element. Aliases are defined to allow multiple instances of the view to be joined to the schema element.

Example:

Arcs

In order to join displayVersions from separate displayable elements, an arc can be defined to specify how the two elements are related. Declaring an Arc takes two steps.

Define an <Arc-Definition>.

An arc is defined with a unique id and a collection of CommonFields. These are DisplayFields which every member element is expected to have. Commonly, the two elements are related by another element that they both relate to. This is called the bridge-element. The bridge-element can be specified in the Arc-Defintion. Filters can be defined on the common fields to assist in the mapping of the correct elements. The possible filter types are closest, before, equals, and distinct. The distinct filter is almost always used to guarantee that there is a one-to-one relationship between the elements. The equals filter is mandatory to join the elements.

<Arc-Definition Id="PARTICIPANT_EXPERIMENT">
             <CommonField id="DATE" type="DATE"/>
             <CommonField id="PART_ID" type="STRING"/>
             <CommonField id="EXPT_ID" type="INTEGER"/>
             <Bridge-Element name="Participant" field="PART_ID"/>
             <Filter field="EXPT_ID" filterType="distinct"/>
             <Filter field="DATE" filterType="closest"/>
             <Filter field="PART_ID" filterType="equals"/>
</Arc-Definition>

Define Arc Membership

Within the member elements, include the <Arc> element to imply that this element is a member of that Arc. The <Arc> specifies the defined Arc by the name attribute. Also, the CommonFields for the Arc are specified with the local fields which correspond.

Instructions for creating a display document.

Select the root element to display.

This must be a globally defined element in your schema.

Create an xml file titled {element_name}_display.xml.

The first section of the name does not matter. But, the file must end in ‘_display.xml’ and be located in a directory called display (which must be located next to your schema) for it to be loaded by the application.

Select the fields which you want to be available for display.

All fields are available to be used in DisplayFields, unless they belong to a multiple reference element (maxOccurs=unbounded). The multiple reference elements are not available because their use would result in multiple rows for one root element.

The fields are specified in the <DisplayFieldElement> of <DisplayField>s. The field is referenced through dot-syntax. The dot-syntax structure must start with the element name (including namespace prefix). Each child field is then followed by a dot. For example, in following element:

<xs:complexType name="mrScanType">
             <xs:sequence>
                    <xs:element name="note" type="xs:string" minOccurs="0"/>
                    <xs:element name="parameters">
                           <xs:complexType>
                                 <xs:sequence>
                                        <xs:element name="voxelResX" type="xs:float" minOccurs="0"/>
                                 </xs:sequence>
                           </xs:complexType>
                    </xs:element>
             </xs:sequence>
             <xs:attribute name="number" type="xs:string" use="required"/>
             <xs:attribute name="type" type="xs:string" use="required"/>
</xs:complexType>

These fields are available:

xnat:mrScanType.note
xnat:mrScanType.parameters.voxelResX
xnat:mrScanType.number
xnat:mrScanType.type

To show one of these fields, the site manager would create a DisplayField like this:

To add some formatting to this field, SQL can be added in a <Content> tag.

<DisplayField id="NOTE" header="Notes" visible="true">
<DisplayFieldElement name="Field1" schema-element="xnat:mrScanType.note"/>
<Content type="sql">ENCODE(substring(@Field1 FROM 0 FOR 10),'escape')</Content>
</DisplayField>

Notice, the use of the DisplayFieldElements name in the sql with an ‘@’ character before it. This marks the spot where that field’s value will be used. The actual SQL column name will be added in place of this marker at runtime.

The site manager can also make the Field a Hyperlink by adding an HTML-Link tag.

The HTML-Link allows the site manager to insert any attributes into the created ANCHOR <A> tag. In the above example, the tag would end up looking like:

<A HREF=”none” ONCLICK=” return rpt('VALUE’,'xnat:mrSessionData','xnat:mrSessionData.ID')”> VALUE</A>

In this instance, the ONCLICK references a javascript function which was declared in the page. Notice that ANY DisplayField ID can be used in the <InsertValue> tag’s field attribute. In many cases, the Display Field for the primary key will have been defined separately and would be referenced here.

Create one or more DisplayVersions.

Create at least one DisplayVersion (the default one for HTML listings should have a version name of ‘listing’). Assign alternating HTML Color codes, a default ORDER BY column (which must match one of the included DisplayFields) and a description. Use DisplayFieldRef tags to select which fields will be displayed, and in what order.

Create Views, ViewLinks, and/or SchemaLinks to add additional display fields.

See further documentation for more information…

Once the document is complete, execute the CreateSQL function. The SQL to create the necessary views will be created at the bottom of the generated file. Once these views have been created in the database, the new displays should be available. The website may need to be restarted or refreshed (using the link in the 'more' page of the administration section of the website for 'Refresh Display Manager' or the direct link, http://application/app/actions/RefreshAction/refresh/DisplayManager) to see the changes.

Reports

The XDAT website makes use of Jakarta Turbine’s structure to allow for the easy creation of secured report Screens. Each report has two primary components; a java class and a Velocity page (.vm). For any report you create, you will need to create both of these components.

What happens before XDAT gets to your report?

The XDAT engine takes care of all of the navigation processing for any Report. This processing starts in the org.cnl.xdat.turbine.actions.DisplayItemAction Class. This class is in charge of locating/loading the item that will be displayed and routing the item to the correct Velocity screen. Generally, items are passed to this DisplayItemAction with just a few simple Turbine RunData parameters (Key/Value parameters). The three parameters passed are the schema element name (search_element), the field whose value is sent (search_field) and the matching value (search_value). Example:

KEY	VALUE
search_element	xnat:mrSessionData
search_field	xnat:mrSessionData.ID
search_value	FORGE1_0014_1_MR

These three parameters will then be used to load the appropriate item from the database. The search_field should correspond to either the primary key field or a field with a unique value, to guarantee that only one item is returned. The search_value must correspond to the item’s search_field.

After the DisplayItemAction has loaded the Item, it checks to see if the element has a customized Report. If no customized Report is found, then the item is routed to the default display Screen. ATTENTION: In order for your customized report to be found by the XDAT engine, it must have the proper name and be in the proper location. The name of the File is expected to begin with ‘XDATScreen_report_’ and then contain the SQL version of the element name (the use of the SQL version of the name, guarantees that there will be no special characters in the name (i.e. ‘:’) which could not be used in a file name). The SQL version of the name can be found by finding the corresponding table in the database, and using that table’s name. The files (java and vm) must be in a location which the Turbine Web Application looks (i.e. the templates/screens directory for the vm, and the java class location specified in the TurbineResources.properties).

Extending/Creating the Java Class.

Each report has a java file which is processed before the Velocity screen is constructed. This java file handles loading the necessary objects into the Velocity Context for easy use in the Velocity screen.

The setup and update scripts create Report classes for all of your root-level elements. They are placed in the package org.nrg.xdat.turbine.modules.screens (in the PROJECT/src/java directory). Often these will be adequate for your needs and you will not need to tamper with them. If you need to add processing the Report class (for example, to load additional data into the context) then you can create your own Report class in the org.apache.turbine.app.PROJECT_NAME.modules.screens package located in the PROJECT/src/java directory. Usually this is as simple as copying the generated java class into the new directory, changing its package name and adding your additional code.

XDAT provides a Java Class (org.nrg.xdat.turbine.modules.screens.SecureReport) which handles most of the processing for you. If you decide you need additional Java processing, you will need to create a custom class which extends the SecureReport or the generated class. It is expected that your custom report class will be named as follows (XDATScreen_report_{sql_name}.java). The SecureReport class provides one abstract method which ‘public void finalProcessing(RunData data, Context context)’ which must be implemented. This method can be left empty, or any additional processing the site manager desires can be added.

The SecureReport class (which all Report screens should extend) places several objects into the context for use in your macro scripting. The item which you searched for will be an org.nrg.xft.XFTItem and can be referenced using the $item variable. The current user (org.nrg.xdat.security.XDATUser) will be accessible via the $user variable. The report will also instantiate the corresponding Java OM objects (located in the org.nrg.xdat.om package which are generated by the setup or update script) and load them into the context as $om. These classes can be modified to allow for customized java processing of your data. If the item being displayed extends xnat:subjectAssessorData, then the corresponding Subject OM (org.nrg.xdat.om.XnatSubjectdata) will be loaded into the context as $subject. If the item being displayed extends xnat:mrAssessorData, then the corresponding MR OM (org.nrg.xdat.om.XnatMrsessiondata) will be loaded into the context as $mr.

Create the Velocity Screen

The velocity screen is the location of most of the report specifications. The site manager can customize this format in any way deemed necessary (See http://jakarta.apache.org/velocity/user-guide.html for more details).

The web application will look in multiple locations for your report files. This allows you to override the default reports which XNAT generates, and the additional reports which are provided with XNAT.

The web application will look in four locations for your Velocity macros (in the following order).

1. WEBAPP_ROOT/templates/screens
2. WEBAPP_ROOT/xnat-templates/screens
3. WEBAPP_ROOT/xdat-templates/screens
4. WEBAPP_ROOT/base-templates/screens

The initial location (1) is where you should place any reports which you create. If the web application doesn’t find a report in that location, it will look in location (2). This is where pre-customized reports specifically for XNAT are located. Next, it will look in location (3) which is where pre-customized reports for XDAT (security) are located. Finally, it will look in the WEBAPP_ROOT/base-templates/screens (4). This is where XNAT’s setup or update scripts put the generated report screens.

The easiest and quickest way to create a new report, is to copy the generated .vm file from the WEBAPP_ROOT/xdat-templates/screens location into the WEBAPP_ROOT/templates/screens location and manipulate the content.

Accessing Item properties

Individual properties of the Item are accessible through the getProperty() method of the org.cnl.xft.XFTItem. The field name can be specified using the dot-syntax name of the field (i.e. $item.getProperty(“xnat:MrSession.mrSessionData.ID”)). The getString() and getBooleanProperty() can be used similarly to receive the values with particular formatting.

There are two ways to access the properties of the children of the Item. First, the site manager can obtain a reference to the sub Item directly using the getProperty() method for single reference or the getChildItems() method for multiple referenced children. Both of these methods take in the dot-syntax name of the field (i.e. $item.getChildItems(“xnat:mrSessionData.scan”)). The other method to access the properties of the children of the Item involves referencing the child fields directly through dot-syntax. This becomes tricky when you are referencing a child which could have multiple objects. So, numbers can be inserted (surrounded by brackets) into the dot_syntax after a reference field name to specify which child you are referencing. Example:

$item.getProperty(“xnat:mrSessionData.scan[2].number”)

The number must be preceded surrounded by ‘[‘ and ‘]’ characters and starts with 0. This code would return the number field of the third scan (0,1,2) for this session. If there was no third scan, then null would be returned.

Thus, when a site manager wants to iterate through multiple children, there are two options.

Obtain direct references to the objects:

#foreach ($scan in $item.getChildItems("xnat:mrSessionData.scan"))
                                <TR>
                                                <TD>$!scan.getProperty("xnat:mrScanType.number")</TD>
                                                <TD>$!scan.getProperty("xnat:mrScanType.type")</TD>
                                                <TD>$!scan.getString("xnat:mrScanType.note")</TD>
                                </TR>
                #end

Directly reference the fields using a number in the dot-syntax

                #foreach($c in [0..10] )
                                <TR>
                                                <TD>$item.getProperty("xnat:mrSessionData.scan [${c}].number”)</TD>
                                                <TD>$item.getProperty("xnat:mrSessionData.scan [${c}].type”)</TD>
                                                <TD>$item.getProperty("xnat:mrSessionData.scan [${c}].note”)</TD>
                                </TR>
                #end

The primary difference between the two methods is that, the first option will result in only as many rows as there are objects. The second option will have as many rows as is specified in the loop. The second option is useful in edit screens.

Creating (OM) Item Classes

The XFTItem structure allows for easy access to items without type casting the item to a specific java type. This provides an excellent generic method for working with data. However, in some instances, the site manager may want to create a custom object to wrap that Item, which will allow for greater flexibility and customization. The XDAT engine creates this Item wrapper for you.

The setup or update scripts create three java files for each complex type in your schema; an auto class (org.nrg.xdat.om.base.auto) which extends org.cnl.xdat.base.BaseElement and contains the methods for constructing an object and accessing its values, a base class (org.nrg.xdat.om.base) where XNAT provided functions are defined, and a extension class (org.nrg.xdat.om - this is where your custom methods should go) which simple extends the base class. If at some point the classes are regenerated, the Auto class will be overwritten with the new Class, but the extension classes will NOT be overwritten.

These custom OM classes are automatically instantiated by the generated Java Reports and placed in the Velocity Context for use in your velocity macros using the name $om.

Notice, that the custom item has inherited methods to access the defined Display Fields for this element (getDisplayField()). So, if you have defined a corresponding Display document for the item’s schema element, those values can be accessed by passing Display Field IDs into the getDisplayField() method. ATTENTION: In order to access these values, the user must specifically preload the Display Field values (using the loadDisplayFields() method). This is not done automatically, as sometimes it can cause a slow SQL select.

There are numerous methods inherited from org.cnl.xdat.base.BaseElement which allow for easy use of Items and effective access of their properties.

Pre-defined Turbine Velocity Macros

For your convenience, some velocity macros have been predefined in templates/macros/TurbineMacros. For use in reports, one macro (elementActionsBox) will be particularly helpful. This macro will list the possible actions for a given item based on the element’s security settings (xnat:element_security). The code to insert this macro into a velocity screen is:

#elementActionsBox($element $search_field $search_value $data.getSession().getAttribute("user") $item)

All of these attributes are passed in from the SecureReport screen, so this code can be inserted without additional work.

Edit Pages

Data Entry forms are generated by the setup or update scripts. They are placed in the PROJECT_NAME/src/xdat-templates directory and are named ‘XDATScreen_edit_’ + data type sql name. These generated edit templates contain every possible field and may need customization for active use. To customize the edit forms, copy them into the PROJECT_NAME/src/templates directory and modify the files as desired.

To modify the preliminary java processing for the screen (if necessary), copy the appropriate org.nrg.xdat.turbine.modules.screens class to the org.apache.turbine.app.PROJECT_NAME.modules.screens package. Add your customized java code to the finalProcessing method and change the package name to reflect the new package location.

Adding Features And Content

XDAT uses Jakarta Turbine to manage its web architecture. Turbine supports the use of Actions and Screens to manage the flow of web requests. The majority of screens are auto-generated for you. However, you may want to build some custom screens and actions to facilitate new features.

Actions are written as Java classes and must be located in the org.apache.turbine.app.PROJECT_NAME.modules.actions package. The classes can extend the org.nrg.xdat.turbine.modules.actions.SecureAction class to make use of the XDAT security model. Action processing goes in the doPerform(data,context) method. As an action completes, it should be directed to a screen for user response. Custom created actions and screens can be accessed through the standard Turbine mechanisms or can be tied into XDAT’s site management system.

In order to tie new features into the XDAT site, you can create custom screens and reference them using the data type ‘element actions’ in the administration section. Doing this will create a link in the actions box on all reports for the specified data type. In the administration section, go to the ‘Data Types’ listing. Click on the Data Type which you would like to edit. This brings up the report for the specified data type. From here you can access the edit page which lists the current ‘element actions’ for this data type and allows for the insertion of new ones. The name of the action must map to the name of your custom screen using the XDATScreen naming convention.

XDATScreen Naming Convention

The report page ‘action’ links generated by adding data type ‘element actions’, link to the org.nrg.xdat.turbine.modules.actions.XDATActionRouter class defined in the XDAT jar. This jar will use the name of the element action and data type name to pass processing to the proper velocity screen. All custom screens which map to an element action must begin with the ‘XDATScreen_’ header. The XDATActionRouter will look for a screen which is named using the header, the sql name of the data type, and the element action name (‘XDATScreen_’ + sql_name + ‘_’ + element_action_name). If this screen is not found, then it will look for a screen named using the header and the element action name (‘XDATScreen_’ + element_action_name). If this screen, is not found then an error is thrown.

If you are creating a custom screen which will be linked to from the actions box, you should either name it “‘XDATScreen_’ + sql_name + ‘_’ + element_action_name” or “‘XDATScreen_’ + element_action_name”. (case-sensitive) Using the second convention will allow the screen to be accessed by any data type which has the corresponding element action. The first convention will only be accessible by the defined data type.

Element Action Attributes

Element Actions are accessible from the ‘Data Type’ report or edit page and effect the links which are available in report pages. There are several attributes which can be set for a given element action.

Name: This is the name which will be used in the Action link and must be used in the screen file’s naming convention.
Display Name: This is the text which will be displayed in the ANCHOR tag on the report page in the Actions box.
Image: This is the name of an image file (located in the src/images directory) which will be displayed with the Display Name text.
Popup: Specifies whether or not the Action link should generate a new window or not. If it’s blank (or ‘never’), then the link will never produce a popup. If it’s ‘sometimes’, then the link will produce a new window if the report page itself is not a popup page, otherwise it will not popup a new window (Useful to prevent popup proliferation). If it’s ‘always’, then the link will always generate a new window.
Secure Access: This will be used to decide whether or not a user has permission to access this action for a particular instance of a data type. It uses the data type permissions defined in the Admin User page (‘edit’, ’read’, ’create’, or ’delete’). If the user does not have permission for the corresponding access type, then no link will show up on the report.
Additional Parameters: This text will be appended to the request url which is sent to the screen.

Sequence: Governs the ordering of the element action links in the Actions box on a report page.

Bundles

Bundles are stored searches which other users are allowed to view. They are a useful tool for organizing subsets of data into easily viewed combinations. The definition of each bundle is stored in the database in the same manner your data is stored. The bundles are loaded into the Web Servers context when they are first requested. Each bundle has a list of users who are allowed to view it. These users will have a link to the bundle in their navigation menu.

A bundle has several key variables.

ID
This is the primary identifier of a bundle. It must be unique to this bundle.

Description
This brief description is the Text which will be used to identify this bundle.

Pivot Data Type (Root Element)
Every bundle must have a pivot data type, which is the root data set of the of the bundle. It is used to join data types together. All other data types in the bundle will be joined to this data type (rather then to each other). XDAT builds a bundle by starting with the root data type, joining other data types to the root data type, processing the WHERE clause to limit the rows in the result set, and outputing the result set according to the specified Displayed Fields.

Sort By Data Type & Field
These two variables combine to identify the field which should be used to sort the rows in the bundle.

Display Fields
The Display Fields of a bundle identify which columns will be displayed in the bundle. These fields reference <DisplayField>s from the display documents (used in the listings). The element_name and field_ID variables are used to specify which previously defined <DisplayField>s should be included in the bundle. The sequence is specifies the order that the fields (columns) should appear in the bundle. The type is the resultant type of the data fields. The header is the Text which will appear as the header of the columns.

Where Clauses
Where clauses are used to limit the rows which are included in the bundle. Without any Where clauses all of the rows for the 'pivot data type' will be included in the bundle. The web interface allows the creation of simple WHERE Clauses. For more complicated (multi-leveled) clause, XML may be needed to define the bundle (rare).

Method
The method variable defines whether the specified Where clauses should use 'AND' or 'OR' logic.

Display Field
The Display Field (schema field) is the data field which will be used to process the clause. This can be a Display Field or a Schema Field. Either way the field should start with the root data type of the field. If it references a pre-defined display type, then it should reference the Display Fields ID (i.e. data_type.Field_ID). If it references a schema field, it should reference the field in the same manner that is used in the display documents (i.e. data_type/schema_field). This allows you to limit the result set by a pre-defined field (which may be derived) or directly from a data value.

Comparison Type
The comparison_type variable specifies what comparison expression to use in the where clause. It can be =,<,<=,>,>=, or LIKE (for string types).

Value
The value variable specifies the Value to use in the Where clause comparison.

Custom Search
The custom_search and override_value_formatting variables can be used to directly specify an unconventional where clause. In the custom_search variable you can include the text of the WHERE clause. This text must be valid sql as it will be included directly in the SQL where clause. The override_value_format specifies that XDAT should not try to format the expression with characters like ' or %.

Allowed Users
These are the logins of the users who are allowed to view this bundle.

Creating/Editing A Bundle

Bundles can be created via two methods, XML Storage or Web Edit Page.

Web Edit Page
Administrators are allowed to access, create, and edit bundles in the Administration section of the website on the 'Bundles' page.

XML Storage
The Bundles can be stored using the StoreXML task in the same way that your other data is stored. The bundle should be built according to the specifications of the /projects/PROJECT_NAME/src/schemas/security/security.xsd schema.

The xml should be stored using the StoreXML task from the command prompt.