You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by cb...@apache.org on 2019/09/08 14:41:42 UTC
svn commit: r1866614 - in /velocity/site/cms/trunk/content/engine/devel:
configuration.mdtext developer-guide.mdtext upgrading.mdtext
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