com.google.clearsilver.jsilver
Class JSilver

java.lang.Object
  extended by com.google.clearsilver.jsilver.JSilver
All Implemented Interfaces:
DataLoader, TemplateRenderer

public final class JSilver
extends Object
implements TemplateRenderer, DataLoader

JSilver templating system.

This is a pure Java version of ClearSilver.

Example Usage

 // Load resources (e.g. templates) from directory.
 JSilver jSilver = new JSilver(new FileResourceLoader("/path/to/templates"));

 // Set up some data.
 Data data = new Data();
 data.setValue("name.first", "Mr");
 data.setValue("name.last", "Man");

 // Render template to System.out. Writer output = ...;
 jSilver.render("say-hello", data, output);
 
For example usage, see java/com/google/clearsilver/jsilver/examples. Additional options can be passed to the constructor using JSilverOptions.

See Also:
JSilver Docs, ClearSilver Docs, JSilverOptions, Data, ResourceLoader

Field Summary
static String AUTO_ESCAPE_KEY
           
static String VAR_ESCAPE_MODE_KEY
           
 
Constructor Summary
JSilver(ResourceLoader defaultResourceLoader)
          Creates a JSilver instance with default options.
JSilver(ResourceLoader defaultResourceLoader, boolean cacheTemplates)
          Deprecated. Use JSilver(ResourceLoader, JSilverOptions).
JSilver(ResourceLoader defaultResourceLoader, JSilverOptions options)
           
 
Method Summary
 void clearCache()
          Force all cached templates to be cleared.
 Appendable createAppendableBuffer()
          Override this to change the type of Appendable buffer used in render(String, Data).
 Data createData()
          Create new Data instance, ready to be populated.
 EscapeMode getEscapeMode(Data data)
          Determine the escaping to apply based on Config variables in HDF.
 JSilverOptions getOptions()
          Returns a copy of the JSilverOptions used by this JSilver instance.
 ResourceLoader getResourceLoader()
          Gets underlying ResourceLoader so you can access arbitrary files using the same mechanism as JSilver.
 TemplateLoader getTemplateLoader()
          Returns the TemplateLoader used by this JSilver template renderer.
 Data loadData(String dataFileName)
          Loads data in Hierarchical Data Format (HDF) into a new Data object.
 void loadData(String dataFileName, Data output)
          Loads data in Hierarchical Data Format (HDF) into an existing Data object.
 void registerGlobalEscaper(String name, TextFilter escaper)
          Registers a global escaper.
 void registerGlobalFunction(String name, Function function)
          Registers a global Function that can be used from any template.
 void registerGlobalFunction(String name, TextFilter textFilter)
          Registers a global TextFilter as function that can be used from any template.
 void releaseAppendableBuffer(Appendable buffer)
           
 String render(String templateName, Data data)
          Same as TemplateRenderer.render(String, Data, Appendable), except returns rendered template as a String.
 void render(String templateName, Data data, Appendable output)
          Renders a given template and provided data, writing to an arbitrary output.
 void render(String templateName, Data data, Appendable output, ResourceLoader resourceLoader)
          Renders a given template and provided data, writing to an arbitrary output.
 String render(Template template, Data data)
          Same as TemplateRenderer.render(Template,Data,Appendable), except returns rendered template as a String.
 void render(Template template, Data data, Appendable output)
          Renders a given template and provided data, writing to an arbitrary output.
 void render(Template template, Data data, Appendable output, ResourceLoader resourceLoader)
          Renders a given template and provided data, writing to an arbitrary output.
 String renderFromContent(String content, Data data)
          Same as renderFromContent(String, Data, Appendable), except returns rendered template as a String.
 void renderFromContent(String content, Data data, Appendable output)
          Renders a given template from the content passed in.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VAR_ESCAPE_MODE_KEY

public static final String VAR_ESCAPE_MODE_KEY
See Also:
Constant Field Values

AUTO_ESCAPE_KEY

public static final String AUTO_ESCAPE_KEY
See Also:
Constant Field Values
Constructor Detail

JSilver

public JSilver(ResourceLoader defaultResourceLoader,
               JSilverOptions options)
Parameters:
defaultResourceLoader - Where resources (templates, HDF files) should be loaded from. e.g. directory, classpath, memory, etc.
options - Additional options.
See Also:
JSilverOptions

JSilver

@Deprecated
public JSilver(ResourceLoader defaultResourceLoader,
                          boolean cacheTemplates)
Deprecated. Use JSilver(ResourceLoader, JSilverOptions).

Parameters:
defaultResourceLoader - Where resources (templates, HDF files) should be loaded from. e.g. directory, classpath, memory, etc.
cacheTemplates - Whether to cache templates. Cached templates are much faster but do not check the filesystem for updates. Use true in prod, false in dev.

JSilver

public JSilver(ResourceLoader defaultResourceLoader)
Creates a JSilver instance with default options.

Parameters:
defaultResourceLoader - Where resources (templates, HDF files) should be loaded from. e.g. directory, classpath, memory, etc.
See Also:
JSilverOptions
Method Detail

render

public void render(String templateName,
                   Data data,
                   Appendable output,
                   ResourceLoader resourceLoader)
            throws IOException,
                   JSilverException
Renders a given template and provided data, writing to an arbitrary output.

