litvinovg/vitro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

List view configuration doc updates

Browse source
This commit is contained in:
rjy7 2011-01-03 20:12:32 +00:00
parent 0fcd2027e1
commit 0cc376e0a1
1 changed files with 72 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

109
doc/list_view_configuration_guidelines.txt
View file

@ -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.
- 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.
-----------------
Optional elements
-----------------
- 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.
- postprocessor: a Java class that postprocesses the data retrieved from the query before
sending it to the template
- 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.
------------------
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.
- 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.
--------
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 Query Requirements), or
alternatively the template can use the localname function: ${localname(org)}.