diff --git a/doc/list_view_configuration_guidelines.txt b/doc/list_view_configuration_guidelines.txt index 406536578..84cc3e320 100644 --- a/doc/list_view_configuration_guidelines.txt +++ b/doc/list_view_configuration_guidelines.txt @@ -1,46 +1,81 @@ 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 +----------------- +Required elements +----------------- -* Optional elements: - - postprocessor: a Java class that postprocesses the data retrieved from the query before - sending it to the template +- list-view-config: root element +- query: the sparql query used to retrieve the data +- template: the name of the template used to display a single property statement -* 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. + +----------------- +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, 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. 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. +- 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. +- 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). +- 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 +- 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. + + +-------- +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??> + ${statement.orgName} + <#else> + <#-- This shouldn't happen, but we must provide for it --> + ${statement.edTrainingName} (no linked organization) + + + + The query must have been constructed to return orgName (see above under Query Requirements), or + alternatively the template can use the localname function: ${localname(org)}. +