Velocity Reference

APPENDIX Velocity Reference VELOCITY HAS A WIDE RANGE of configuration settings, directives, and resource loaders. This appendix is a reference for aU aspects of Velocity configuration and usage. Introducing the Directives The following sections show the syntax for the standard directives included in the Velocity distribution. #set The #set directive assigns variables' values. These values can be a simple literal value or another variable. Syntax #set($variable=<literal value> I <variable_name» Example #set($myVar = "Hello World") Output The #set directive has no output. 347 Appendix #if/#else/#end The #if/#else/#end directives support conditional processing within your tem plates. The use of these directives is synonymous with the use of the if/else construct in Java. Syntax #if«boolean expression> I <boolean literal> I <boolean variable reference» Output for true #else Output for false #end Example #set($someVar = true) #if($someVar) Hello World! #else Goodbye Cruel World! #end Output Hello World! #foreach The #foreach directive iterates over all elements in a collection or an array and performs some processing for each element. Syntax #foreach($var in $collectionOrArray) ## do something with $var #end 348 Velocity Reference Example #foreach($num in [0 •• 5]) $num #end Output o 1 2 3 4 5 #include The #include directive includes some content from another resource in the out put stream. The content is added as-is with no processing by the Velocity engine. Syntax #import«resource_name» Example For example, the main template, template. vm, could contain the followingVfL code: Hello #include("world.txt") And an external file resource, world. txt, could contain the following static text: World Output Hello World 349 Appendix #parse The #parse directive functions in a similar manner to the #include directive; however, the external resource is first parsed by the Velocity engine, and any VTL constructs are processed as if they were part of the main template. Syntax #parse«resource_name» Example For example, the main template, template. vm, could contain the following VTL code: #set ($who = "World") Hello #parse("world.vm") And an external template, world.vm, could contain the additionalVTL code: $who Output Hello World Configuring Velocity Velocity has a selection of configuration parameters that can control various aspects of the runtime. The following sections provide a quick reference to these configuration parameters. General Configuration Options Table A-1 shows the general configuration options. 350 Velocity Reference TableA-l. General Configuration Options Parameter Name Description Default Value runtime. log Specifies the name of the log file cre velocity. log ated by the Velocity log system. File names that aren't absolute are resolved relative to the current directory of your application. runtime. log. logsystem.class Specifies the class name of the org.apache. LogSystem implementation. Use this velocity. runtime. if you want to use a specific LogSystem log. AvalonLogSystem implementation. runtime. log. error. stacktrace Specifies whether Velocity should out false put a stack trace for error-level log messages. runtime. log. warn. stacktrace Specifies whether Velocity should out false put a stack trace for warn-level log messages. runtime. log. info. stacktrace Specifies whether Velocity should out false put a stack trace for info-level log messages. runtime. log. invalid. Specifies whether a log message true references should be written when an invalid reference is encountered. input. encoding Specifies the encoding to use when ISO-8859-1 reading resource files. output. encoding Specifies the encoding to use when ISO-8859-1 creating output. parser.pool.size Specifies the size of the parser pool. 20 runtime. interpolate. string. Specifies whether string literals should true literals be interpolated by the runtime. runtime.introspector. Specifies the Uberspect implementa org.apache. uberspect tion class to use. If you choose to velocity. uti!. create your own Uberspector, then you introspection. can replace the default value of this UberspectImpl configuration parameter. 351 Appendix Directive Configuration Table A-2 shows the directive configuration options. TableA-2. Directive Configuration Options Parameter Name Description Default Value directive.foreach.counter. Specifies the name of the counter velocityCount name variable used by the #foreach directive. directive.foreach.counter. Set sthe initial value of the counter 1 initial. value variable used by the #foreach directive. directive.include.output. Specifies the token to output before an <1-- include error errormsg. start error message when writing error mes sages to the output stream. The end token must also be specified for this to take effect. directive.include.output. Specifies the token to output after an see error log --> errormsg.end error message. directive.parse.maxdepth Specifies the maximum parse depth 10 when using the #parse directive. This is relevant only if you use embed tem plates using #parse that have #parse statements themselves. ResourceManager Configuration Table A-3 shows the ResourceManager configuration options. Table A-3. ResourceManager Configuration Options Parameter Name Description Default Value resource.manager.logwhenfound Specifies whether a log message should true be written when a resource is located by the resource manager. resource. loader A comma-separated list of loader file names. These names correspond to sep arate loader configurations for each name specified. resource. manager. cache. class Specifies the class implementing the re org.apache. source manager cache. You can provide velocity. runtime. your own caching implementation using resource. this parameter. ResourceCachelmpl 352 Velocity Reference ResourceLoader Configuration An important part of configuring your Velocity system is configuring the resource loaders used by your application. The following sections are a quick reference to the configuration parameters for the different resource loaders. For all the configuration parameters, you should replace the <name> variable with the name of the resource loader you want to configure. Common Configuration Some of the parameters are considered common to all resource loaders; Table A-4 shows these. Table A-4. Common ResourceLoader Configuration Options Parameter Name Description Default Value <name>.resource.loader.class The name of the class that implements org.apache.velocity. the resource loader. runtime. resource. loader. FileResourceLoader <name>. resource. loader. cache Specifies whether caching is enabled false for the resource loader. <name>.resource.loader. Specifies the duration in seconds to wait 2 modificationChecklnterval before checking to see if a cached resource has been modified. Set this to o to prevent checks. FileResourceLoader Table A-5 shows the FileResourceLoader-specific configuration options. TableA-5. FileResourceLoader-Specijic Configuration Options Parameter Name Description Default Value <name>.resource.loader.path The path to search for. This should be a . / directory or list of directories separated by commas. The template name should match a file within one of the specified directories. 353 Appendix JarResourceLoader Table A-6 shows the JarResourceLoader-specific configuration options. Table A-6. JarResourceLoader-Specijic Configuration Options Parameter Name Description Default Value <name>.resource. loader. path The path to the JAR file (or JAR files) that the runtime loader should search for resources in. ClasspathResourceLoader The ClasspathResourceLoader has no configuration parameters other than the standard ones. DataSourceResourceLoader Table A-7 shows the DataSourceResourceLoader-specific configuration options. TableA-7. DataSourceResourceLoader-Specific Configuration Options Parameter Name Description <name>. resource .loader. resource. datasource The JNDI name of the DataSource to use to retrieve the resources. <name>. resource. loader. resource. table The name of the table in which the resources are stored. <name>.resource.loader.resource.keycolumn The name of the column that stores the resource name. <name>.resource.loader.resource. The name of the column that stores the actual templatecolumn resource content. <name>.resource.loader.resource. The name of the column that has the time timestamp column stamp for the resource. This is required for caching support to function correctly. 354 Velocity Reference Velocimacro Configuration Table A-8 shows the Velocimacro configuration parameters. Table A -8. Velocimacro Configuration Parameters Parameter Name Description Default Value velocimacro.library Specifies the name of one or more files con - VM _global_ taining global macro definitions. If you library. vm want to use more than one global library file, then split the filenames with a comma. velocimacro.permissions. Specifies whether macros can be defined true allow. inline in line in a template as opposed to in the global library. velocimacro.permissions.allow. Specifies whether an inline macro can re false inline.to.replace.global place a globally defined macro with the same name. velocimacro.permissions.allow. This parameter specifies whether inline false inline.local.scope macros should be scoped to the local template only. See Chapter 3 for more details on this parameter. velocimacro. context . locals cope Specifies whether a reference access from false within a macro can change the context. velocimacro . library . autoreload Specifies whether Velocity

Load more