Velocity's Chinese Guide (4)-Finishing

1. Macro <?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office"/>

#macro script element allows the template designer to define duplicate segments in the VTL template. Velocimacros is very useful in both complex and simple situations. The following velocimacro, which is used to save keystrokes and reduce typographical errors, introduces the concepts of velocity macros.

#macro (d) <tr><td></td></tr> #end

In the example, Velocimacro is defined as D, which can be invoked in the same form as other VTL directives:

#d ()

When the template is called, Velocity replaces the #d () with a single blank table.

Velocimacro can take some parameters, or without parameters (as shown in the previous example). But when he is called, the parameter must be the same as the parameter it defines. Many velocimacros are defined as more than one parameter. The following macro has two parameters, a color, and an array.

#macro (tablerows $color $somelist) #foreach ($something in $somelist) <TR><TD bgcolor= $color > $something </td></tr> #end #end

The Velocimacro defined in this example, named TableRows, requires two parameters. The first parameter replaces $color, and the second replaces $somelist.

Anything that can be written into the VTL template can be written into the main part of the Velocimacro. The TableRows macro is actually a foreach statement. There are two #ende statements in the definition of the #tablerows macro, the first one belongs to #foreach, and the second ends the macro definition.

#set ($greatlakes = ["Superior", "Michigan", "Huron", "Erie", "Ontario"]) #set ($color = "Blue") <table> #tablerows ($color $greatlakes) </table>

Please note that $greatlakes replaces $somelist. Thus, when the #tablerows macro is invoked, the following output is produced:

<table> <TR><TD bgcolor= "Blue" >Superior</td></tr> <TR><TD bgcolor= "Blue" >Michigan</td></tr> <TR><TD bgcolor= "Blue" >Huron</td></tr> <TR><TD bgcolor= "Blue" >Erie</td></tr> <TR><TD bgcolor= "Blue" >Ontario</td></tr> </table>

Velocimacros is defined within the Velocity template statement, which means it is not valid in other velocity templates within the same site. There are obvious advantages to defining a macro and sharing it with other templates: He reduces the task of repeatedly defining macros within a large number of templates, reduces the chance of error, and ensures that changes to other macros are valid for all other templates.

However, if #tablerows ($color $list) macro is defined within a Velocimacros template library, it can be used by other regular templates. Of course, it can be used for a variety of purposes, but also reusable multiple times. In the MUSHROOM.VM template that represents all fungal species (fungi), #tablerows macros can be used to list typical mushrooms.

#set ($parts = ["Volva", "Stipe", "annulus", "Gills", "pileus"]) #set ($cellbgcol = "#CC00FF") <table> #tablerows ($cellbgcol $parts) </table>

As we execute the request against MUSHROOM.VM, Velocity will find the #tablerows macro (defined in the Velocity.properties file) within the template Gallery and produce the following output:

<table> <TR><TD bgcolor= "#CC00FF" >volva</td></tr> <TR><TD bgcolor= "#CC00FF" >stipe</td></tr> <TR><TD bgcolor= "#CC00FF" >annulus</td></tr> <TR><TD bgcolor= "#CC00FF" >gills</td></tr> <TR><TD bgcolor= "#CC00FF" >pileus</td></tr> </table>

Velocimacro Parameters

The Velocimacros parameter can be the following VTL element:

References (Reference): elements that begin with ' $ '

Literal string (string literal): such as "$foo" or ' Hello '

Literal number: 1, 2 ....

Integer range: [1..2] or [$foo ... $bar]

Object array: ["A", "B", "C"]

Boolean true

Boolean Fake

When passing a reference as an argument to Velocimacros, note that the reference is passed by "name." This means that their values are generated in each use of their velocimacro. This feature allows you to pass the reference in the method call and make the method call each time you use it. For example, Fo, when the following velocimacro is invoked,

#macro (CallMe $a) $a $a $a #end #callme ($foo. Bar ())

As a result, the reference $foo is invoked 3 times in Method Bar ().

When you look at this, this feature is amazing when you think about Velocimacros's original motivation – avoid a lot of "cut-and-copy" operations in the VTL template-you'll understand. It allows you to pass a stateless object, such as an object that repeats some color order within a color table row, to Velocimacro.

If you need to use this feature, you can usually get a value from the method and pass it to the macro as a new reference:

#set ($myval = $foo. Bar ()) #callme ($myval)

Velocimacro Property

There are several line definitions in the Velocity.properties file that can be used to flexibly implement Velocimacros. For details, see the Development Guide (Developer Guide).

Velocimacro.library – is a comma-delimited list of all Velocimacro template libraries. By default, Velocity searches for a single library VM_GLOBAL_LIBRARY.VM ... Preconfigured template paths are used to find Velocimacro libraries.

Velocimacro.permissions.allow.inline – This property determines whether Velocimacros can be defined within a regular template, with a value of logical true or FALSE. By default, setting to True allows designers to define macros within the scale board.

Velocimacro.permissions.allow.inline.to.replace.global – logical True or FALSE to allow Velocimacro to be specified in the regular template Instead of a global macro that is defined in the template Library and passed through the Velocimacro.library property in the boot fashion. The default setting is False.

Velocimacro.permissions.allow.inline.local.scope – Logical True or FALSE, the default value is False. The Velocimacros that controls whether defined within the template is visible only within the template that defines it. In other words, if set to true, a template can define a macro that can only be used by him. You can use it to make some pretty macros, if a global call to another global macro, within a local (inline) scope, when called by a template, the template can define a private implementation of the second global macro called by the first global macro. All other templates are unaffected.

Velocimacro.context.localscope – The logical value is TRUE or FALSE, and the default value is False. When set to true, all modifications made within the Velocimacro through #set () are treated as local behavior of velocimacro and do not affect their context.

Velocimacro.library.autoreload – This property controls automatic loading of the Velocimacro library. The default value is False. If set to True, the invoked Velocimacro Source Library will be checked for changes and, if necessary, reload. This will allow you to change and test the Velocimacro library without having to restart the application server or servlet container, just as you would work on a regular template. This mode is valid only when the resource loader's cached mode is closed (such as File.resource.loader.cache = False). This feature is designed for development time and is not used in production mode.

Velocimacro Trivia

Currently, Velocimacros must first define it before it is first used in the stencil. This means that #macro () claim that it should be before using Velocimacros.

It is important to remember this if you want to #parse () a template that contains #macro () instructions. Because #parse () occurs at run time, the parser decides whether or not an element in the template that looks like a VM is really a VM, so parsing a series of VMS may not work as expected. To avoid this, you can simply use the velocimacro.library approach to allow velocity to load the VM at startup.

2 . escape VTL directives

The VTL can be escaped by a backslash ("/"), directives can be escaped with the backslash character in a manner similar to valid VTL references.

# # #include ("A.txt") renders as <contents of a.txt> #include ("A.txt") # #/#include ("A.txt") renders as/#include ("A.txt") /#include ("A.txt") # #//#include ("A.txt") renders as/<contents of a.txt> #include ("A.txt")

 

Should be cautious when escaping instructions that contain multiple script elements, such as f-else-end statements, within a single instruction. The following is a typical VTL if statement;

#if ($jazz)     Vyac Heslav Ganelin #end

 

If $jazz is true, The output is

 

If $jazz is false, there will be no output. Escaping script elements will change the output. Consider the following:

Vyacheslav Ganelin