Introduction

Custom list views provide a way to expand the data that is displayed for object and data properties. For example, with the default list view the hasPresenterRole object property would only display the rdfs:label of the role individual; but with a custom list view, the "presentations" view includes not only the role but also the title of the presentation, the name of the conference where the presentation was given and the date the presentation was given. This wiki page provides guidelines for developing custom list views as well as an example of a custom list view.

List View Configuration Guidelines

The following our guidelines for developing custom list views.

Registering the List View

A custom list view is associated with an object property in the RDF files in the directory /vivo/rdf/display/everytime. To register a list view, create a new .rdf or .n3 file in that directory.  The file must be well-formed RDF/XML or N3.

...

Note: Faux property custom list views are not registered in the same way. The list view is specified in the configuration of the faux property itself, using the faux property editing form. See details in Create and edit faux properties.

Required Elements

The list view configuration file requires three elements:

1. list-view-config: this is the root element that contains the other elements
2. query-select: this defines the SPARQL query used to retrieve data
3. template: this holds the name of the Freemarker template file used to display a single property statement

Optional Elements

The list-view-config root element can also contain two optional elements:

1. query-construct: one or more construct queries used to construct a model that the select query is run against
2. postprocessor: a Java class that postprocesses the data retrieved from the query before sending it to the template. If no post-processor is specified, the default post-processor will be invoked.

Construct Queries

Because SPARQL queries with multiple OPTIONAL clauses are converted to highly inefficient SQL by the Jena API, one or more construct queries should be included to improve query performance. They are used to construct a model significantly smaller than the entire  dataset that the select query can be run against with reasonable performance.

...

The ordering of the construct queries is not significant.

The Select Query

General select query requirements

Use a SELECT DISTINCT clause rather than a simple SELECT. There can still be cases where the same individual is retrieved more than once, if there are multiple solutions to the other assertions, but DISTINCT provides a start at uniqueness.

The WHERE clause must contain a statement ?subject ?property ?object, with the variables ?subject and ?property named as such. For a default list view, the ?object variable must also be named as such. For a custom list view, the object can be given any name, but it must be included in the SELECT terms retrieved by the query. This is the statement that will be edited from the edit links.

Data which is required in public view, optional when editing

Incomplete data can result in a missing linked individual or other critical data (such as a URL or anchor text on a link object). When the user has editing privileges on the page, these statements are displayed so that the user can edit them and provide the missing data. They should be hidden from non-editors. Follow these steps in the select query to ensure this behavior:

...

• The Java code will preprocess the query to remove the <critical-data-required> tag, either retaining its text content (in public view) or removing the content (when editing), so that the appropriate query is executed.

Collated vs. uncollated queries

The query should contain <collated> elements, which are used when the property is collated. For uncollated queries, the fragments are removed by a query preprocessor. Since any ontology property can be collated in the Ontology Editor, all queries should contain the following <collated> elements:

...

Both collated and uncollated versions of the query should be tested, since the collation value is user-configurable via the ontology editor.

Datetimes in the query

To retrieve a datetime interval, use the following fragment, substituting the appropriate variable for ?edTraining:

...

Many properties that retrieve dates order by end datetime descending (most recent first). In this case, a post-processor must apply to sort null values at the top rather than the bottom of the list, which is the ordering returned by the SPARQL ORDER BY clause in the case of nulls in a descending order. In that case, the variable names must be exactly as shown to allow the post-processor to do its work.

The Template

To ensure that values set in the template on one iteration do not bleed into the next statement:

...

If a variable is in an OPTIONAL clause in the query, the display of the value in the template should include the default value operator ! to prevent an error on null values.

List View Example

This example will walk through the custom list view for the core:researchAreaOf object property.  This property is displayed on the profile page for research area individuals.

Associate the property with a list view

In this example we're using RDF/XML to associate the researchAreaOf object property (line 1) with a specific list view configuration (line 2):

<rdf:Description rdf:about="http://vivoweb.org/ontology/core#researchAreaOf">
    <display:listViewConfigFile rdf:datatype="http://www.w3.org/2001/XMLSchema#string">listViewConfig-researchAreaOf.xml</display:listViewConfigFile>
</rdf:Description>

The list view configuration

The root <list-view-config> element in our listViewConfig-researchAreaOf.xml file contains the required <query-select> and <template> elements as well as two optional <query-construct> sections and an optional <postprocessor> element.

...

Note: the <postprocessor> is included here only to show the syntax. The actual listViewConfig-researchAreaOf.xml file in the VIVO code base does not use a custom post-processor.

The Freemarker Template

Finally, here are the contents of our Freemarker template, propStatement-researchAreaOf.ftl.

...