NIHVIVO-564 data model dump: add help for directives in the data model

webapp/src/edu/cornell/mannlib/vitro/webapp/web/directives/DumpDataModelDirective.java

@@ -25,7 +25,7 @@ import freemarker.template.TemplateModel;
 import freemarker.template.TemplateModelException;
 import freemarker.template.utility.DeepUnwrap;
 
-public class DumpDataModelDirective implements TemplateDirectiveModel {
+public class DumpDataModelDirective implements VitroTemplateDirectiveModel {
 
     private static final Log log = LogFactory.getLog(DumpDataModelDirective.class);
     
@@ -47,23 +47,28 @@ public class DumpDataModelDirective implements TemplateDirectiveModel {
                 "The dumpDataModel directive doesn't allow nested content.");
         }
 
+        Configuration config = env.getConfiguration();
         TemplateHashModel dataModel = env.getDataModel();
         Map<String, Object> models = new HashMap<String, Object>();
-        List<String> directives = new ArrayList<String>();
+        Map<String, String> directives = new HashMap<String, String>();
           
         Map<String, Object> dm = (Map<String, Object>) DeepUnwrap.permissiveUnwrap(dataModel);
         List<String> varNames = new ArrayList(dm.keySet()); 
         Collections.sort(varNames);
         for (String var : varNames) {
+            // RY Instead, push each var/directive through the template and return a string.
+            // The meat of dumpDirective will go in a helper.
+            // Send the two lists of strings (variables and directives) to dump-datamodel.ftl.
+            // That way, the directive dump won't be broken up into two pieces, for example.
             Object value = dm.get(var);
-            if (value instanceof TemplateDirectiveModel) {
+            if (value instanceof VitroTemplateDirectiveModel) {
-                directives.add((String) var);
+                String help = ((VitroTemplateDirectiveModel) value).help(config);
+                directives.put(var, help);
             } else {
                 models.put(var, value);
             }
         }
 
-        Configuration config = env.getConfiguration();
         String templateName = "dump-datamodel.ftl";
         
         Map<String, Object> map = new HashMap<String, Object>();
@@ -84,4 +89,18 @@ public class DumpDataModelDirective implements TemplateDirectiveModel {
 
     }
 
+    @Override
+    public String help(Configuration config) {
+        Map<String, Object> map = new HashMap<String, Object>();
+        map.put("usage", "Dump the contents of the template data model.");
+
+        map.put("comments", "Sequences (lists and arrays) are enclosed in square brackets. Hashes are enclosed in curly braces.");
+        
+        List<String> examples = new ArrayList<String>();
+        examples.add("<@dumpDataModel />");
+        map.put("examples", examples);
+        
+        return new FreemarkerHelper().mergeMapToTemplate("dump-directive-help.ftl", map, config);
+    }
+
 }

webapp/src/edu/cornell/mannlib/vitro/webapp/web/directives/DumpDirective.java

@@ -4,7 +4,9 @@ package edu.cornell.mannlib.vitro.webapp.web.directives;
 
 import java.io.IOException;
 import java.io.Writer;
+import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 
 import org.apache.commons.logging.Log;
@@ -17,7 +19,6 @@ import freemarker.template.SimpleScalar;
 import freemarker.template.TemplateBooleanModel;
 import freemarker.template.TemplateDateModel;
 import freemarker.template.TemplateDirectiveBody;
-import freemarker.template.TemplateDirectiveModel;
 import freemarker.template.TemplateException;
 import freemarker.template.TemplateHashModel;
 import freemarker.template.TemplateModel;
@@ -26,7 +27,7 @@ import freemarker.template.TemplateNumberModel;
 import freemarker.template.TemplateScalarModel;
 import freemarker.template.TemplateSequenceModel;
 
-public class DumpDirective implements TemplateDirectiveModel {
+public class DumpDirective implements VitroTemplateDirectiveModel {
 
     private static final Log log = LogFactory.getLog(DumpDirective.class);
     
@@ -113,4 +114,21 @@ public class DumpDirective implements TemplateDirectiveModel {
 
     }
     
+    public String help(Configuration config) {
+        Map<String, Object> map = new HashMap<String, Object>();
+        map.put("usage", "Dump the contents of a template variable.");
+        
+        map.put("comments", "Sequences (lists and arrays) are enclosed in square brackets. Hashes are enclosed in curly braces.");
+        
+        Map<String, String> params = new HashMap<String, String>();
+        params.put("var", "name of variable to dump");
+        map.put("params", params);
+        
+        List<String> examples = new ArrayList<String>();
+        examples.add("<@dump var=\"urls\" />");
+        map.put("examples", examples);
+        
+        return new FreemarkerHelper().mergeMapToTemplate("dump-directive-help.ftl", map, config);
+    }
+
 }

webapp/src/edu/cornell/mannlib/vitro/webapp/web/directives/VitroTemplateDirectiveModel.java

@@ -0,0 +1,10 @@
+package edu.cornell.mannlib.vitro.webapp.web.directives;
+
+import freemarker.template.Configuration;
+import freemarker.template.TemplateDirectiveModel;
+
+public interface VitroTemplateDirectiveModel extends TemplateDirectiveModel {
+    
+    public String help(Configuration config);
+
+}

webapp/web/css/dump.css

@@ -12,3 +12,7 @@
 .dump li {
     list-style-type: none;
 }
+
+.dump.directive h6 {
+    margin-top: 1em;
+}

webapp/web/templates/freemarker/body/partials/dump/dump-datamodel.ftl

@@ -4,9 +4,9 @@
 
 <div class="dump datamodel">
 
-    <h4>Data Model Dump for Template <em>${containingTemplate}</em></h6>
+    <h3>Data Model Dump for Template <em>${containingTemplate}</em></h3>
     
-    <h5>Variables</h5>
+    <h4>VARIABLES</h4>
     
     <ul>
         <#list models?keys as key>
@@ -14,10 +14,13 @@
         </#list>
     </ul>
     
-    <h5>Directives</h5>
+    <h4>DIRECTIVES</h4>
     <ul>
-        <#list directives as directive>
+        <#list directives?keys as directive>
-            <li>${directive}</li>
+            <li class="dump directive">
+                <p><strong>Directive name:</strong> ${directive}</p> 
+                ${directives[directive]!"no help available for this directive"}         
+            </li>
         </#list> 
     </ul> 
       

webapp/web/templates/freemarker/body/partials/dump/dump-directive-help.ftl

@@ -0,0 +1,29 @@
+<#-- $This file is distributed under the terms of the license in /doc/license.txt$ -->
+
+<#-- Template for dumping directive help -->
+
+<p><strong>Usage:</strong> ${usage!}</p>
+
+<#if comments??>
+    <p><strong>Comments:</strong> ${comments}</p>     
+</#if>      
+
+<h6>Parameters:</h6>
+<#if params?? && params?keys?has_content>
+    <ul>
+        <#list params?keys as param>
+            <li><strong>${param}:</strong> ${params[param]}</li>   
+        </#list>
+    </ul>
+<#else>
+    <p>none</p>
+</#if>
+
+<h6>Examples:</h6>
+<#if examples??>
+    <ul>
+        <#list examples as example>
+            <li>${example}</li>
+        </#list>   
+    </ul>
+</#if>