Author: cbrisson
Date: Mon Mar 11 00:22:24 2019
New Revision: 1855183
URL: http://svn.apache.org/viewvc?rev=1855183&view=rev
Log:
[site/engine] Propagate property names and semantics changes - added summary
tree
Modified:
velocity/site/cms/trunk/content/engine/devel/configuration-property-changes-in-2.1.mdtext
velocity/site/cms/trunk/content/engine/devel/configuration.mdtext
velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext
velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext
velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext
velocity/site/cms/trunk/content/engine/devel/webapps.mdtext
Modified:
velocity/site/cms/trunk/content/engine/devel/configuration-property-changes-in-2.1.mdtext
URL:
http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/configuration-property-changes-in-2.1.mdtext?rev=1855183&r1=1855182&r2=1855183&view=diff
==============================================================================
---
velocity/site/cms/trunk/content/engine/devel/configuration-property-changes-in-2.1.mdtext
(original)
+++
velocity/site/cms/trunk/content/engine/devel/configuration-property-changes-in-2.1.mdtext
Mon Mar 11 00:22:24 2019
@@ -1,52 +1,63 @@
-# Configuration Changes in Velocity Engine 2.1
+## Configuration Properties Changes between Engine 2.0 and Engine 2.1
-## Configuration Property Name Changes
+Velocity Engine configuration property names have been reviewed in Engine 2.1
for clarity and consistency.
-Velocity configuration property names have been reviewed in Engine 2.1 for
clarity and consistency.
+**Old property names are still functional but have been deprecated** and will
be removed in Engine 3.0. Velocity will emit warnings in the logs when old
property names are used.
-Old property names are still functional but have been deprecated and will be
removed in Engine 3.0. Velocity will emit warnings in the logs when old
property names are used.
+### Changes Summary
-Property names changes:
-
-Old property name | New property name | Property purpose
+2.0 property name | 2.1 property name | Property purpose
------------------|------------------ |-----------------
+runtime.log.instance | *unchanged* | org.slf4j.Logger instance
+runtime.log.name | *unchanged* | org.slf4j.Logger name
+runtime.log.invalid.references | runtime.log.log_invalid_references | whether
to log invalid references
+*n/a* | runtime.log.log_invalid_method_calls | whether to log invalid method
calls
resource.loader | resource.loaders | list of resource loader names
<name>.resource.loader.<prop> |
resource.loader.<name>.<prop> | property of a named resource loader
<name>.resource.loader.modificationCheckInterval |
resource.loader.<name>.modification_check_interval | modification check
interval of a named resource loader
+resource.manager.instance | *unchanged* | resource manager live instance
+resource.manager.class | *unchanged* | resource manager class
+resource.manager.cache.class | *unchanged* | resource manager cache class
resource.manager.defaultcache.size | resource.manager.cache.default_size |
resource manager default cache size
resource.manager.logwhenfound | resource.manager.log_when_found | whether to
log when a resource is found
<scope>.provide.scope.control | context.scope_control.<scope> |
enabling scope control object in the context for a specific scope
-runtime.log.invalid.references | runtime.log.log_invalid_references | whether
to log invalid references
runtime.string.interning | runtime.string_interning | whether to use string
interning
+directive.define.max.depth | directive.define.max_depth | max depth for the
`#define` directive
directive.foreach.maxloops | directive.foreach.max_loops | maximum number of
loops of a `#foreach` directive
directive.foreach.skip.invalid | directive.foreach.skip_invalid | whether to
skip bad iterables
directive.if.emptycheck | directive.if.empty_check | whether the `#if`
directive checks objects for emptiness
-directive.include.output.errormsg.start | directive.include.output_error_start
| error message prefix for `#include` and `#parse`
-directive.include.output.errormsg.end | directive.include.output_error_end |
error message suffix for `#include` and `#parse`
-directive.define.max.depth | directive.define.max_depth | max depth for the
`#define` directive
+directive.include.output.errormsg.start | directive.include.output_error_start
(deprecated) | error message prefix for `#include` and `#parse`
+directive.include.output.errormsg.end | directive.include.output_error_end
(deprecated) | error message suffix for `#include` and `#parse`
+directive.parse.max.depth | directive.parse.max_depth | max depth for the
`#parse` directive
userdirective (undocumented) | runtime.custom_directives | list of custom
directives
eventhandler.referenceinsertion.class |
event_handler.reference_insertion.class | list of reference insertion event
handler classes
eventhandler.methodexception.class | event_handler.method_exception.class |
list of method exception event handler classes
eventhandler.include.class | event_handler.include.class | list of file
inclusion event handler classes
eventhandler.invalidreferences.class | event_handler.invalid_references.class
| list of invalid reference event handler classes
velocimacro.library | velocimacro.library.path | path to the velocimacro
library template
+velocimacro.library.autoreload | *unchanged* | whether to autoreload library
velocimacro.permissions.allow.inline | velocimacro.inline.allow | whether to
allow inline velocimacros
velocimacro.permissions.allow.inline.to.replace.global |
velocimacro.inline.replace_global | whether inline macros override global ones
velocimacro.permissions.allow.inline.local.scope |
velocimacro.inline.local_scope | whether inline macros have a local scope
+velocimacro.arguments.strict | *unchanged* | expect strict argments number
+*n/a* | velocimacro.arguments.preserve_literals | whether invalid references
is literal provided argument or argument name
velocimacro.max.depth | velocimacro.max_depth | velocimacros max calling depth
velocimacro.body.reference | velocimacro.body_reference | name of the
reference holding the body passed to a block macro
runtime.references.strict | runtime.strict_mode.enable | enables strict
rendering mode
runtime.references.strict.escape | runtime.strict_mode.escape | toggles
modified escaping in strict rendering mode
-runtime.introspector.uberspect | introspector.uberspect | list of chained
uberspectors classnames
-runtime.conversion.handler.instance (since 2.0) |
introspector.conversion_handler.class | method arguments conversion handler
classname
+runtime.introspector.uberspect | introspector.uberspect.class | list of
chained uberspectors classnames
+introspector.restrict.packages | *unchanged* | restricted packages for
SecureIntrospector
+introspector.restrict.classes | *unchanged* | restricted classes for
SecureIntrospector
+runtime.conversion.handler.class (since 2.0) |
introspector.conversion_handler.class | method arguments conversion handler
classname
runtime.interpolate.string.literals | runtime.interpolate_string_literals |
whether to interpolate string literals in double quotes
runtime.strict.math | runtime.strict_math | switch for ignoring nulls in math
equations vs throwing exceptions
context.autoreference.key | context.self_reference_key | key upon which a
context should be accessible within itself
+parser.pool.class | *unchanged* | parser pool class
space.gobbling | parser.space_gobbling | space gobbling mode
Also, the default velocimacro library template has been renamed from
`VM_global_library.vm` to `velocimacros.vtl` ; Velocity will check for the old
default path if the new one is not found.
-## New Configuration Properties
+## New Properties Description
Velocity Engine 2.1 introduces the following new properties:
Modified: velocity/site/cms/trunk/content/engine/devel/configuration.mdtext
URL:
http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/configuration.mdtext?rev=1855183&r1=1855182&r2=1855183&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/configuration.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/configuration.mdtext Mon Mar
11 00:22:24 2019
@@ -1,20 +1,86 @@
Title: Apache Velocity Engine - Configuration
-## Velocity Configuration - Contents
+## Configuration
[TOC]
## Configuring Velocity
-Velocity's runtime configuration is controlled by a set of configuration keys
listed below. Generally, these keys will have values that consist of either a
String, or a comma-separated list of Strings, referred to as a CSV for
comma-separated values.
+Velocity's runtime configuration is controlled by a set of configuration keys
listed below. Generally, these keys will have values that consist of either a
String, or a comma-separated list of Strings, referred to as a CSV for
comma-separated values.
-There is a set of default values contained in Velocity's jar, found in
/src/java/org/apache/velocity/runtime/defaults/velocity.defaults, that Velocity
uses as its configuration baseline. This ensures that Velocity will always have
a 'correct' value for its configuration keys at startup, although it may not be
what you want.
+There is a set of default values contained in Velocity's jar, found in
org/apache/velocity/runtime/defaults/velocity.properties, that Velocity uses as
its configuration baseline. This ensures that Velocity will always have a
'correct' value for its configuration keys at startup, although it may not be
what you want.
-Any values specified before init() time will replace the default values.
Therefore, you only have to configure velocity with the values for the keys
that you need to change, and not worry about the rest. Further, as we add more
features and configuration capability, you don't have to change your
configuration files to suit - the Velocity engine will always have default
values.
+Any values specified before init() time will replace the default values.
Therefore, you only have to configure velocity with the values for the keys
that you need to change, and not worry about the rest. Further, as we add more
features and configuration capability, you don't have to change your
configuration files to suit - the Velocity engine will always have default
values.
-Please sees the section [**Using
Velocity**](developer-guide.html#using-velocity) for discussion on the
configuration API.
+Please see the section [**Using
Velocity**](developer-guide.html#using-velocity) for discussion on the
configuration API.
-Below are listed the configuration keys that control Velocity's behavior,
organized by category. Each key is listed with its current default value to the
right of the '=' sign.
+The properties key names have been reviewed in Engine 2.1. Old names are still
functional but will emit a deprecation warning in the log. See the [**table of
correspondance**](configuration-property-changes-in-2.1.html).
+
+## Configuration Summary Tree
+
+The following tree gathers all non deprecated configuration properties with
their default values.
+
+ :::properties
+ context. +-- scope_control. +-- define = false
+ | +-- evaluate = false
+ | +-- foreach = true
+ | +-- macro = false
+ | +-- template = false
+ | +-- *somebodymacro* = false
+ +-- self_reference_key = *key_name*
+
+ directive. +-- define.max_depth = 2
+ +-- foreach. +-- max_loops = -1
+ | +-- skip_invalid = true
+ +-- if. +-- empty_check = true
+ +-- parse. +-- max_depth = 10
+
+ event_handler. +-- include.class = *classname*, *classname* ...
+ +-- invalid_reference.class = *classname*, *classname* ...
+ +-- method_exception.class = *classname*, *classname* ...
+ +-- reference_insertion.class = *classname*, *classname* ...
+
+ introspector. +-- conversion_handler. +-- class =
org.apache.velocity.util.introspection.TypeConversionHandlerImpl
+ | +-- instance = *Java Object instance*
+ +-- uberspect.class =
org.apache.velocity.util.introspection.UberspectImpl
+
+ parser. +-- allow_hyphen_in_identifiers = false
+ +-- pool. +-- class = org.apache.velocity.runtime.ParserPoolImpl
+ | +-- size = 20
+ +-- space_gobbling = lines
+
+ resource. +-- default_encoding = UTF-8
+ +-- loaders = file, ...
+ +-- loader.*loader_name*. +-- class = *classname*
+ | +-- instance = *Java Object instance*
+ | +-- cache = false
+ | +-- modification_check_interval = 2
+ | +-- *loader_prop* = ...
+ +-- manager. +-- cache. +-- class =
org.apache.velocity.runtime.resource.ResourceCacheImpl
+ | +-- default_size = 89
+ +-- class =
org.apache.velocity.runtime.resource.ResourceManagerImpl
+ +-- instance = null
+ +-- log_when_found = true
+
+ runtime. +-- custom_directives = *classname*, *classname* ...
+ +-- interpolate_string_literals = true
+ +-- log. +-- instance = *Java Object instance*
+ | +-- log_invalid_method_calls = true
+ | +-- log_invalid_references = true
+ | +-- name = org.apache.velocity
+ +-- strict_math = false
+ +-- strict_mode. +-- enable = false
+ | +-- escape = false
+ +--string_interning = true
+
+ velocimacro. +-- arguments. +-- preserve_literals = false
+ | +-- strict = false
+ +-- body_reference = false
+ +-- inline. +-- allow = true
+ | +-- local_scope = false
+ | +-- replace_global = false
+ +-- library. +-- autoreload = false
+ +-- path = velocimacros.vtl
## Logging
@@ -26,83 +92,71 @@ Below are listed the configuration keys
> If no living Logger instance has been given using the previous property,
> Velocity will get a Logger object using the provided name.
-**`runtime.log.invalid.references = true`**
+**`runtime.log.log_invalid_references = true`**
> Property to turn off the log output when a reference isn't valid. Good thing
> to turn off in production, but very valuable for debugging.
-## Character Encoding
+**`runtime.log.log_invalid_method_calls = true`**
-**`input.encoding = UTF-8`**
-
-> Character encoding for input (templates). UTF-8 if not specified.
+> Property to turn off the log output when a method call isn't valid or has
thrown. Good thing to turn off in production, but very valuable for debugging.
## VTL Directives
### #define() Directive
-**`define.provide.scope.control = false`**
-
-> Used to turn on the automatic provision of the $define scope control during
#define() calls. The default is false. Set it to true if you want a local,
managed namespace you can put references in when within a #define block or if
you want it for more advanced #break usage.
+**`directive.define.max_depth = 2`**
-### #evaluate() Directive
-
-**`evaluate.provide.scope.control = false`**
-
-> Used to turn on the automatic provision of the $evaluate scope during
#evaluate() or Velocity[Engine].evaluate(...) calls. The default is false. Set
it to true if you want a local, managed namespace you can put references in
during an evaluation or if you want it for more advanced #break usage.
+> Defines the allowable parse depth for the #define directive.
### #foreach() Directive
-**`foreach.provide.scope.control = true`**
-
-> Used to control the automatic provision of the $foreach scope during
#foreach calls. This gives access to the foreach status information (e.g.
$foreach.index or $foreach.hasNext). The default is true. Set it to false if
unused and you want a tiny performance boost.
-
-**`directive.foreach.maxloops = -1`**
+**`directive.foreach.max_loops = -1`**
> Maximum allowed number of loops for a #foreach() statement.
-**`directive.foreach.skip.invalid = true`**
+**`directive.foreach.skip_invalid = true`**
> Tells #foreach to simply skip rendering when the object it is iterating over
> is not or cannot produce a valid Iterator.
### #if() Directive
-**`directive.if.emptycheck = true`**
+**`directive.if.empty_check = true`**
> When evaluating if a reference resolves to `true` or `false` in a boolean
> context, the engine first checks if its value is null, if it is a Boolean or
> if it has a getAsBoolean() method. Then, if none of this applies, the
> behavior depends upon this configuration flag:
>
-> - if `directive.if.emptycheck` is `false`, no further check is performed and
the object resolves to `true`.
-> - if `directive.if.emptycheck` is `true`, the object is check for emptiness
and zero value:
+> - if `directive.if.empty_check` is `false`, no further check is performed
and the object resolves to `true`.
+> - if `directive.if.empty_check` is `true`, the object is check for emptiness
and zero value:
> - return whether an array is empty.
> - return whether isEmpty() is false (covers String and all Collection
> classes).
> - return whether length() is zero (covers CharSequence classes other
> than String).
> - returns whether size() is zero (covers all Collections classes).
> - return whether a Number *strictly* equals zero.
> - return whether the result of getAsString() is empty (and false for a
> null result) if it exists.
-> - return whether the result of getAsNumber() *strictly* equals zero (and
false for a null result) if it exists.
-
-### #set() Directive
-
-**`directive.set.null.allowed = false`**
-
-> If true, having a right hand side of a #set() statement with an invalid
reference or null value will set the left hand side to null. If false, the left
hand side will stay the same.
+> - return whether the result of getAsNumber() *strictly* equals zero (and
false for a null result) if it exists.
### #include() and #parse() Directives
-**`directive.include.output.errormsg.start = <!-- include error :`**
-**`directive.include.output.errormsg.end = see error log --> `**
+**`directive.include.output_error_start = <!-- include error :`**
+**`directive.include.output_error_end = see error log --> `**
+> *Deprecated. If/how errors are displayed is not the concern of the engine,
which should throw in all cases.*
> Defines the beginning and ending tags for an in-stream error message in the
> case of a problem with the #include() directive. If both the .start and .end
> tags are defined, an error message will be output to the stream, of the form
> '.start msg .end' where .start and .end refer to the property values. Output
> to the render stream will only occur if both the .start and .end (next) tag
> are defined.
-**`directive.parse.max.depth = 10`**
+**`directive.parse.max_depth = 10`**
> Defines the allowable parse depth for a template. A template may #parse()
> another template which itself may have a #parse() directive. This value
> prevents runaway #parse() recursion.
-**`template.provide.scope.control = false`**
+### custom directives
-> Used to turn on the automatic provision of the $template scope control
during #parse calls and template.merge(...) calls. The default is false. Set it
to true if you want a secure namespace for your template variables or more
advanced #break control.
+**`runtime.custom_directives = `** *empty*
+> coma separated list of custom directives class names, which must inherit
from `org.apache.velocity.runtime.directive.Directive`.
## Resource Management
+**`resource.default_encoding = UTF-8`**
+
+> Default character encoding for input (templates). UTF-8 if not specified.
+
**`resource.manager.instance = null`**
> Living Java instance, that must implement the interface
> org.apache.velocity.runtime.resource.ResourceManager. This property can only
> be set programmatically, and takes precedence over the next property. It is
> otherwise used by Velocity to store its actual resource manager once
> instanciated.
@@ -112,7 +166,7 @@ Below are listed the configuration keys
The following resource management configuration keys only apply to the default
Resource Manager.
-**`resource.manager.logwhenfound = true`**
+**`resource.manager.log_when_found = true`**
> Switch to control logging of 'found' messages from resource manager. When a
> resource is found for the first time, the resource name and classname of the
> loader that found it will be noted in the runtime log.
@@ -120,82 +174,74 @@ The following resource management config
> Replace the Velocity default Resource Cache class. A resource cache
> implementation must implement the
> (`org.apache.velocity.runtime.resource.ResourceCache`)[apidocs/org/apache/velocity/runtime/resource/ResourceCache.html]
> interface As with the resource manager. A description of the requirements
> of a resource manager is out of scope for this document. Implementors are
> encouraged to review the default implementation.
-**`resource.manager.defaultcache.size = 89`**
+**`resource.manager.cache.default_size = 89`**
-> Sets the size of the default implementation of the resource manager cache
size (in number of elements). When `resource.manager.defaultcache.size` is set
to 0, then the default implementation uses the standard Java
`ConcurrentHashMap`. Otherwise, a non-zero cache size uses an LRU Map. The
default cache size is 89. Note that the ConcurrentHashMap may be better at
thread concurrency.
+> Sets the size of the default implementation of the resource manager cache
size (in number of elements). When `resource.manager.cache.default_size` is set
to 0, then the default implementation uses the standard Java
`ConcurrentHashMap`. Otherwise, a non-zero cache size uses an LRU Map. The
default cache size is 89. Note that the ConcurrentHashMap may be better at
thread concurrency.
-**`resource.loader = file`**
+**`resource.loaders = file`**
> *Multi-valued key. Will accept CSV for value.* Public name of a resource
> loader to be used. This public name will then be used in the specification
> of the specific properties for that resource loader. Note that as a
> multi-valued key, it's possible to pass a value like "file, string" (sans
> quotes), indicating that following will be configuration values for two
> loaders.
-> Please note than [VelocityTools](tools/devel) will override the default
value and set it to `webapp`.
+> In a [VelocityToolsView](/tools/devel/view.html) environment, VelocityView
will override the default value and set it to `webapp`, its webapp resource
loader.
-** *name*`.loader.description = Velocity File Resource Loader`**
+** `resource.loader.`*name*`.description = Velocity File Resource Loader`**
-> Description string for the given loader.
+> Optional description string for the given loader.
-** *name*`.resource.loader.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader`**
+** `resource.loader.`*name*`.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader`**
-> Name of implementation class for the loader. The default loader is the [file
resource
loader](/engine/devel/apidocs/org/apache/velocity/runtime/resource/loader/FileResourceLoader.html)
(or the [webapp resource
loader](/tools/devel/apidocs/org/apache/velocity/tools/view/WebappResourceLoader.html)
for VelocityTools).
+> Name of implementation class for the loader. The default loader is the [file
resource
loader](/engine/devel/apidocs/org/apache/velocity/runtime/resource/loader/FileResourceLoader.html)
(or the [webapp resource
loader](/tools/devel/apidocs/org/apache/velocity/tools/view/WebappResourceLoader.html)
for VelocityTools). See [all available resource
loaders](developer-guide.html#resource-loaders).
-** *name*`.resource.loader.path = .`**
+** `resource.loader.`*name*`.path = .`**
> *Multi-valued key. Will accept CSV for value.* Root(s) from which the loader
> loads templates. Templates may live in subdirectories of this root. ex.
> homesite/index.vm This configuration key applies currently to the
> FileResourceLoader and JarResourceLoader.
-** *name*`.resource.loader.cache = false`**
+** `resource.loader.`*name*`.cache = false`**
> Controls caching of the templates in the loader. Default is false, to make
> life easy for development and debugging. This should be set to true for
> production deployment. When 'true', the `modificationCheckInterval`
> property applies. This allows for the efficiency of caching, with the
> convenience of controlled reloads - useful in a hosted or ISP environment
> where templates can be modifed frequently and bouncing the application or
> servlet engine is not desired or permitted.
-** *name*`.resource.loader.modificationCheckInterval = 2`**
+** `resource.loader.`*name*`.modificationCheckInterval = 2`**
> This is the number of seconds between modification checks when caching is
> turned on. When this is an integer > 0, this represents the number of
> seconds between checks to see if the template was modified. If the template
> has been modified since last check, then it is reloaded and reparsed.
> Otherwise nothing is done. When <= 0, no modification checks will take
> place, and assuming that the property `cache` (above) is true, once a
> template is loaded and parsed the first time it is used, it will not be
> checked or reloaded after that until the application or servlet engine is
> restarted.
> To illustrate, here is an example taken right from the default Velocity
> properties, showing how setting up the FileResourceLoader is managed
:::properties
- resource.loader = file
+ resource.loaders = file
- file.resource.loader.description = Velocity File Resource Loader
- file.resource.loader.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader
- file.resource.loader.path = .
- file.resource.loader.cache = false
- file.resource.loader.modificationCheckInterval = 2
+ resource.loader.file.description = Velocity File Resource Loader
+ resource.loader.file.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader
+ resource.loader.file.path = .
+ resource.loader.file.cache = false
+ resource.loader.file.modification_check_interval = 2
## Velocimacros
-**`velocimacro.library = VM_global_library.vm `**
+**`velocimacro.library.path = velocimacros.vtl `**
-> *Multi-valued key. Will accept CSV for value.* Filename(s) of Velocimacro
library to be loaded when the Velocity Runtime engine starts. These
Velocimacros are accessable to all templates. The file is assumed to be
relative to the root of the file loader resource path.
+> *Multi-valued key. Will accept CSV for value.* Filename(s) of Velocimacro
library to be loaded when the Velocity Runtime engine starts. These
Velocimacros are accessable to all templates. The file is assumed to be
relative to the root of the file loader resource path. If the default
(<code>velocimacro.vtl</code> since 2.1) is not found, the old default
(<code>VM_global_library.vm</code>) is also searched for.
-**`velocimacro.permissions.allow.inline = true`**
+**`velocimacro.inline.allow = true`**
> Determines of the definition of new Velocimacros via the #macro() directive
> in templates is allowed. The default value is true, meaning any template
> can define and use new Velocimacros. Note that depending on other
> properties, those #macro() statements can replace global definitions.
-**`velocimacro.permissions.allow.inline.to.replace.global = false`**
+**`velocimacro.inline.replace_global = false`**
> Controls if a Velocimacro defind 'inline' in a template can replace a
> Velocimacro defined in a library loaded at startup.
-**`velocimacro.permissions.allow.inline.local.scope = false`**
+**`velocimacro.inline.local_scope = false`**
> Controls 'private' templates namespaces for Velocimacros. When true, a
> #macro() directive in a template creates a Velocimacro that is accessable
> only from the defining template. This means that Velocimacros cannot be
> shared unless they are in the global or local library loaded at startup.
> (See above.) It also means that templates cannot interfere with each other.
> This property also allows a technique where there is a 'default'
> Velocimacro definition in the global or local library, and a template can
> 'override' the implementation for use within that template. This occurrs
> because when this property is true, the template's namespace is searched for
> a Velocimacro before the global namespace, therefore allowing the override
> mechanism.
-**`velocimacro.context.localscope = false`**
-
-> Controls whether reference access (set/get) within a Velocimacro will change
the context, or be of local scope in that Velocimacro. This feature is
deprecated and has been removed in Velocity 2.0. Instead, please use the
$macro namespace for storage of references local to your Velocimacro. (e.g.
#set( $macro.foo = 'bar') and $macro.foo)
-
**`velocimacro.library.autoreload = false`**
-> Controls Velocimacro library autoloading. When set to `true` the source
Velocimacro library for an invoked Velocimacro will be checked for changes, and
reloaded if necessary. This allows you to change and test Velocimacro
libraries without having to restart your application or servlet container, just
like you can with regular templates. This mode only works when caching is *off*
in the resource loaders (e.g. `file.resource.loader.cache = false` ). This
feature is intended for development, not for production.
+> Controls Velocimacro library autoloading. When set to `true` the source
Velocimacro library for an invoked Velocimacro will be checked for changes, and
reloaded if necessary. This allows you to change and test Velocimacro
libraries without having to restart your application or servlet container, just
like you can with regular templates. This mode only works when caching is *off*
in the resource loaders (e.g. `resource.loader.file.cache = false` ). This
feature is intended for development, not for production.
**`velocimacro.arguments.strict = false`**
> When set to true, will throw a `ParseErrorException` when parsing a template
> containing a macro with an invalid number of arguments. Is set to false by
> default to maintain backwards compatibility with templates written before
> this feature became available.
-**`velocimacro.body.reference = false`**
-
-> Defines name of the reference that can be used to get the body content (an
AST block) given for a block macro call (e.g. #@myMacro() has a body #end). The
default reference name is "bodyContent" (e.g. $bodyContent). This block macro
feature was introduced in Velocity 1.7.
-
-**`velocimacro.preserve.argument.literals = false`**
+**`velocimacro.arguments.preserve_literals = false`**
> Since 2.0, inside a macro, the rendering of null arguments uses the local
> reference literal. For instance, the following VTL code
>
@@ -205,33 +251,29 @@ The following resource management config
>
> will display `$foo`. To revert to the 1.x behavior, since 2.1, you can set
> this property to true. The previous code will then display `$null`.
-**`macro.provide.scope.control = false`**
-
-> Used to turn on the automatic provision of the $macro scope control during
#macro calls. The default is false. Set it to true if you need a local
namespace in macros or more advanced #break controls.
-
-**`<somebodymacro>.provide.scope.control = false`**
+**`velocimacro.body_reference = false`**
-> Used to turn on the automatic provision of the $<nameofthemacro> scope
control during a call to a macro with a body (e.g. #@foo #set($foo.a=$b) ...
$foo.a #end). The default is false. Set it to true if you happen to need a
namespace just for your macro's body content or more advanced #break controls.
+> Defines name of the reference that can be used to get the body content (an
AST block) given for a block macro call (e.g. #@myMacro() has a body #end). The
default reference name is "bodyContent" (e.g. $bodyContent). This block macro
feature was introduced in Velocity 1.7.
## Strict Reference Setting
-**`runtime.references.strict = false`**
+**`runtime.strict_mode.enable = false`**
-> When set to true Velocity will throw a `MethodInvocationException` for
references that are not defined in the context, or have not been defined with a
#set directive. This setting will also throw an exception if an attempt is
made to call a non-existing property on an object or if the object is null.
When this property is true then property `directive.set.null.allowed` is also
set to true. Also, `directive.foreach.skip.invalid` defaults to true when this
property is true, but explicitly setting `directive.foreach.skip.invalid` will
override this default. For a complete discussion see [Strict References
Setting](user-guide.html#strict-reference-mode).
+> When set to true Velocity will throw a `MethodInvocationException` for
references that are not defined in the context, or have not been defined with a
#set directive. This setting will also throw an exception if an attempt is made
to call a non-existing property on an object or if the object is null. When
this property is true then property `directive.foreach.skip_invalid` defaults
to true, unless this later property is explicitly set to false. For a complete
discussion see [Strict References
Setting](user-guide.html#strict-reference-mode).
-**`runtime.references.strict.escape = false`**
+**`runtime.strict_mode.escape = false`**
> Changes escape behavior such that putting a forward slash before a reference
> or macro always escapes the reference or macro and absorbs the forward slash
> regardless if the reference or macro is defined. For example "\$foo" always
> renders as "$foo", or "\#foo()" is always rendered as "#foo()". This escape
> behavior is of use in strict mode since unintended strings of characters
> that look like references or macros will throw an exception. This provides
> an easy way to escape these references. However, even in non-strict mode
> the developer may find this a more consistent and reliable method for
> escaping.
## String Interpolation
-**`runtime.interpolate.string.literals = true`**
+**`runtime.interpolate_string_literals = true`**
> Controls interpolation mechanism of VTL String Literals. Note that a VTL
> StringLiteral is specifically a string using double quotes that is used in a
> #set() statement, a method call of a reference, a parameter to a VM, or as
> an argument to a VTL directive in general. See the VTL reference for
> further information.
## Math
-**`runtime.strict.math = false`**
+**`runtime.strict_math = false`**
> Affects all math operations in VTL. If changed to true, this will cause
> Velocity to throw a MathException whenever one side of a math operation has
> a null value (e.g. `#set( $foo = $null * 5 )`) or when trying to divide by
> zero. If this value is left `false`, then rendering will continue and that
> math operation will be ignored.
@@ -245,7 +287,7 @@ The following resource management config
> This property is used by the default pooling implementation to set the
> number of parser instances that Velocity will create at startup and keep in
> a pool. The default of 20 parsers should be more than enough for most uses.
> In the event that Velocity does run out of parsers, it will indicate so in
> the log, and dynamically create overflow instances as needed. Note that
> these extra parsers will not be added to the pool, and will be discarded
> after use. This will result in very slow operation compared to the normal
> usage of pooled parsers, but this is considered an exceptional condition. A
> web application using Velocity as its view engine might exhibit this
> behavior under extremely high concurrency (such as when getting
> Slashdotted). If you see a corresponding message referencing the
> `parser.pool.size` property in your log files, please increment this
> property immediately to avoid performance degradation.
-**`parser.allows.dash.in.identifiers = false`**
+**`parser.allow_hyphen_in_identifiers = false`**
> This is a backward compatibility option, false by default, which allows the
> '**`-`**' character inside variable identifiers (available since 2.1). If
> enabled, be warned that you will have to surround the mathematical minus
> sign with spaces for it to be correctly interpreted.
@@ -253,29 +295,29 @@ The following resource management config
See the [Event Handlers](developer-guide.html#event-handlers) section of the
dev guide.
-**`eventhandler.include.class`** = *classname*
+**`event_handler.include.class`** = *classname*, *classname* ...
> register an [include event
> handler](apidocs/org/apache/velocity/app/event/IncludeEventHandler.html).
-**`eventhandler.invalidreference.class`** = *classname*
+**`event_handler.invalid_reference.class`** = *classname*, *classname* ...
> register an [invalid reference event
> handler](apidocs/org/apache/velocity/app/event/InvalidReferenceEventHandler.html).
-**`eventhandler.methodexception.class`** = *classname*
+**`event_handler.method_exception.class`** = *classname*, *classname* ...
> register a [method exception event
> handler](apidocs/org/apache/velocity/app/event/MethodExceptionEventHandler.html).
-**`eventhandler.referenceinsertion.class`** = *classname*
+**`event_handler.reference_insertion.class`** = *classname*, *classname* ...
> register a [reference insertion event
> handler](apidocs/org/apache/velocity/app/event/ReferenceInsertionEventHandler.html).
## Introspection
Introspection is the process of mapping properties, methods and iterators of
VTL references to Java objects. The object responsible of the introspection
strategy in Velocity is called an *uberspector*.
-**`runtime.introspector.uberspect =
org.apache.velocity.util.introspection.UberspectImpl`**
+**`introspector.uberspect.class =
org.apache.velocity.util.introspection.UberspectImpl`**
> This property sets the 'Uberspector', the introspection package that handles
> all introspection strategies for Velocity. You can specify a comma-separated
> list of Uberspector classes, in which case all Uberspectors are chained. The
> default chaining behaviour is to return the first non-null value for each
> introspection call among all provided uberspectors. You can modify this
> behaviour (for instance to restrict access to some methods) by subclassing
> org.apache.velocity.util.introspection.AbstractChainableUberspector (or
> implementing directly
> org.apache.velocity.util.introspection.ChainableUberspector). This allows
> you to create more interesting rules or patterns for Uberspection, rather
> than just returning the first non-null value.
>
-> Some alternate Uberspectors are provided within the Velocity package. Please
refer to the [Customizing
Introspection](developer-guide.html#customizing-introspection) section for a
detailed list. You would for instance use `runtime.introspector.uberspect =
org.apache.velocity.util.introspection.SecureUberspector` to avoid template
authors to instanciate new classes or to use reflection, or use
`runtime.introspector.uberspect =
org.apache.velocity.util.introspection.UberspectImpl,
org.apache.velocity.util.introspection.UberspectPublicFields` to expose Java
public fields in your templates.
+> Some alternate Uberspectors are provided within the Velocity package. Please
refer to the [Customizing
Introspection](developer-guide.html#customizing-introspection) section for a
detailed list. You would for instance use `introspector.uberspect.class =
org.apache.velocity.util.introspection.SecureUberspector` to avoid template
authors to instanciate new classes or to use reflection, or use
`introspector.uberspect.class =
org.apache.velocity.util.introspection.UberspectImpl,
org.apache.velocity.util.introspection.UberspectPublicFields` to expose Java
public fields in your templates.
-**`runtime.conversion.handler.class =
org.apache.velocity.util.introspection.TypeConversionHandlerImpl`**
+**`introspector.conversion_handler.class =
org.apache.velocity.util.introspection.TypeConversionHandlerImpl`**
> This configuration option is only taken into account by the default
> uberspector (UberspectImpl) and its subclasses (like SecureUberspector). It
> can be set to:
>
>- `none`: the only accepted conversions for method arguments will be the ones
>accepted by Java, typically widening number conversions. This reflects the
>behavior of Velocity 1.x.
@@ -283,23 +325,47 @@ Introspection is the process of mapping
>
> The default conversion handler will try to convert values between all
> number, boolean and string types (along with a Locale to string conversion
> since 2.1). Failed conversions will throw a MethodInvocationException (or
> call the registered MethodExceptionEventHandler, if any). Watch out for
> conversions towards boolean: non-zero numbers and the "true" String are
> true, everything else is false. This differs slighly from the
> `#if($reference)` truthness rules, where all non-null numbers and all
> non-null and non-empty strings are true.
-**`runtime.conversion.handler.instance`** = *Java Object instance*
+**`introspector.conversion_handler.instance`** = *Java Object instance*
> This configuration option is only taken into account by the default
> uberspector (UberspectImpl) and its subclasses (like SecureUberspector). It
> can be set to a living Java instance of an object implementing the interface
> [org.apache.velocity.util.introspection.TypeConversionHandler](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html)
> or the deprecated (since 2.1) interface
> [org.apache.velocity.util.introspection.ConversionHandler](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html).
## Context
-**`context.autoreference.key = <key name>`**
+**`context.self_reference_key = <key name>`**
+
+> This property has no default value. If present, the Context object will
become accessible from the templates under the provided name. For instance,
with the configuration "`context.self_reference_key = self`", then `$self` will
contain the context itself. This feature is meant to be used for debugging
purposes.
+
+**`context.scope_control.define = false`**
+
+> Used to turn on the automatic provision of the $define scope control during
#define() calls. The default is false. Set it to true if you want a local,
managed namespace you can put references in when within a #define block or if
you want it for more advanced #break usage.
+
+**`context.scope_control.evaluate = false`**
-> This property has no default value. If present, the Context object will
become accessible from the templates under the provided name. For instance,
with the configuration "`context.autoreference.key = self`", then `$self` will
contain the context itself. This feature is meant to be used for debugging
purposes.
+> Used to turn on the automatic provision of the $evaluate scope during
#evaluate() or Velocity[Engine].evaluate(...) calls. The default is false. Set
it to true if you want a local, managed namespace you can put references in
during an evaluation or if you want it for more advanced #break usage.
+
+**`context.scope_control.foreach = true`**
+
+> Used to control the automatic provision of the $foreach scope during
#foreach calls. This gives access to the foreach status information (e.g.
$foreach.index or $foreach.hasNext). The default is true. Set it to false if
unused and you want a tiny performance boost.
+
+**`context.scope_control.macro = false`**
+
+> Used to turn on the automatic provision of the $macro scope control during
#macro calls. The default is false. Set it to true if you need a local
namespace in macros or more advanced #break controls.
+
+**`context.scope_control.template = false`**
+
+> Used to turn on the automatic provision of the $template scope control
during #parse calls and template.merge(...) calls. The default is false. Set it
to true if you want a secure namespace for your template variables or more
advanced #break control.
+
+**`context.scope_control.<somebodymacro> = false`**
+
+> Used to turn on the automatic provision of the $<nameofthemacro> scope
control during a call to a macro with a body (e.g. #@foo #set($foo.a=$b) ...
$foo.a #end). The default is false. Set it to true if you happen to need a
namespace just for your macro's body content or more advanced #break controls.
## String Interning
-**`runtime.string.interning = true`**
+**`runtime.string_interning = true`**
> This property specifies whether to use Java (String
> interning)[https://en.wikipedia.org/wiki/String_interning] on identifiers.
> This may save some memory when set to true, and run a little bit faster when
> set to false.
## Space Gobbling
-**`space.gobbling = lines`**
+**`parser.space_gobbling = lines`**
> Space gobbling policy. See the [Space Gobbling
> section](developer-guide.html#space-gobbling) in the developer guide.
> Possible values are:
>- `none` : no space gobbling at all.
>- `bc` : Velocity 1.x backward compatible space gobbling.
@@ -315,20 +381,20 @@ Configuring the resource loaders for Vel
The first step in configuring one or more resource loaders is do 'declare'
them by name to Velocity. Use the property `resource.loader` and list one or
more loader names. You can use anything you want - these names are used to
associate configuration properties with a given loader.
:::properties
- resource.loader = file
+ resource.loaders = file
That entry declares that we will have a resource loader known as 'file'. The
next thing to do is to set the important properties. The most critical is to
declare the class to use as the loader:
:::properties
- file.resource.loader.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader
+ resource.loader.file.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader
In this case, we are telling velocity that we are setting up
a resource loadercalled 'file', and are using the class
`org.apache.velocity.runtime.resource.loader.FileResourceLoader` to be the
class to use. The next thing we do is set the properties important to this
loader.
:::properties
- file.resource.loader.path = /opt/templates
- file.resource.loader.cache = true
- file.resource.loader.modificationCheckInterval = 2
+ resource.loader.file.path = /opt/templates
+ resource.loader.file.cache = true
+ resource.loader.file.modification_check_interval = 2
Here, we set a few things. First, we set the path to find the templates to be
`/opt/templates`. Second, we turned caching on, so that after a template or
static file is read in, it is cached in memory. And finally, we set the
modification check interval to 2 seconds, allowing Velocity to check for new
templates.
@@ -337,24 +403,24 @@ Those are the basics. What follows are
**Do-nothing Default Configuration: ** As the name says, there is nothing you
have to do or configure to get the default configuration. This configuration
uses the FileResourceLoader with the current directory as the default resource
path, and caching is off. As a properties set, this is expressed as:
:::properties
- resource.loader = file
+ resource.loaders = file
- file.resource.loader.description = Velocity File Resource Loader
- file.resource.loader.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader
- file.resource.loader.path = .
- file.resource.loader.cache = false
- file.resource.loader.modificationCheckInterval = 0
+ resource.loader.file.description = Velocity File Resource Loader
+ resource.loader.file.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader
+ resource.loader.file.path = .
+ resource.loader.file.cache = false
+ resource.loader.file.modification_check_interval = 0
**Multiple Template Path Configuration: ** This configuration uses the
FileResourceLoader with several directories as 'nodes' on the template search
path. We also want to use caching, and have the templates checked for changes
in 10 second intervals. As a properties set, this is expressed as:
:::properties
- resource.loader = file
+ resource.loaders = file
- file.resource.loader.description = Velocity File Resource Loader
- file.resource.loader.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader
- file.resource.loader.path = /opt/directory1, /opt/directory2
- file.resource.loader.cache = true
- file.resource.loader.modificationCheckInterval = 10
+ resource.loader.file.description = Velocity File Resource Loader
+ resource.loader.file.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader
+ resource.loader.file.path = /opt/directory1, /opt/directory2
+ resource.loader.file.cache = true
+ resource.loader.file.modification_check_interval = 10
**Multiple Loader Configuration :** This configuration sets up three loaders
at the same time, the FileResourceLoader, the ClasspathResourceLoader, and the
JarResourceLoader. The loaders are set-up such that the FileResourceLoader is
consulted first, then the ClasspathResourceLoader, and finally the
JarResourceLoader. This would allow you to qickly drop a template into the file
template area to replace on of the templates found in the classpath (usually
via a jar) without having to rebuild the jar.
@@ -362,31 +428,31 @@ Those are the basics. What follows are
#
# specify three resource loaders to use
#
- resource.loader = file, class, jar
+ resource.loaders = file, class, jar
#
# for the loader we call 'file', set the FileResourceLoader as the
# class to use, turn off caching, and use 3 directories for templates
#
- file.resource.loader.description = Velocity File Resource Loader
- file.resource.loader.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader
- file.resource.loader.path = templatedirectory1, anotherdirectory, foo/bar
- file.resource.loader.cache = false
- file.resource.loader.modificationCheckInterval = 0
+ resource.loader.file.description = Velocity File Resource Loader
+ resource.loader.file.class =
org.apache.velocity.runtime.resource.loader.FileResourceLoader
+ resource.loader.file.path = templatedirectory1, anotherdirectory, foo/bar
+ resource.loader.file.cache = false
+ resource.loader.file.modification_check_interval = 0
#
# for the loader we call 'class', use the ClasspathResourceLoader
#
- class.resource.loader.description = Velocity Classpath Resource Loader
- class.resource.loader.class =
org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader
+ resource.loader.class.description = Velocity Classpath Resource Loader
+ resource.loader.class.class =
org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader
#
# and finally, for the loader we call 'jar', use the JarResourceLoader
# and specify two jars to load from
#
- jar.resource.loader.description = Velocity Jar Resource Loader
- jar.resource.loader.class =
org.apache.velocity.runtime.resource.loader.JarResourceLoader
- jar.resource.loader.path = jar:file:/myjarplace/myjar.jar,
jar:file:/myjarplace/myjar2.jar
+ resource.loader.jar.description = Velocity Jar Resource Loader
+ resource.loader.jar.class =
org.apache.velocity.runtime.resource.loader.JarResourceLoader
+ resource.loader.jar.path = jar:file:/myjarplace/myjar.jar,
jar:file:/myjarplace/myjar2.jar
Node that the three names 'file', 'class', and 'jar' are merely for your
convenience and sanity. They can be anything you want - they are just used to
associate a set of properties together. However, it is recommended that you
use names that give some hint of the function.
@@ -398,17 +464,17 @@ The following configuration maximizes th
:::properties
# No automatic conversion of methods arguments
- runtime.conversion.handler = none
+ introspector.conversion_handler.class = none
# Use backward compatible space gobbling
- space.gobbling = bc
+ engine.space_gobbling = bc
# Have #if($foo) only returns false if $foo is false or null
- directive.if.emptycheck = false
+ directive.if.empty_check = false
# Allow '-' in identifiers
- parser.allows.dash.identifiers = true
+ parser.allow_hyphen_in_identifiers = true
# When displaying null arguments literals, use provided arguments literals
- velocimacro.preserve.arguments.literals = true
+ velocimacro.arguments.preserve_literals = true
Modified: velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
URL:
http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext?rev=1855183&r1=1855182&r2=1855183&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
(original)
+++ velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext Mon Mar
11 00:22:24 2019
@@ -483,7 +483,7 @@ If we wanted to use a different director
/* first, we init the runtime engine. */
Properties p = new Properties();
- p.setProperty("file.resource.loader.path", "/opt/templates");
+ p.setProperty("resource.loader.file.path", "/opt/templates");
Velocity.init( p );
/* lets make a Context and put data into it */
@@ -503,7 +503,7 @@ And the same if you want to use a Veloci
/* first, we init the runtime engine. */
Properties p = new Properties();
- p.setProperty("file.resource.loader.path", "/opt/templates");
+ p.setProperty("resource.loader.file.path", "/opt/templates");
VelocityEngine engine = new VelocityEngine();
engine.init( p );
@@ -544,7 +544,7 @@ You can customize this logger in two way
Since version 2.0, it's possible to control the whitespace and endline
gobbling performed by Velocity during the rendering, so as to control the
indentation of the generated code. Space gobbling only happens **around**
directive and control elements (all elements starting with `#`).
-The `space.gobbling` configuration key can take the following values: `none`,
`bc` (aka backward compatible), `lines` (the default) and `structured`, each
detailed below.
+The `parser.space_gobbling` configuration key can take the following values:
`none`, `bc` (aka backward compatible), `lines` (the default) and `structured`,
each detailed below.
### No space gobbling
@@ -817,25 +817,26 @@ One of the fundamental and important par
The resource loader system if very flexible, allowing one or more resource
loaders to be in operation at the same time. This allows tremendous
flexibility in configuration and resource managment, and futher allows you to
write your own resource loaders for your special needs.
-There are currently four kinds of resource loaders that are included with
Velocity, each described below. Note that in the example configuration
properties given, a common name for the loader is shown (ex.'file' in
`file.resource.loader.path`). This 'common name' may not work for your
configuration, as resource loaders common names are defined by the
`resource.loader` configuration entry. Also, each of these loaders is located
in the package `org.apache.velocity.runtime.resource.loader`.
+There are currently four kinds of resource loaders that are included with
Velocity, each described below. Note that in the example configuration
properties given, a common name for the loader is shown (ex.'file' in
`resource.loader.file.path`). This 'common name' may not work for your
configuration, as resource loaders common names are defined by the
`resource.loader` configuration entry. Also, each of these loaders is located
in the package `org.apache.velocity.runtime.resource.loader`.
+ **FileResourceLoader :** This loader gets resources from the filesystem. Its
configuration properties include:
- + `file.resource.loader.path` = <path to root of templates> [ ,
<path to root of templates> ... ]
- + `file.resource.loader.cache` = true/false
- + `file.resource.loader.modificationCheckInterval` = <seconds between
checks>
+ + `resource.loader.file.path` = <path to root of templates> [ ,
<path to root of templates> ... ]
+ + `resource.loader.file.cache` = true/false
+ + `resource.loader.file.modification_check_interval` = <seconds between
checks>
This is the default loader (except when using VelocityTools, see below),
and is configured, by default to get templates from the 'current directory'.
In the case of using Velocity with servlets, this can be a problem as you don't
want to have to keep your templates in the directory from which you start your
servlet engine. See the documentation for your servlet or web framework (for
example [VelocityViewServlet](/tools/devel/view-servlet.html)) for more info on
how to configure the location of the Velocity templates.
-+ **JarResourceLoader :** This loader gets resource from specific jar files.
It is very similar to the FileResourceLoader, except that you have the
convenience of bundling your templates into jars. The properties are
identical, except for `jar.resource.loader.path`, where you provide the full
location of the jar(s) you wish to load resources from. To specify a jar for
the loader.path you use the standard JAR URL syntax of
`java.net.JarURLConnection`.
++ **JarResourceLoader :** This loader gets resource from specific jar files.
It is very similar to the FileResourceLoader, except that you have the
convenience of bundling your templates into jars. The properties are
identical, except for `resource.loader.jar.path`, where you provide the full
location of the jar(s) you wish to load resources from. To specify a jar for
the loader.path you use the standard JAR URL syntax of
`java.net.JarURLConnection`.
+ **ClasspathResourceLoader :** This loader gets resources from the
classloader. In general, this means that the ClasspathResourceLoader will load
templates placed in the classpath (in jars, for example) While the classpath is
a source of great pain and suffering in general, it is a very useful mechanism
when working on a Servlet Spec 2.2 (or newer) compliant servlet runner. <a
href="http://jakarta.apache.org/tomcat/"; class="externalLink">Tomcat</a> is an
example of such. To use this loader effectively, all you must do is jar your
templates, and put that jar into the WEB-INF/lib directory of your webapp.
There are no configuration options to worry about, nor is the absolute vs.
relative path an issue, as it is with Jar and File resource loaders. Again,
please note that the ClasspathResourceLoader is not only for use with a servlet
container, but can be used in any application context.
+ **URLResourceLoader :** This loader gets resources from a URL connection.
Its configuration properties include:
- + `url.resource.loader.root` = <root URL path of templates> [ ,
<root URL path of templates> ... ]
- + `url.resource.loader.cache` = true/false
- + `url.resource.loader.modificationCheckInterval` = <seconds between
checks>
+ + `resource.loader.url.root` = <root URL path of templates> [ ,
<root URL path of templates> ... ]
+ + `resource.loader.url.cache` = true/false
+ + `resource.loader.url.modification_check_interval` = <seconds between
checks>
+ + `resource.loader.url.timeout` = -1
This loader simply downloads resources from configured URLs. It works
much like the FileResourceLoader, however, it can pull templates down from any
valid URL to which the application can create a connection.
@@ -954,28 +955,30 @@ All event handler interfaces available i
>
> Available implementations include:
>
-> + `org.apache.velocity.app.event.implement.EscapeHtmlReference`
+> + `org.apache.velocity.app.event.implement.EscapeHtmlReference` (deprecated,
imractical use)
> + `org.apache.velocity.app.event.implement.EscapeJavascriptReference`
-> + `org.apache.velocity.app.event.implement.EscapeSqlReference`
-> + `org.apache.velocity.app.event.implement.EscapeXmlReference`
+> + `org.apache.velocity.app.event.implement.EscapeSqlReference` (deprecated,
imractical use)
+> + `org.apache.velocity.app.event.implement.EscapeXmlReference` (deprecated,
imractical use)
### Registering Event Handlers
You may register event handlers in either of two manners. The easiest way to
register event handlers is to specify them in velocity.properties. (Event
handlers configured in this manner are referred to as "global" event handlers).
For example, the following property will escape HTML entities in any inserted
reference.
:::properties
- eventhandler.referenceinsertion.class =
org.apache.velocity.app.event.implement.EscapeHtmlReference
+ event_handler.reference_insertion.class =
org.apache.velocity.app.event.implement.EscapeHtmlReference
Most event handler interfaces will also permit event handlers to be chained
together. Such a chain may be in a comma separated list or as additional lines
with a property/value pair. For example, the following event handler properties
install two `ReferenceInsertionEventHandler`'s. The first will apply to
references starting with "msg" (for example `$msgText`) and will escape HTML
entities (e.g. turning `&` into `&`). The second will escape all
references starting with "sql" (for example `$sqlText`) according to SQL
escaping rules. (note that in these examples, the first two properties given
relate to the event handler configuration while the second two properties are
used by the specific event handler implementation).
:::properties
- eventhandler.referenceinsertion.class =
org.apache.velocity.app.event.implement.EscapeHtmlReference
- eventhandler.referenceinsertion.class =
org.apache.velocity.app.event.implement.EscapeSqlReference
- eventhandler.escape.html.match = /msg.*/
- eventhandler.escape.sql.match = /sql.*/
+ event_handler.reference_insertion.class =
org.apache.velocity.app.event.implement.EscapeHtmlReference
+ event_handler.reference_insertion.class =
org.apache.velocity.app.event.implement.EscapeSqlReference
+ event_handler.escape.html.match = /msg.*/
+ event_handler.escape.sql.match = /sql.*/
Event handlers may also be attached to a context via an `EventCartridge`.
This allows event handlers to be tied more closely to a specific template merge
or group of merges. The event handler will automatically be injected with the
current context if it implements the `ContextAware` interface. (Due to
thread-safety reasons this is not possible with global event handlers).
+Note that most escaping reference insertion handlers were deprecated in Engine
2.1. They reveal themselves quite impractical, since they will for instance
handle in the same way references insertions in plain text or in XML/HTML
attribute values.
+
The following code shows how to register an event handler with an
EventCartridge and a context.
:::java
@@ -1402,7 +1405,7 @@ You can also provide custom [`Converter<
}
}
-You'll then need to register your uberspector with
`runtime.introspection.uberspect = mypackage.MyUberspector`. Another approach
would be to inherit from
`org.apache.util.introspection.TypeConversionHandlerImpl`, add converters
within its constructor and register your conversion handler using the
`runtime.conversion.handler.class` configuration property, or to directly
provide Velocity with a living instance of a
`org.apache.util.introspection.TypeConversionHandler` using the
`runtime.conversion.handler.instance` configuration property.
+You'll then need to register your uberspector with
`introspector.uberspect.class = mypackage.MyUberspector`. Another approach
would be to inherit from
`org.apache.util.introspection.TypeConversionHandlerImpl`, add converters
within its constructor and register your conversion handler using the
`introspector.conversion_handler.class` configuration property, or to directly
provide Velocity with a living instance of a
`org.apache.util.introspection.TypeConversionHandler` using the
`runtime.conversion.handler.instance` configuration property.
*Velocity Engine 2.0 backward compatibility note*: the
[`org.apache.util.introspection.ConversionHandler`](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html)
interface has been deprecated in favor of the
[`org.apache.util.introspection.TypeConversionHandler`](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html)
interface. The new interface let one specify converters towards a
`java.lang.reflect.Type` rather than a `java.lang.class`.
Modified: velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext
URL:
http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext?rev=1855183&r1=1855182&r2=1855183&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext Mon Mar 11
00:22:24 2019
@@ -8,7 +8,47 @@ Title: Apache Velocity Engine - Upgradin
Release with the same major number (1.x, 2.x) are intended to be drop-in
replacements. However, in most cases the versions of dependency jars must be
adjusted because newer versions of Velocity might require updates.
-## Upgrading from Velocity 1.7.x to Velocity 2.x
+## Upgrading from Velocity 2.0 to Velocity 2.1
+
+For busy people: To maximize backward compatibility of Velocity 2.1 with
Velocity 1.x, be sure to include the following lines in your Velocity
configuration:
+
+ :::properties
+ # No automatic conversion of methods arguments
+ introspector.conversion_handler.class = none
+
+ # Use backward compatible space gobbling
+ parser.space_gobbling = bc
+
+ # Have #if($foo) only returns false if $foo is false or null
+ directive.if.empty_check = false
+
+ # Allow '-' in identifiers
+ parser.allow_hyphen_in_identifiers = true
+
+ # When displaying null arguments literals, use provided arguments literals
+ velocimacro.arguments.preserve_literals = true
+
+Also, please note that Velocity 2.1 now requires Java JDK 1.8 for bulding and
Java JRE 1.8 at runtime.
+
+### Behavior / API Changes
+
++ inside a macro, since 2.0, the rendering of null arguments uses the local
reference literal. To revert to the 1.7 behavior, you can set the boolean
property `velocimacro.preserve.arguments.literals` to true. The macros will
then use the provided argument literals in such cases.
++ the
[`org.apache.util.introspection.ConversionHandler`](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html)
interface (introduced in 2.0) has been deprecated in favor of the
[`org.apache.util.introspection.TypeConversionHandler`](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html)
interface. The new interface let one specify converters towards a
`java.lang.reflect.Type` rather than a `java.lang.class`.
++ most names of Velocity configuration properties have changed ; old names are
still functional but will emit a deprecation warning in the log. See the
[Configuration Changes in Velocity
2.1](configuration-property-changes-in-2.1.html) page.
+
+### VTL Changes
+
++ since 2.0 the hypen ( `-` ) cannot be used in variable names anymore, but in
2.1, this behavior can be restored for backward compatibility with 1.7 by
setting the new `parser.allow_hyphen_in_identifiers` boolean property to true
++ it's now possible to provide default values for references, using the syntax
`${name|'John Doe'}`. The right part can be any valid VTL expression.
++ the `#foreach()` directive accepts an `#else` block which is evaluated when
the loop is empty: `#foreach(...) ... #else ... #end`.
+
+### Dependency Changes
+
++ Velocity 2.1 now requires JDK 1.8+ for building and JRE 1.8+ at runtime.
++ commons-lang3 has been upgraded to 3.8.1.
++ slf4j-api has been upgraded to 1.7.26.
+
+## Upgrading from Velocity 1.7 to Velocity 2.0
<div class="note">
Please note that the maven repository path has changed:
@@ -18,29 +58,23 @@ Please note that the maven repository pa
</ul>
</div>
-For busy people: To maximize backward compatibility with Velocity 1.x, be sure
to include the following lines in your Velocity configuration:
+For busy people: To maximize backward compatibility of Velocity 2.0 with
Velocity 1.x, be sure to include the following lines in your Velocity
configuration:
:::properties
# No automatic conversion of methods arguments
- runtime.conversion.handler = none
+ runtime.conversion.handler.class = none
# Use backward compatible space gobbling
space.gobbling = bc
# Have #if($foo) only returns false if $foo is false or null
directive.if.emptycheck = false
-
- # Allow '-' in identifiers
- parser.allows.dash.identifiers = true
-
- # When displaying null arguments literals, use provided arguments literals
- velocimacro.preserve.arguments.literals = true
and check the [Dependency changes](#dependencies-changes) below.
Read below for futher details.
-### Behavior / API changes:
+### Behavior / API Changes
+ velocity is now using the SLF4J logging facade. Hence, all methods accepting
or returning a logger now use the org.slf4j.Logger object. Velocity uses a
logger name of `org.apache.velocity` (configurable with the `runtime.log.name`
configuration entry), and [several other childen
loggers](developer-guide.html#logging).
+ the internal Context API now enforces String keys everywhere, this may break
custom Context implementations at compile-time.
@@ -55,21 +89,18 @@ Read below for futher details.
+ Initialization methods in Velocity and VelocityEngine taking an
ExtendedProperties have been removed (but `setProperties(Properties)` methods
are still here). All occurences of the
org.apache.commons.collections.ExtendedProperties class in the runtime internal
initialization API have been replaced by org.apache.velocity.util.ExtProperties.
+ the macros are now using a 'call by sharing' convention (which means that
all arguments are evaluated once at start, and that the macro receives a copy
of the reference to each argument).
+ the `UberspectLoggable` interface has been removed.
-+ the `directive.if.tostring.nullcheck` configuration property has been
superseded by the `directive.if.emptycheck` property, which defaults to true.
It means that all empty objects (strings and collections) as long as zero
numbers, do evaluate to false (see the complete [boolean context
evaluation](configuration.html#if-directive) rules.). You may want to set
`directive.if.emptycheck` to false to maximize backward compatibility with 1.x.
-+ inside a macro, the rendering of null arguments uses the local reference
literal - to revert to the 1.7 behavior, you can set the boolean property
`velocimacro.preserve.arguments.literals` to true (since 2.1). The macros will
then use the provided argument literals in such cases.
-+ since 2.1, the
[`org.apache.util.introspection.ConversionHandler`](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html)
interface has been deprecated in favor of the
[`org.apache.util.introspection.TypeConversionHandler`](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html)
interface. The new interface let one specify converters towards a
`java.lang.reflect.Type` rather than a `java.lang.class`.
++ the `directive.if.tostring.nullcheck` configuration property has been
superseded by the `directive.if.emptycheck` (warning: renamed as
`directive.if.empty_check` in 2.1) property, which defaults to true. It means
that all empty objects (strings and collections) as long as zero numbers, do
evaluate to false (see the complete [boolean context
evaluation](configuration.html#if-directive) rules.). You may want to set
`directive.if.emptycheck` to false to maximize backward compatibility with 1.x.
++ inside a macro, the rendering of null arguments uses the local reference
literal (see 2.1 for an 1.7 compatibility flag).
-### VTL Changes:
+### VTL Changes
-+ the hypen ( `-` ) cannot be used in variable names anymore, but this
behavior can be restored for backward compatibility (since 2.1) by setting the
new `parser.allows.dash.in.identifiers` boolean property to true
++ the hypen ( `-` ) cannot be used in variable names anymore (see 2.1 for an
1.7 compatibility flag).
+ method arguments can be arithmetic expressions
-+ method arguments are now converted as needed between all main basic Java
standard types (booleans, numbers and strings). If you want to revert to the
1.x behavior, set the property `runtime.conversion.handler = none`.
++ method arguments are now converted as needed between all main basic Java
standard types (booleans, numbers and strings). If you want to revert to the
1.x behavior, set the property `runtime.conversion.handler.class = none`.
+ space gobbling (to control the indentation of generated code) is now
configurable via the `space.gobbing` configuration key, which can take the
following values: `none`, `bc` (aka. backward compatible), `lines` and
`structured`. See the related documentation section for details. To maximize
backward compatibility with 1.x, set it to `bc`.
+ the #foreach predefined references `$velocityCount` and `$velocityHasNext`
have been removed. Use `$foreach.count` (1-based), `$foreach.index` (0-based)
and `foreach.hasNext()`.
-+ since 2.1, it's now possible to provide default values for references, using
the syntax `${name|'John Doe'}`. The right part can be any valid VTL expression.
-+ since 2.1, the `#foreach()` directive accepts an `#else` block which is
evaluated when the loop is empty: `#foreach(...) ... #else ... #end`.
-### Dependency changes:
+### Dependency Changes
+ Velocity now requires a JDK version of 1.7 or higher.
+ commons-collections and commons-logging aren't needed any more at runtime.
Modified: velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext
URL:
http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext?rev=1855183&r1=1855182&r2=1855183&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext Mon Mar 11
00:22:24 2019
@@ -149,7 +149,6 @@ Here are some examples of valid variable
:::velocity
$foo
$mudSlinger
- $mud-slinger
$mud_slinger
$mudSlinger1
@@ -319,9 +318,9 @@ Formal and quiet reference notation can
:::html+velocity
<input type="text" name="email" value="$!{email}"/>
-## Strict Reference Mode
+## Strict Rendering Mode
-Velocity 1.6 introduces the concept of strict reference mode which is
activated by setting the velocity configuration property
'runtime.references.strict' to true. The general intent of this setting is to
make Velocity behave more strictly in cases that are undefined or ambiguous,
similar to a programming language, which may be more appropriate for some uses
of Velocity. In such undefined or ambiguous cases Velocity will throw an
exception. The following discussion outlines the cases in which strict
behavior is different from traditional behavior.
+The strict rendering mode is activated by setting the velocity configuration
property 'runtime.strict_mode.enable' to true. The general intent of this
setting is to make Velocity behave more strictly in cases that are undefined or
ambiguous, similar to a programming language, which may be more appropriate for
some uses of Velocity. In such undefined or ambiguous cases Velocity will throw
an exception. The following discussion outlines the cases in which strict
behavior is different from traditional behavior.
With this setting references are required to be either placed explicitly into
the context or defined with a #set directive or Velocity will throw an
exception. References that are in the context with a value of null will not
produce an exception. Additionally, if an attempt is made to call a method or a
property on an object within a reference that does not define the specified
method or property then Velocity will throw an exception. This is also true if
there is an attempt to call a method or property on a null value.
@@ -340,7 +339,7 @@ Also, The following statements show exam
$bar.foo.bogus ## $bar.foo does not provide property bogus, Exception
$bar.retnull.bogus ## cannot call a property on null, Exception</pre>
-In general strict reference behavior is true for all situations in which
references are used except for a special case within the #if directive. If a
reference is used within a #if or #elseif directive without any methods or
properties, and if it is not being compared to another value, then undefined
references are allowed. This behavior provides an easy way to test if a
reference is defined before using it in a template. In the following example
where $foo is not defined the statements will not throw an exception.
+In general strict rendering mode behavior is true for all situations in which
references are used except for a special case within the #if directive. If a
reference is used within a #if or #elseif directive without any methods or
properties, and if it is not being compared to another value, then undefined
references are allowed. This behavior provides an easy way to test if a
reference is defined before using it in a template. In the following example
where $foo is not defined the statements will not throw an exception.
:::velocity
#if ($foo)#end ## False
@@ -349,7 +348,7 @@ In general strict reference behavior is
#if ($foo && $foo == "bar")#end ## False and $foo == "bar" wil not be
evaluated
#if ($foo1 || $foo2)#end ## False $foo1 and $foo2 are not defined
-Strict mode requires that comparisons of >, <, >= or <= within an #if
directive makes sense. Also, the argument to #foreach must be iterable (this
behavior can be modified with the property directive.foreach.skip.invalid).
Finally, undefined macro references will also throw an exception in strict mode.
+Strict rendering mode requires that comparisons of >, <, >= or <= within an
#if directive makes sense. Also, the argument to #foreach must be iterable
(this behavior can be modified with the property
directive.foreach.skip_invalid). Finally, undefined macro references will also
throw an exception in strict mode.
References that Velocity attempts to render but evaluate to null will cause an
Exception. To simply render nothing in this case the reference can be preceded
by '$!' instead of '$', similar to non strict mode. Keep in mind this is
different from the reference not existing in the context which will always
throw an exception when attempting to render it in strict mode. For example,
below $foo has a value of null in the context
@@ -642,7 +641,7 @@ It's possible to set a maximum allowed n
:::properties
# The maximum allowed number of loops.
- directive.foreach.maxloops = -1
+ directive.foreach.max_loops = -1
If you want to stop looping in a foreach from within your template, you can
now use the #break directive to stop looping at any time:
@@ -680,7 +679,7 @@ The *#parse* script element allows the t
Like the *#include* directive, *#parse* can take a variable rather than a
template. Any templates to which *#parse* refers must be included under
TEMPLATE_ROOT. Unlike the *#include* directive, *#parse* will only take a
single argument.
-VTL templates can have *#parse* statements referring to templates that in turn
have *#parse* statements. By default set to 10, the *directive.parse.max.depth*
line of the `velocity.properties` allows users to customize maximum number of
*#parse* referrals that can occur from a single template. (Note: If the
*directive.parse.max.depth* property is absent from the `velocity.properties`
file, Velocity will set this default to 10.) Recursion is permitted, for
example, if the template `dofoo.vm` contains the following lines:
+VTL templates can have *#parse* statements referring to templates that in turn
have *#parse* statements. By default set to 10, the *directive.parse.max_depth*
line of the `velocity.properties` allows users to customize maximum number of
*#parse* referrals that can occur from a single template. (Note: If the
*directive.parse.max_depth* property is absent from the `velocity.properties`
file, Velocity will set this default to 10.) Recursion is permitted, for
example, if the template `dofoo.vm` contains the following lines:
:::velocity
Count down.
@@ -853,17 +852,17 @@ If you need to circumvent this feature,
Several lines in the `velocity.properties` file allow for flexible
implementation of Velocimacros. Note that these are also documented in the <a
href="developer-guide.html">Developer Guide</a>.
-`velocimacro.library` - A comma-separated list of all Velocimacro template
libraries. By default, Velocity looks for a single library:
*VM_global_library.vm*. The configured template path is used to find the
Velocimacro libraries.
+`velocimacro.library.path` - A comma-separated list of all Velocimacro
template libraries. By default, Velocity looks for a single library:
*velocimacros.vtl* (since 2.1 ; and if not found it will also look at the old
default *VM_global_library.vm*). The configured template path is used to find
the Velocimacro libraries.
-`velocimacro.permissions.allow.inline` - This property, which has possible
values of true or false, determines whether Velocimacros can be defined in
regular templates. The default, true, allows template designers to define
Velocimacros in the templates themselves.
+`velocimacro.inline.allow` - This property, which has possible values of true
or false, determines whether Velocimacros can be defined in regular templates.
The default, true, allows template designers to define Velocimacros in the
templates themselves.
-`velocimacro.permissions.allow.inline.to.replace.global` - With possible
values of true or false, this property allows the user to specify if a
Velocimacro defined inline in a template can replace a globally defined
template, one that was loaded on startup via the `velocimacro.library`
property. The default, `false`, prevents Velocimacros defined inline in a
template from replacing those defined in the template libraries loaded at
startup.
+`velocimacro.inline.replace_global` - With possible values of true or false,
this property allows the user to specify if a Velocimacro defined inline in a
template can replace a globally defined template, one that was loaded on
startup via the `velocimacro.library.path` property. The default, `false`,
prevents Velocimacros defined inline in a template from replacing those defined
in the template libraries loaded at startup.
-`velocimacro.permissions.allow.inline.local.scope` - This property, with
possible values of true or false, defaulting to false, controls if Velocimacros
defined inline are 'visible' only to the defining template. In other words,
with this property set to true, a template can define inline VMs that are
usable only by the defining template. You can use this for fancy VM tricks -
if a global VM calls another global VM, with inline scope, a template can
define a private implementation of the second VM that will be called by the
first VM when invoked by that template. All other templates are unaffected.
+`velocimacro.inline.local_scope` - This property, with possible values of true
or false, defaulting to false, controls if Velocimacros defined inline are
'visible' only to the defining template. In other words, with this property
set to true, a template can define inline VMs that are usable only by the
defining template. You can use this for fancy VM tricks - if a global VM calls
another global VM, with inline scope, a template can define a private
implementation of the second VM that will be called by the first VM when
invoked by that template. All other templates are unaffected.
-`velocimacro.library.autoreload` - This property controls Velocimacro library
autoloading. The default value is `false`. When set to `true` the source
Velocimacro library for an invoked Velocimacro will be checked for changes, and
reloaded if necessary. This allows you to change and test Velocimacro
libraries without having to restart your application or servlet container, just
like you can with regular templates. This mode only works when caching is
<i>off</i> in the resource loaders (e.g. `file.resource.loader.cache = false`
). This feature is intended for development, not for production.
+`velocimacro.library.autoreload` - This property controls Velocimacro library
autoloading. The default value is `false`. When set to `true` the source
Velocimacro library for an invoked Velocimacro will be checked for changes, and
reloaded if necessary. This allows you to change and test Velocimacro
libraries without having to restart your application or servlet container, just
like you can with regular templates. This mode only works when caching is
<i>off</i> in the resource loaders (e.g. `resource.loader.file.cache = false`
). This feature is intended for development, not for production.
-Please note than when two templates each define a macro with the same name,
you either need `velocimacro.permissions.allow.inline.local.scope` or
`velocimacro.permissions.allow.inline.to.replace.global` to be set to true for
each template to use its own macro version.
+Please note than when two templates each define a macro with the same name,
you either need `velocimacro.inline.local_scope` or
`velocimacro.inline.replace_global` to be set to true for each template to use
its own macro version.
## Getting Literal
@@ -1228,14 +1227,14 @@ There is a property, meant to be used in
which defaults to false. When set to true *along with*
- `<type>.resource.loader.cache = false`
+ `resource.loader.<type>.cache = false`
(where <type> is the name of the resource loader that you are using, such as
'file') then the Velocity engine will automatically reload changes to your
Velocimacro library files when you make them, so you do not have to dump the
servlet engine (or application) or do other tricks to have your Velocimacros
reloaded.
Here is what a simple set of configuration properties would look like.
- file.resource.loader.path = templates
- file.resource.loader.cache = false
+ resource.loader.file.path = templates
+ resource.loader.file.cache = false
velocimacro.library.autoreload = true
Don't keep this on in production.
Modified: velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext
URL:
http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext?rev=1855183&r1=1855182&r2=1855183&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext Mon Mar
11 00:22:24 2019
@@ -120,7 +120,7 @@ Usage:
+ *condition* - Expression to evaluate. When its result is null, evaluate to
false. Otherwise, check for conversion towards Boolean and non-emptiness as
follow:
- return its value for a Boolean object, or the result of the
getAsBoolean() method if it exists.
- - if `directive.if.emptycheck` = `false` (`true` by default), stop here
and consider it true.
+ - if `directive.if.empty_check` = `false` (`true` by default), stop here
and consider it true.
- return whether an array is empty.
- return whether isEmpty() is false (covers String and all Collection
classes).
- return whether length() is zero (covers CharSequence classes other than
String).
@@ -186,7 +186,7 @@ The maximum allowed number of loop itera
:::properties
# The maximum allowed number of loops.
- directive.foreach.maxloops = -1
+ directive.foreach.max_loops = -1
### #include - Renders local file(s) that are not parsed by Velocity
@@ -218,7 +218,7 @@ Examples:
+ String: `#parse( "lecorbusier.vm" )`
+ Variable: `#parse( $foo )`
-Recursion permitted. See *parse_directive.maxdepth* in `velocity.properties`
to change from parse depth. (The default parse depth is 10.)
+Recursion permitted. See *directive.parse.max_depth* in `velocity.properties`
to change from parse depth. (The default parse depth is 10.)
### #stop - Stops the template engine
