diff --git a/doc/list_view_configuration_guidelines.txt b/doc/list_view_configuration_guidelines.txt index 550d5397a..9a5c89dda 100644 --- a/doc/list_view_configuration_guidelines.txt +++ b/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 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 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 ?subclass ... - 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 ?subclass ... + + - Include the following in the WHERE clause, substituting in the relevant variables for + ?infoResource and core:InformationResource: + + + OPTIONAL { ?subclass rdfs:subClassOf core:InformationResource . + ?infoResource a ?subclass + } + - 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 ${statement.orgName} <#else> <#-- This shouldn't happen, but we must provide for it --> - ${statement.edTrainingName} (no linked organization) + ${statement.edTrainingName} (no linked organization) -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.