Difference between revisions of "NVelocity"

From AbleCommerce Wiki
Jump to: navigation, search
(initial content, basic syntax)
 
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
NVelocity is an open source templating engine employed by AbleCommerce to accomplish certain features - most notably the [[email template]] system.  The source originates from the project fork maintained by the [http://www.castleproject.org/others/nvelocity/index.html Castle project].
+
NVelocity is an open source templating engine employed by AbleCommerce to accomplish certain features - most notably the [[Email Templates|email template]] system.  By using special script and formatting codes, templates can be processed to include dynamic content.  Below is an overview of some of the most basic syntax for editing email templates.
−
 
+
−
By using special script and formatting codes, NVelocity templates can be processed to include dynamic content.  Below is an overview of some of the most basic syntax for editing email templates.
+
  
 
== Variable Substitution ==
 
== Variable Substitution ==
Line 9: Line 7:
 
Standard Syntax: $variable_name
 
Standard Syntax: $variable_name
  
−
Hello $User.FirstName!
+
<pre>Hello $user.PrimaryAddress.FirstName!</pre>
  
 
Explicit Syntax: ${variable_name}
 
Explicit Syntax: ${variable_name}
  
−
Hello ${User.FirstName}!
+
<pre>Hello ${user.PrimaryAddress.FirstName}!</pre>
  
 
Standard syntax cannot be used if your variable is part of a larger string where the variable name would not be clearly defined. Below shows an example of incorrect use of the standard syntax, where explicit syntax must be used instead:
 
Standard syntax cannot be used if your variable is part of a larger string where the variable name would not be clearly defined. Below shows an example of incorrect use of the standard syntax, where explicit syntax must be used instead:
Line 19: Line 17:
 
Incorrect with Standard syntax:
 
Incorrect with Standard syntax:
  
−
some_text$variable_namesome_more_text
+
<pre>some_text$variable_namesome_more_text</pre>
  
 
Correct with Explicit syntax:
 
Correct with Explicit syntax:
  
−
some_text${variable_name}some_more_text
+
<pre>some_text${variable_name}some_more_text</pre>
  
 
When you reference variables you are accessing the object through the .NET framework. You can use traditional .NET syntax to access properties and methods. A common example might be to provide string formats:
 
When you reference variables you are accessing the object through the .NET framework. You can use traditional .NET syntax to access properties and methods. A common example might be to provide string formats:
  
−
$user.LastLoginDate.ToString("mm-ddd-yyyy")
+
<pre>$user.LastLoginDate.ToString("mm-ddd-yyyy")</pre>
  
 
== nVelocity Scripting ==
 
== nVelocity Scripting ==
Line 33: Line 31:
 
With the nVelocity scripting language you can implement conditional logic and looping to create dynamic output.  Any line that begins with a # pound sign is interpreted as a line of script.
 
With the nVelocity scripting language you can implement conditional logic and looping to create dynamic output.  Any line that begins with a # pound sign is interpreted as a line of script.
  
−
'''Conditional Statements'''
+
===Conditional Statements===
  
 
You can employ conditional logic in your email templates with the if-end statement. For example:
 
You can employ conditional logic in your email templates with the if-end statement. For example:
  
−
#if($User.IsAnonymous)
+
<pre>
 +
#if($user.IsAnonymous)
  
 
     You can register now to get the great benefits of membership!
 
     You can register now to get the great benefits of membership!
Line 43: Line 42:
 
#else
 
#else
  
−
     Welcome back $User.UserName!
+
     Welcome back $User.Username!
  
 
#end
 
#end
 +
</pre>
  
−
'''Looping'''
+
===Looping===
  
 
You can loop over collections of items with the foreach-end statement. For example:
 
You can loop over collections of items with the foreach-end statement. For example:
  
 +
<pre>
 
Current exchange rates for currencies:
 
Current exchange rates for currencies:
  
Line 57: Line 58:
 
<tr><th>Currency</th><th>Rate</th></tr>
 
<tr><th>Currency</th><th>Rate</th></tr>
  
−
#foreach($currency in $Store.Currencies)
+
#foreach($currency in $store.Currencies)
  
 
<tr><td>$currency.Name</td><td>$currency.ExchangeRate</td></tr>
 
<tr><td>$currency.Name</td><td>$currency.ExchangeRate</td></tr>
Line 64: Line 65:
  
 
</table>
 
</table>
 +
</pre>
  
−
'''Advanced Looping'''
+
===Advanced Looping===
−
The foreach statement supports additional features to enable things like alternating rows, headers, and footers.
+
  
 +
The foreach statement supports additional features to enable things like alternating rows, headers, and footers.
  
 +
<pre>
 
#foreach($i in $items)
 
#foreach($i in $items)
  
Line 108: Line 111:
  
 
#end
 
#end
 +
</pre>
 +
 +
===Set Statement===
  
−
'''Set Statement'''
 
 
You can create new nVelocity variables using the set statement.
 
You can create new nVelocity variables using the set statement.
  
 +
<pre>
 
#set ($counter = 1)
 
#set ($counter = 1)
  
Line 126: Line 132:
 
<br />
 
<br />
  
−
All transactions are conducted in $Store.PrimaryCurrency.Name.
+
All transactions are conducted in $store.PrimaryCurrency.Name.
 +
</pre>
  
−
'''Including Comments'''
+
===Including Comments===
−
You can include comments in your nVelcoity script.  Single line comments are created by starting a line with a ## double pound sign.
+
  
 +
You can include comments in your nVelocity script.  Single line comments are created by starting a line with a ## double pound sign.
 +
 +
<pre>
 
## single line comment will not be output
 
## single line comment will not be output
 +
</pre>
  
−
Multi line comments can also be included, by using the #* &ldots; *# syntax:
+
Multi line comments can also be included, by using the #* ... *# syntax:
  
 +
<pre>
 
#* This is a
 
#* This is a
  
Line 144: Line 155:
  
 
*#
 
*#
 +
</pre>
 +
 +
== Licensing ==
 +
NVelocity is distributed under the Apache License, version 1.1.  AbleCommerce links to a modified version of the Castle fork of NVelocity.  The modification is made from Castle's 5837 SVN revision, and is limited to adding the AllowPartiallyTrustedCallers attribute to the library.  This allows the portions of the library used by AbleCommerce to work in partially trusted ASPNET environments.  Our modified version of the NVelocity source code is available for download from our ftp site at ftp://ftp.ablecommerce.com/thirdparty.
 +
 +
[[Category:Merchant User Guide]]

Latest revision as of 21:39, 24 July 2009

NVelocity is an open source templating engine employed by AbleCommerce to accomplish certain features - most notably the email template system. By using special script and formatting codes, templates can be processed to include dynamic content. Below is an overview of some of the most basic syntax for editing email templates.

Variable Substitution

Variables are indicated by a dollar sign, and may be enclosed in curly braces. Variables can appear anywhere within the template.

Standard Syntax: $variable_name 

Hello $user.PrimaryAddress.FirstName!

Explicit Syntax: ${variable_name} 

Hello ${user.PrimaryAddress.FirstName}!

Standard syntax cannot be used if your variable is part of a larger string where the variable name would not be clearly defined. Below shows an example of incorrect use of the standard syntax, where explicit syntax must be used instead:

Incorrect with Standard syntax: 

some_text$variable_namesome_more_text

Correct with Explicit syntax: 

some_text${variable_name}some_more_text

When you reference variables you are accessing the object through the .NET framework. You can use traditional .NET syntax to access properties and methods. A common example might be to provide string formats: 

$user.LastLoginDate.ToString("mm-ddd-yyyy")

nVelocity Scripting

With the nVelocity scripting language you can implement conditional logic and looping to create dynamic output. Any line that begins with a # pound sign is interpreted as a line of script.

Conditional Statements

You can employ conditional logic in your email templates with the if-end statement. For example: 

#if($user.IsAnonymous)

    You can register now to get the great benefits of membership!

#else

    Welcome back $User.Username!

#end

Looping

You can loop over collections of items with the foreach-end statement. For example: 

Current exchange rates for currencies:

<table>

<tr><th>Currency</th><th>Rate</th></tr>

#foreach($currency in $store.Currencies)

<tr><td>$currency.Name</td><td>$currency.ExchangeRate</td></tr>

#end

</table>

Advanced Looping

The foreach statement supports additional features to enable things like alternating rows, headers, and footers. 

#foreach($i in $items)

#each

text which appears for each item

#before

text which appears before each item

#after

text which appears after each item

#between

text which appears between each two items

#odd

text which appears for every other item, including the first

#even

text which appears for every other item, starting with the second

#nodata

Content rendered if $items evaluated to null or empty

#beforeall

text which appears before the loop, only if there are items matching condition

#afterall

text which appears after the loop, only of there are items matching condition

#end

Set Statement

You can create new nVelocity variables using the set statement. 

#set ($counter = 1)

Currencies provided by $Store.Name:<br />

#foreach($currency in $Store.Currencies)

$counter. $currency.Name<br />

#set ($counter = $counter + 1)

#end

<br />

All transactions are conducted in $store.PrimaryCurrency.Name.

Including Comments

You can include comments in your nVelocity script. Single line comments are created by starting a line with a ## double pound sign. 

## single line comment will not be output

Multi line comments can also be included, by using the #* ... *# syntax: 

#* This is a

comment that spans

multiple lines and will

not be displayed

*#

Licensing

NVelocity is distributed under the Apache License, version 1.1. AbleCommerce links to a modified version of the Castle fork of NVelocity. The modification is made from Castle's 5837 SVN revision, and is limited to adding the AllowPartiallyTrustedCallers attribute to the library. This allows the portions of the library used by AbleCommerce to work in partially trusted ASPNET environments. Our modified version of the NVelocity source code is available for download from our ftp site at ftp://ftp.ablecommerce.com/thirdparty.

Retrieved from "http://wiki.ablecommerce.com/index.php?title=NVelocity&oldid=726"