|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.webmacro.directive.Directive | +--org.webmacro.directive.IncludeDirective
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:
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"
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
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 OptionsIncludeDirective
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
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 |
public static final int TYPE_TEMPLATE
public static final int TYPE_TEXT
public static final int TYPE_DYNAMIC
protected int _type
protected Macro _macFilename
protected java.lang.String _strFilename
protected java.lang.String _directiveName
Constructor Detail |
public IncludeDirective()
Method Detail |
public static DirectiveDescriptor getDescriptor()
public final java.lang.Object build(DirectiveBuilder builder, BuildContext bc) throws BuildException
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.
public void write(FastWriter out, Context context) throws PropertyException, java.io.IOException
context
parameter before being written to the FastWriterorg.webmacro.Macro
PropertyException
- if required data was missing from contextjava.io.IOException
- if we could not successfully write to outprotected boolean isLazy(Broker b)
protected boolean isStrictlyCompatible(Broker b)
protected java.lang.String[] getTemplateExtensions(Broker b)
protected int guessType(Broker b, java.lang.String filename)
If the filename ends with any of the configured
ParseDirective.TemplateExtensions
, assume it's a template.
Otherwise, it must be a file
protected java.lang.Object getThingToInclude(Broker b, int type, java.lang.String filename) throws PropertyException
protected Template getTemplate(Broker b, java.lang.String name) throws PropertyException
protected java.lang.String getFile(Broker b, java.lang.String name) throws PropertyException
public void accept(TemplateVisitor v)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |