org.webmacro.directive
Class IncludeDirective

java.lang.Object
  extended byorg.webmacro.directive.Directive
      extended byorg.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|macro] quoted-string-variable
IncludeDirective has 4 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

    Files included as text are located once. Changes to the included file will not be found by WebMacro!

    Examples:

    
       // include your system password file (not a good idea! :)
       #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.

    Please note that files included "as template" that contains #macro's DO NOT make their #macro's available to the outer template. See "Including as macro" below for this.

    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).

    Files included as templates are located and conditionally reloaded/parsed when they change.

    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 as macro
    Including a file as a macro is similiar to the above, except that #macro's defined in the included file are made available to the outer template. "Macro" templates are found using the same TemplatePath settings as "#include as template".

    Files included as macros are located once. Changes to the included template will not be found by WebMacro!

    Exapmles:

    
       // include a template with macros
       #include as macro "my_macros.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
    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

    Nested Class Summary
     
    Nested classes inherited from class org.webmacro.directive.Directive
    Directive.ArgDescriptor, Directive.AssignmentArg, Directive.BlockArg, Directive.ConditionArg, Directive.ExactlyOneChoice, Directive.FormalArgListArg, Directive.KeywordArg, Directive.LiteralBlockArg, Directive.LValueArg, Directive.NameArg, 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
              the name given to the directive by webmacro configuration.
    protected  Log _log
              Logging can be good
    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
    static int TYPE_MACRO
              the file to include as a Template containing #macro's
    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_ARGLIST, ArgType_ASSIGN, ArgType_BLOCK, ArgType_CHOICE, ArgType_CONDITION, ArgType_GROUP, ArgType_KEYWORD, ArgType_LITBLOCK, ArgType_LVALUE, ArgType_NAME, 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.
     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

    See Also:
    Constant Field Values

    TYPE_MACRO

    public static final int TYPE_MACRO
    the file to include as a Template containing #macro's

    See Also:
    Constant Field Values

    TYPE_TEXT

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

    See Also:
    Constant Field Values

    TYPE_DYNAMIC

    public static final int TYPE_DYNAMIC
    the file to include is unknown

    See Also:
    Constant Field Values

    _log

    protected Log _log
    Logging can be good


    _type

    protected int _type
    the included file type. one of TYPE_TEMPLATE, TYPE_STATIC, TYPE_MACRO, or TYPE_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
    the name given to the directive by webmacro configuration. Used in conjuction with the StrictCompatibility configuration and to make determinitaions on how the #included file should be included.

    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.

    The specified file to include is included during build/parse time if:
    1) The specified filename is a String, not a $Variable; and
    2) The "as" keyword is "macro"; or
    3) if the Lazy configuration option is set for this directive.

    Otherwise, template is found and including during runtime evaluation of this directive.

    Specified by:
    build in class Directive
    Throws:
    BuildException

    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

    Throws:
    PropertyException - if required data was missing from context
    java.io.IOException - if we could not successfully write to out

    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. This method does not know how to get a file whose type is "TYPE_DYNAMIC".

    Throws:
    PropertyException

    getTemplate

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

    Throws:
    PropertyException

    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).

    Throws:
    PropertyException

    accept

    public void accept(TemplateVisitor v)
    Specified by:
    accept in interface Visitable
    Overrides:
    accept in class Directive