119 lines
5.3 KiB
Text
119 lines
5.3 KiB
Text
List view configuration guidelines
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
-----------------
|
|
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
|
|
- 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
|
|
-----------------
|
|
|
|
- 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
|
|
---------
|
|
|
|
--------------------------
|
|
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
|
|
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.
|
|
|
|
### TO BE AMENDED - use uniongraph instead
|
|
- 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).
|
|
|
|
---------------------------
|
|
Query for collated property
|
|
---------------------------
|
|
|
|
- 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 }
|
|
}
|
|
|
|
- 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 { 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.
|
|
|
|
|
|
------------
|
|
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 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.
|