Specified by:
render in interface TemplateRenderer
Parameters:
templateName - Name of template to load (e.g. "things/blah.cs").
data - Data to be used in template.
output - Where template should be rendered to. This can be a Writer, PrintStream, System.out/err), StringBuffer/StringBuilder or anything that implements Appendable
resourceLoader - How to find the template data to render and any included files it depends on.
Throws:
IOException
JSilverException

render

public void render(String templateName,
                   Data data,
                   Appendable output)
            throws IOException,
                   JSilverException
Renders a given template and provided data, writing to an arbitrary output.

Specified by:
render in interface TemplateRenderer
Parameters:
templateName - Name of template to load (e.g. "things/blah.cs").
data - Data to be used in template.
output - Where template should be rendered to. This can be a Writer, PrintStream, System.out/err), StringBuffer/StringBuilder or anything that implements
Throws:
IOException
JSilverException

render

public String render(String templateName,
                     Data data)
              throws IOException,
                     JSilverException
Same as TemplateRenderer.render(String, Data, Appendable), except returns rendered template as a String.

Specified by:
render in interface TemplateRenderer
Throws:
IOException
JSilverException

render

public void render(Template template,
                   Data data,
                   Appendable output,
                   ResourceLoader resourceLoader)
            throws IOException,
                   JSilverException
Renders a given template and provided data, writing to an arbitrary output.

Specified by:
render in interface TemplateRenderer
Parameters:
template - Template to load.
data - Data to be used in template.
output - Where template should be rendered to. This can be a Writer, PrintStream, System.out/err), StringBuffer/StringBuilder or anything that implements java.io.Appendable.
resourceLoader - ResourceLoader to use when reading in included files.
Throws:
IOException
JSilverException

render

public void render(Template template,
                   Data data,
                   Appendable output)
            throws IOException,
                   JSilverException
Renders a given template and provided data, writing to an arbitrary output.

Specified by:
render in interface TemplateRenderer
Parameters:
template - Template to load.
data - Data to be used in template.
output - Where template should be rendered to. This can be a Writer, PrintStream, System.out/err), StringBuffer/StringBuilder or anything that implements java.io.Appendable.
Throws:
IOException
JSilverException

render

public String render(Template template,
                     Data data)
              throws IOException,
                     JSilverException
Description copied from interface: TemplateRenderer
Same as TemplateRenderer.render(Template,Data,Appendable), except returns rendered template as a String.

Specified by:
render in interface TemplateRenderer
Throws:
IOException
JSilverException

renderFromContent

public void renderFromContent(String content,
                              Data data,
                              Appendable output)
                       throws IOException,
                              JSilverException
Renders a given template from the content passed in. That is, the first parameter is the actual template content rather than the filename to load.

Specified by:
renderFromContent in interface TemplateRenderer
Parameters:
content - Content of template (e.g. "Hello <cs var:name ?>").
data - Data to be used in template.
output - Where template should be rendered to. This can be a Writer, PrintStream, System.out/err), StringBuffer/StringBuilder or anything that implements java.io.Appendable
Throws:
IOException
JSilverException

renderFromContent

public String renderFromContent(String content,
                                Data data)
                         throws IOException,
                                JSilverException
Same as renderFromContent(String, Data, Appendable), except returns rendered template as a String.

Specified by:
renderFromContent in interface TemplateRenderer
Throws:
IOException
JSilverException

getEscapeMode

public EscapeMode getEscapeMode(Data data)
Determine the escaping to apply based on Config variables in HDF. If there is no escaping specified in the HDF, check whether JSilverOptions has any escaping configured.

Parameters:
data - HDF Data to check
Returns:
EscapeMode

createAppendableBuffer

public Appendable createAppendableBuffer()
Override this to change the type of Appendable buffer used in render(String, Data).


releaseAppendableBuffer

public void releaseAppendableBuffer(Appendable buffer)

registerGlobalFunction

public void registerGlobalFunction(String name,
                                   Function function)
Registers a global Function that can be used from any template.


registerGlobalFunction

public void registerGlobalFunction(String name,
                                   TextFilter textFilter)
Registers a global TextFilter as function that can be used from any template.


registerGlobalEscaper

public void registerGlobalEscaper(String name,
                                  TextFilter escaper)
Registers a global escaper. This also makes it available as a Function named with "_escape" suffix (e.g. "html_escape").


createData

public Data createData()
Create new Data instance, ready to be populated.

Specified by:
createData in interface DataLoader

loadData

public void loadData(String dataFileName,
                     Data output)
              throws JSilverBadSyntaxException,
                     IOException
Loads data in Hierarchical Data Format (HDF) into an existing Data object.

Specified by:
loadData in interface DataLoader
Throws:
JSilverBadSyntaxException
IOException

loadData

public Data loadData(String dataFileName)
              throws IOException
Loads data in Hierarchical Data Format (HDF) into a new Data object.

Specified by:
loadData in interface DataLoader
Throws:
IOException

getResourceLoader

public ResourceLoader getResourceLoader()
Gets underlying ResourceLoader so you can access arbitrary files using the same mechanism as JSilver.


clearCache

public void clearCache()
Force all cached templates to be cleared.


getTemplateLoader

public TemplateLoader getTemplateLoader()
Returns the TemplateLoader used by this JSilver template renderer. Needed for HDF/CS compatbility.


getOptions

public JSilverOptions getOptions()
Returns a copy of the JSilverOptions used by this JSilver instance.



Copyright © 2010-2012 Google. All Rights Reserved.