org.webmacro.directive
Class IncludeDirective

java.lang.Object
  |
  +--org.webmacro.directive.Directive
        |
        +--org.webmacro.directive.IncludeDirective
All Implemented Interfaces:
Macro, Visitable

public class IncludeDirective
extends Directive

IncludeDirective allows you to include other text files or Templates into the current Template.

Syntax:

    #include [as text|template] quoted-string-variable
IncludeDirective has 3 modes of operation which are detailed below.

Please note that #include is now the preferred way to include files or templates. Although you can still use #parse (in the same manner as described below), its use has been deprecated.

Including as text
Including a file as text causes the raw bytes of the file to be included in the current template. The file is not considered to be a Template, and is not parsed by WebMacro. This allows you to include external files that contain javascript or stylesheets without fear of mangling by WebMacro's parser.

Files included as text are found using the default URLProvider. If the URLProvider cannot find the file, the Broker is asked to find it. This allows you to include files from any of the following places:

  • other websites
  • local filesystem
  • active classpath

    Examples:

     
       // include your system password file
       #include as text "/etc/password"
    
       // include the WebMacro homepage
       #include as text "http://www.webmacro.org"
    
       // inlude a file that is in your classpath
       #include as text "somefile.txt"
    
     

    Including as template
    Including a file as template causes the file to be parsed and evaluated by WebMacro using the current Context. The evaluated output of the Template is included in your main template.

    Files included as template are found in your TemplatePath. This path, if not explicitly set in WebMacro.properties, defaults to the system classpath (standalone and JSDK 1.0), or the "web-app" directory (JSDK 2.x).

    Examples:

    
       // include a global header template
       #include as template "header.wm"
    
       // include a header template from a subdirectory of your TemplatePath
       #include as template "common/header.wm"
    
       // include a header template using an absolute path in your TemplatePath
       #include as template "/mysite/common/header.wm"
    
     
    Including without qualification
    Including a file without first qualifing it as a text file or template causes IncludeDirective to make some educated guesses about what type of file it is.

    If the filename contains ://, it is assumed to be a URL and is treated as if it were a text file.

    Else if the filename ends with any of the configured template file extensions (see below), it is assumed to be a template.

    Else it is assumed to be text.

    Examples:

    
        // include homepage of WebMacro -- assumed to be "as text"
        #include "http://www.webmacro.org/"
    
        // include a template -- assumed to be "as template"
        #include "header.wm"
    
        // include a text file from local filesystem -- assumed to be "as text"
        #include "somefile.txt"
    
     
    WebMacro.properties Configuration Options
    The IncludeDirective has a set of configuration options that make its syntax easier to use and enforce strict backwards compatibility with earlier versions of WebMacro. These settings apply to both #include and the deprecated #parse directives. Simply substitute the property prefix include with parse to configure settings differently per directive.

    include.Lazy = true | false (default = true)
    This is an optimization feature that specifies when files should be included.

    If include.Lazy is true, files are included during runtime evaluation of the main template. This allows you to take advantage of the ReloadOnChange features of the TemplateProvider. Most useful during development.

    If set to false, files are included during the parsing step of the main template. Although changes in the included files will not be seen, the advantage to setting include.Lazy to false is performance. Included files are found and/or parsed only once. Very useful for production settings that don't need to recognize changed templates.

    include.StrictCompatibility = true | false (default = false)
    This forces IncludeDirective, when being used as #include, to be 100% compatible with previous versions of WebMacro.

    If set to true unqualified #include'd files will always be assumed to be text.

    If set to false (the default), unqualified #include'd files will have their type (text or template) determined using the rules outlined above in Including without qualification parse.StrictCompatibility = true | false (default = true)
    This forces IncludeDirective, when being used as #parse, to be 100% compatible with previous versions of WebMacro.

    If set to true (the default), unqualified #parse'd files will always be assumed to be Templates.

    If set to false (the default), unqualified #include'd files will have their type (text or template) determined using the rules outlined above in Including without qualification.

    Please remember that #parse has been deprecated. You should use #include in all cases when including files.

    include.TemplateExtensions = list of file extensions
    This list of file extensions is used to determine the file type of an unqualified #include'd file.

    The default set of extensions are: wm, wmt, tml

    Since:
    the beginning, but consolidated with #parse post 0.97
    Author:
    Eric B. Ridge

    Inner classes inherited from class org.webmacro.directive.Directive
    Directive.ArgDescriptor, Directive.AssignmentArg, Directive.BlockArg, Directive.ConditionArg, Directive.KeywordArg, Directive.LiteralBlockArg, Directive.LValueArg, Directive.NotSimpleVariableBuildException, Directive.NotVariableBuildException, Directive.OptionalGroup, Directive.OptionalRepeatingSubdirective, Directive.OptionalSubdirective, Directive.OptionChoice, Directive.QuotedStringArg, Directive.RValueArg, Directive.SingleOptionChoice, Directive.StringArg, Directive.Subdirective
     
    Field Summary
    protected  java.lang.String _directiveName
               
    protected  Macro _macFilename
              the filename as a Macro, if the filename arg is a Macro
    protected  java.lang.String _strFilename
              the filename as a String, if it is something we can determine during build()
    protected  int _type
              the included file type.
    static int TYPE_DYNAMIC
              the file to include is unknown, so we'll need to figure it out based on filename
    static int TYPE_TEMPLATE
              the file to include is a Template
    static int TYPE_TEXT
              the file to include is a static file
     
    Fields inherited from class org.webmacro.directive.Directive
    ArgType_ASSIGN, ArgType_BLOCK, ArgType_CHOICE, ArgType_CONDITION, ArgType_GROUP, ArgType_KEYWORD, ArgType_LITBLOCK, ArgType_LVALUE, ArgType_QUOTEDSTRING, ArgType_RVALUE, ArgType_STRING, ArgType_SUBDIRECTIVE
     
    Constructor Summary
    IncludeDirective()
               
     
    Method Summary
     void accept(TemplateVisitor v)
               
     java.lang.Object build(DirectiveBuilder builder, BuildContext bc)
              Build this use of the directive.
    static DirectiveDescriptor getDescriptor()
               
    protected  java.lang.String getFile(Broker b, java.lang.String name)
              get the contents of a file (local file or url) via the "url" provider known by the specified broker.
    protected  Template getTemplate(Broker b, java.lang.String name)
              get a Template via the "template" provider known by the specified broker
    protected  java.lang.String[] getTemplateExtensions(Broker b)
              get an array of Template file extensions we should use, if type==dynamic, to decide if the specified file is a template or not
    protected  java.lang.Object getThingToInclude(Broker b, int type, java.lang.String filename)
              get the template or file that the user wants to include, based on the specified type
    protected  int guessType(Broker b, java.lang.String filename)
              if the filename contains :// assume it's a file b/c it's probably a url.
    protected  boolean isLazy(Broker b)
              are we configured to lazily include the file/template (meaning during expansion)? If not, we end up inserting the template/file contents during build().
    protected  boolean isStrictlyCompatible(Broker b)
              are we strictly compatible with previous versions of both #parse and #include? Default is no, we are not strictly compatible b/c we can get pretty close by dynamically figuring out the file type and b/c #parse has been deprecated.
     void write(FastWriter out, Context context)
              Write out the included file to the specified FastWriter.
     
    Methods inherited from class org.webmacro.directive.Directive
    evaluate, getWarningText, writeWarning
     
    Methods inherited from class java.lang.Object
    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     

    Field Detail

    TYPE_TEMPLATE

    public static final int TYPE_TEMPLATE
    the file to include is a Template

    TYPE_TEXT

    public static final int TYPE_TEXT
    the file to include is a static file

    TYPE_DYNAMIC

    public static final int TYPE_DYNAMIC
    the file to include is unknown, so we'll need to figure it out based on filename

    _type

    protected int _type
    the included file type. one of TYPE_TEMPLATE, TEXT, or DYNAMIC

    _macFilename

    protected Macro _macFilename
    the filename as a Macro, if the filename arg is a Macro

    _strFilename

    protected java.lang.String _strFilename
    the filename as a String, if it is something we can determine during build()

    _directiveName

    protected java.lang.String _directiveName
    Constructor Detail

    IncludeDirective

    public IncludeDirective()
    Method Detail

    getDescriptor

    public static DirectiveDescriptor getDescriptor()

    build

    public final java.lang.Object build(DirectiveBuilder builder,
                                        BuildContext bc)
                                 throws BuildException
    Build this use of the directive.

    We perform some build-time optimizations if the Lazy configuration parameter is false and if we are able to determine the filename during build(). In this case, the included file (or template) is found (and/or parsed) and returned from this method. Note that this eliminates the ability for #include'd files/template to "reload on change", but this is configurable and documented here and above.

    Overrides:
    build in class Directive

    write

    public void write(FastWriter out,
                      Context context)
               throws PropertyException,
                      java.io.IOException
    Write out the included file to the specified FastWriter. If the included file is actually a template, it is evaluated against the context parameter before being written to the FastWriter
    Following copied from interface: org.webmacro.Macro
    Throws:
    PropertyException - if required data was missing from context
    java.io.IOException - if we could not successfully write to out

    isLazy

    protected boolean isLazy(Broker b)
    are we configured to lazily include the file/template (meaning during expansion)? If not, we end up inserting the template/file contents during build(). Default is yes, be lazy.

    isStrictlyCompatible

    protected boolean isStrictlyCompatible(Broker b)
    are we strictly compatible with previous versions of both #parse and #include? Default is no, we are not strictly compatible b/c we can get pretty close by dynamically figuring out the file type and b/c #parse has been deprecated.

    getTemplateExtensions

    protected java.lang.String[] getTemplateExtensions(Broker b)
    get an array of Template file extensions we should use, if type==dynamic, to decide if the specified file is a template or not

    guessType

    protected int guessType(Broker b,
                            java.lang.String filename)
    if the filename contains :// assume it's a file b/c it's probably a url.

    If the filename ends with any of the configured ParseDirective.TemplateExtensions, assume it's a template.

    Otherwise, it must be a file


    getThingToInclude

    protected java.lang.Object getThingToInclude(Broker b,
                                                 int type,
                                                 java.lang.String filename)
                                          throws PropertyException
    get the template or file that the user wants to include, based on the specified type

    getTemplate

    protected Template getTemplate(Broker b,
                                   java.lang.String name)
                            throws PropertyException
    get a Template via the "template" provider known by the specified broker

    getFile

    protected java.lang.String getFile(Broker b,
                                       java.lang.String name)
                                throws PropertyException
    get the contents of a file (local file or url) via the "url" provider known by the specified broker. If the url provider can't find it we check the Broker (Broker.getResource).

    accept

    public void accept(TemplateVisitor v)
    Overrides:
    accept in class Directive