List view configuration doc updates

doc/list_view_configuration_guidelines.txt

@@ -1,18 +1,30 @@
 List view configuration guidelines
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* Required elements: 
+-----------------
+Required elements
+-----------------
+
+- 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
 
-* Optional elements: 
+
+-----------------
+Optional elements
+----------------- 
+    
 - postprocessor: a Java class that postprocesses the data retrieved from the query before
                  sending it to the template
 
-* Query requirements:
+
+------------------
+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.
+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 
@@ -44,3 +56,26 @@ List view configuration guidelines
       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)}.
+