diff --git a/doc/list_view_configuration_guidelines.txt b/doc/list_view_configuration_guidelines.txt new file mode 100644 index 000000000..406536578 --- /dev/null +++ b/doc/list_view_configuration_guidelines.txt @@ -0,0 +1,46 @@ +List view configuration guidelines +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Required elements: + - 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 + +* 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. 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. 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. + + - It is generally necessary to provide for a missing linked individual, due to 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 claus. 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. \ No newline at end of file