Author: cbrisson
Date: Sun Sep 8 14:41:42 2019
New Revision: 1866614
URL: http://svn.apache.org/viewvc?rev=1866614&view=rev
Log:
[site/engine] Document latest changes in devel
Modified:
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
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=1866614&r1=1866613&r2=1866614&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/configuration.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/configuration.mdtext Sun Sep
8 14:41:42 2019
@@ -37,6 +37,7 @@ The following tree gathers all non depre
event_handler. +-- include.class = *classname*, *classname* ...
+-- invalid_reference. +-- class = *classname*, *classname*
...
+ +-- exception = false
+-- null = false
+-- quiet = false
+-- tested = false
@@ -106,7 +107,18 @@ The following tree gathers all non depre
**`runtime.log.track_location = false`**
-> (Since 2.2). When set to true, Velocity will populate [slf4j
MDC](https://logback.qos.ch/manual/mdc.html) with the `file`, `line` and
`context` tags during the template rendering process. When using an MDC-aware
slf4j backend, you can display template locations in logs. Be aware that it can
have a small performance impact.
+> (Since 2.2) When this debugging flag is set to true, Velocity will:
+
+1. populate [slf4j MDC](https://logback.qos.ch/manual/mdc.html) with the
`file`, `line` and `context` tags during the template rendering process. When
using an MDC-aware slf4j backend, you can display template locations in logs.
+2. print the VTL rendering stack trace in the logs when errors are encountered
during rendering.
+
+As a side effect, any Java object with an access to a RuntimeServices object
will be able to get the current VTL stack trace using:
+
+ :::java
+ /* rsvc contains an instance of
org.apache.velocity.runtime.RuntimeServices */
+ String[] vtlStackTrace = rsvc.getLogContext().getStackTrace();
+
+Be aware that it can have a (probably very) small performance impact.
## VTL Directives
@@ -309,14 +321,17 @@ See the [Event Handlers](developer-guide
**`event_handler.invalid_reference.class`** = *classname*, *classname* ...
> register an [invalid reference event
> handler](apidocs/org/apache/velocity/app/event/InvalidReferenceEventHandler.html).
+**`event_handler.invalid_reference.exception`** = `false`
+> Make the registered
org.apache.velocity.app.event.implement.ReportInvalidReferences event handler
throw an exception at the first encountered invalid reference.
+
**`event_handler.invalid_reference.null`** = `false`
-> make registered event handlers receive events whenever the reference value
is present in the context but has a null value, or if a method call returned
null.
+> (Since 2.2) Make registered invalid reference event handlers receive events
whenever the reference value is present in the context but has a null value, or
if a method call returned null.
**`event_handler.invalid_reference.quiet`** = `false`
-> make registered event handlers receive events whenever the invalid reference
is a quiet reference.
+> (Since 2.2) Make registered invalid reference event handlers receive events
whenever the invalid reference is a quiet reference.
**`event_handler.invalid_reference.tested`** = `false`
-> make registered event handlers receive events whenever the invalid reference
is just tested for validity in an `#if()` statement.
+> (Since 2.2) Make registered invalid reference event handlers receive events
whenever the invalid reference is just tested for validity in an `#if()`
statement.
**`event_handler.method_exception.class`** = *classname*, *classname* ...
> register a [method exception event
> handler](apidocs/org/apache/velocity/app/event/MethodExceptionEventHandler.html).
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=1866614&r1=1866613&r2=1866614&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
(original)
+++ velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext Sun Sep
8 14:41:42 2019
@@ -1429,11 +1429,11 @@ The value for the *encoding* argument is
Note that this applies only to the encoding of the template itself - the
output encoding is an application specific issue.
-## Velocity and XML
+## Velocity and structured data
-Velocity's flexibility and simple template language makes it an ideal
environment for working with XML data.
+Velocity's flexibility and simple template language makes it an ideal
environment for working with structured data, as XML, JSON, etc.
-Generally, the pattern for dealing with XML in Velocity is to use something
like [JDOM](http://www.jdom.org/) to process your XML into a data structure
with convenient Java access. Then, you produce templates that access data
directly out of the XML document - directly though the JDOM tree. For example,
start with an XML document such as:
+Generally, the pattern for dealing with such structured data in Velocity is
-for instance with XML data- to use something like [JDOM](http://www.jdom.org/)
to process your XML into a data structure with convenient Java access. Then,
you produce templates that access data directly out of the XML document -
directly though the JDOM tree. For example, start with an XML document such as:
::xml
<document>
@@ -1517,6 +1517,8 @@ Alternatively, since Velocity makes it e
#set( $sometext = $jdomElement.getText() )
<text>$sometext</text>
+Last but not least, you can make use of a custom
ReferenceInsertionEventHandler to escape references at the time they are
rendered. If you can easily control when to escape and when not to escape from
within this handler, or if you're certain that you want to escape everything,
it's one of the easiest way.
+
The previous suggestions for dealing with XML entities came from Christoph
Reck, an active participant in the Velocity community.
## Velocity Scripting
@@ -1539,7 +1541,24 @@ Hello World example:
engine.getContext().setWriter(writer);
Object result = engine.eval(script);
System.out.println(writer);
-
+
+## Customizing the VTL parser
+
+Since 2.2, a Velocity Engine can use a custom parser. You need to generate
your custom parser class, let's say `com.foo.MyCustomParser`, by copy pasting
the content of the
[velocity-custom-parser-example](https://repository.apache.org/content/repositories/snapshots/org/apache/velocity/velocity-custom-parser-example/2.2-SNAPSHOT/velocity-custom-parser-example-2.2-20190908.141659-1.pom)
maven module pom file inside one of your own modules pom.xml, and then
adapting its `<properties>` section. There's a minimal maven knowledge required
to understand what you are doing, but basically it boils down to do merge the
content of the `<properties>`, `<dependencies>` and `<build>` sections in your
target pom file.
+
+This custom parser will let you configure the following VTL characters:
+
++ `*` (used in `#*` multiline comments syntax)
++ `@` (used in `#@blockmacro` syntax)
++ `$` (used in `$reference` syntax)
++ `#` (used in `#*` and `##` comments, `#directive` and `#macro` syntaxes)
+
+Then, in the target project, you have to specify which parser to use from
within the `velocity.properties` file:
+
+ :::properties
+ parser.class = com.foo.MyCustomParser
+
+For instance, you may want to replace `#` with `%` because the target language
(markdown for instance) already makes use of the `#` symbol.
## Summary
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=1866614&r1=1866613&r2=1866614&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext Sun Sep 8
14:41:42 2019
@@ -41,15 +41,18 @@ Also, please note that since version 2.1
### Behavior / API Changes
-+ The references with alternate values like `${foo|'foo'}` won't trigger any
invalid reference event if their alternate value os valid.
++ The references with alternate values like `${foo|'foo'}` won't trigger any
invalid reference event if their alternate value is valid.
++ New [`runtime.log.track_location`](configuration.html#logging) debugging
configuration flag (defaults to false). When true, logs VTL stacktrace on
errors and populate slf4j template location MDC tags.
++ New 1.7.x backward compatibility configuration flags for event handlers, see
above section.
### VTL Changes
-(none)
++ The new velocity-custom-parser-example maven module demonstrates [how to
buid a custom VTL parser](developer-guide.html#customizing-the-vtl-parser)
which uses alternatives to the following four VTL syntax characters: `$`, `#`,
`@` and `*`.
### Dependency Changes
-TODO
++ commons-lang3 has been upgraded to 3.9.
++ slf4j-api has been upgraded to 1.7.2.
## Upgrading from Velocity 2.0 to Velocity 2.1
