velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cbris...@apache.org
Subject svn commit: r1866614 - in /velocity/site/cms/trunk/content/engine/devel: configuration.mdtext developer-guide.mdtext upgrading.mdtext
Date Sun, 08 Sep 2019 14:41:42 GMT
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
 



Mime
View raw message