vitro/doc/list_view_configuration_guidelines.txt

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

-----------------
Required elements
-----------------

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


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


------------------
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. 
      
- Each assertion or set of optional assertions must reference a different graph variable, so that
no requirement about which assertions are in the same graph is imposed (unless this is desired
in a specific case).
      
- For collated properties: 
    - Include a ?subclass variable, named as such, in the SELECT clause. If the ?subclass variable
      is missing, the property will be displayed without collation.
    - ?subclass must be the first term in the ORDER BY clause
    - Include the following in the WHERE clause, substituting in the relevant variables for
      ?infoResource and core:InformationResource:
        OPTIONAL { GRAPH ?g4 { ?subclass rdfs:subClassOf core:InformationResource }
            GRAPH ?g5 { ?infoResource a ?subclass } 
            FILTER (?g5 != <http://vitro.mannlib.cornell.edu/default/inferred-tbox> && 
                    ?g5 != <http://vitro.mannlib.cornell.edu/default/vitro-kb-inf> ) 
        }  
      The filter blocks the retrieval of inferred type statements, so that, for example, we get
      subclass bibo:Book but not bibo:Document, assuming the latter is inferred. If both have been
      asserted, we will get both.
    
        
--------
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 Query Requirements), or 
    alternatively the template can use the localname function: ${localname(org)}.