NIHVIVO-1334 Updated documentation on custom list view config

doc/list_view_configuration_guidelines.txt

@@ -2,7 +2,7 @@ List view configuration guidelines
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -----------------
-Required elements
+REQUIRED ELEMENTS
 -----------------
 
 - list-view-config: root element
@@ -11,17 +11,20 @@ Required elements
 
 
 -----------------
-Optional elements
+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.
                  
+---------
+THE QUERY
+---------
 
-------------------
+--------------------------
-Query requirements
+General 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
@@ -44,25 +47,55 @@ due to the possibility of incomplete data. Make sure the query does the followin
 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
+Query for collated property
-      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
+- Include a ?subclass variable, named as such, in the SELECT clause. If the ?subclass variable
-      ?infoResource and core:InformationResource:
+is missing, the property will be displayed without collation.
-        OPTIONAL { GRAPH ?g4 { ?subclass rdfs:subClassOf core:InformationResource }
+
-            GRAPH ?g5 { ?infoResource a ?subclass } 
+- ?subclass must be the first term in the ORDER BY clause
-            FILTER (?g5 != <http://vitro.mannlib.cornell.edu/default/inferred-tbox> && 
+
-                    ?g5 != <http://vitro.mannlib.cornell.edu/default/vitro-kb-inf> ) 
+- Include the following in the WHERE clause, substituting in the relevant variables for
-        }  
+?infoResource and core:InformationResource:
-      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
+    OPTIONAL { GRAPH ?g4 { ?subclass rdfs:subClassOf core:InformationResource }
-      asserted, we will get both.
+        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.
+
+----------------------
+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 { GRAPH ?g10 { ?dateTimeInterval core:start ?dateTimeStartValue .                     
+                                       ?dateTimeStartValue core:dateTime ?dateTimeStart }
+               }
+               OPTIONAL { GRAPH ?g11 { ?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.
    
     
---------
+------------
-Template
+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.
@@ -78,6 +111,6 @@ Template
         </#if>
     </#local>
         
-    The query must have been constructed to return orgName (see above under Query Requirements), or 
+The query must have been constructed to return orgName (see above under "General query requirements"), or 
-    alternatively the template can use the localname function: ${localname(org)}.
+alternatively the template can use the localname function: ${localname(org)}.