NIHVIVO-1879 Update list view configuration guidelines for changes to the handling of collated properties, and other miscellaneous updates.

doc/list_view_configuration_guidelines.txt

@@ -6,31 +6,55 @@ REQUIRED ELEMENTS
 -----------------
 
 - list-view-config: root element
-- query-base: sparql query used to retrieve data for an uncollated property
-- query-collated: sparql query used to retrieve data for a collated property
+- query-select: sparql query used to retrieve data
 - template: the name of the template used to display a single property statement
 
-Note: both query-base and query-collated must be included to support the collation checkbox
-on the back end Object Property Edit form.
-
-
 -----------------
 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.
                  
----------
-THE QUERY
----------
-
------------------ 
-Construct queries
 -----------------
+CONSTRUCT QUERIES
+-----------------                
 
- - forthcoming -
+- 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
@@ -54,24 +78,36 @@ due to the possibility of incomplete data. Make sure the query does the followin
       retrieved in the template using the localname(uri) method. 
       
     
---------------------------- 
-Query for collated property
----------------------------
+-------------------------------
+Collated vs. uncollated queries
+-------------------------------
 
-- Include a ?subclass variable, named as such, in the SELECT clause. If the ?subclass variable
-is missing, the property will be displayed without collation.
+- 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:
 
-- ?subclass must be the first term in the ORDER BY clause.
+    - A ?subclass variable, named as such, in the SELECT clause. If the ?subclass variable
+    is missing, the property will be displayed without collation.
 
-- Include the following in the WHERE clause, substituting in the relevant variables for
-?infoResource and core:InformationResource:
+        SELECT DISTINCT <collation-fragment> ?subclass </collation-fragment> ...
 
-    OPTIONAL { GRAPH ?g4 { ?subclass rdfs:subClassOf core:InformationResource }
-        GRAPH ?g5 { ?infoResource a ?subclass } 
-    }  
+    - ?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
 ----------------------
@@ -80,15 +116,15 @@ Datetimes in the query
 ?edTraining:
 
     OPTIONAL { GRAPH ?g9 { ?edTraining core:dateTimeInterval ?dateTimeInterval }
-               OPTIONAL { GRAPH ?g10 { ?dateTimeInterval core:start ?dateTimeStartValue .                     
-                                       ?dateTimeStartValue core:dateTime ?dateTimeStart }
+               OPTIONAL { ?dateTimeInterval core:start ?dateTimeStartValue .                     
+                          ?dateTimeStartValue core:dateTime ?dateTimeStart 
                }
-               OPTIONAL { GRAPH ?g11 { ?dateTimeInterval core:end ?dateTimeEndValue .   
-                                       ?dateTimeEndValue core:dateTime ?dateTimeEnd } 
+               OPTIONAL { ?dateTimeInterval core:end ?dateTimeEndValue .   
+                          ?dateTimeEndValue core:dateTime ?dateTimeEnd 
                }                                       
     }    
 
-The variables ?dateTimeStart and ?dateTimeEnd are included in the SELECT clause.
+- 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, 
@@ -110,12 +146,12 @@ THE TEMPLATE
             <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)
+            <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 query requirements"), or 
-alternatively the template can use the localname function: ${localname(org)}.
+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.