vitro/doc/list_view_configuration_guidelines.txt

List view configuration guidelines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-----------------
REQUIRED ELEMENTS
-----------------

- list-view-config: root element
- query-select: sparql query used to retrieve data
- template: the name of the template used to display a single property statement

-----------------
OPTIONAL ELEMENTS
----------------- 
   
- query-construct: one or more construct queries used to construct a model that the
                   select query is run against 
- postprocessor: a Java class that postprocesses the data retrieved from the query before
                 sending it to the template. If no postprocessor is specified, the default
                 postprocessor 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 that the select query is
run against. 

- The construct queries themselves should not contain multiple OPTIONAL clauses, to prevent
the same type of inefficiency. Instead, use multiple construct queries to construct a 
model that includes all the necessary data.

- In the absence of any construct queries, the select query is run against the
entire dataset. 

- The construct queries must be designed to collect all the data that the
select query will request. They can be flexibly constructed to contain more data than
is currently selected, to allow for possible future expansion of the SELECT. For example, one
of the construct queries for core:hasRole includes

    ?role ?roleProperty ?roleValue . 
    
WHERE

    ?role ?roleProperty ?roleValue . 
    
That is, it includes all the properties of the role, rather than just those currently
selected by the select query.

- 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.
      
- In a custom list view, it is generally necessary to provide for a missing linked individual, 
due to the possibility of incomplete data. Make sure the query does the following:
    - Enclose the clause for the linked individual in an OPTIONAL block. 
    - Select the object's localname using the ARQ localname function, so that the template can 
      display the local name in the absence of the linked individual. Alternatively, this can be 
      retrieved in the template using the localname(uri) method. 
      
    
-------------------------------
Collated vs. uncollated queries
-------------------------------

- The query should contain <collation-fragment> 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 <collation-fragment> elements:

    - A ?subclass variable, named as such, in the SELECT clause. If the ?subclass variable
    is missing, the property will be displayed without collation.

        SELECT DISTINCT <collation-fragment> ?subclass </collation-fragment> ...

    - ?subclass must be the first term in the ORDER BY clause.

        ORDER BY <collation-fragment> ?subclass </collation-fragment> ...

    - Include the following in the WHERE clause, substituting in the relevant variables for
    ?infoResource and core:InformationResource:

        <collation-fragment>
        OPTIONAL { ?subclass rdfs:subClassOf core:InformationResource .
                   ?infoResource a ?subclass 
        }  
        </collation-fragment>
    
- Postprocessing removes all but the most specific subclass value from the query result set.


----------------------
Datetimes in the query
----------------------

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

    OPTIONAL { GRAPH ?g9 { ?edTraining core:dateTimeInterval ?dateTimeInterval }
               OPTIONAL { ?dateTimeInterval core:start ?dateTimeStartValue .                     
                          ?dateTimeStartValue core:dateTime ?dateTimeStart 
               }
               OPTIONAL { ?dateTimeInterval core:end ?dateTimeEndValue .   
                          ?dateTimeEndValue core:dateTime ?dateTimeEnd 
               }                                       
    }    

- The variables ?dateTimeStart and ?dateTimeEnd are included in the SELECT clause.

- Many properties that retrieve dates order by end datetime descending (most recent first). In this
case, a postprocessor 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 postprocessor to do its work.
   
    
------------
THE TEMPLATE
------------

- To ensure that values set in the template on one iteration do not bleed into the next statement:
    - The template should consist of a macro that controls the display, and a single line that invokes the macro.
    - Variables defined inside the macro should be defined with <#local> rather than <#assign>.

- To allow for a missing linked individual, the template should include code such as:
    <#local linkedIndividual>
        <#if statement.org??>
            <a href="${url(statement.org)}">${statement.orgName}</a>
        <#else>
            <#-- This shouldn't happen, but we must provide for it -->
            <a href="${url(statement.edTraining)}">${statement.edTrainingName}</a> (no linked organization)
        </#if>
    </#local>
        
The query must have been constructed to return orgName (see above under "General select query requirements"), 
or alternatively the template can use the localname function: ${localname(org)}.

- 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.