Difference between revisions of "Customizing Email Templates"

From AbleCommerce Wiki
Jump to: navigation, search
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
Merchants can fully customize the customer notification email. It can include plain text, static HTML, and even dynamic information with the help of the full fledged template engine.
+
Merchants can fully customize the emails sent by Ablecommerce. The email templates defined in Ablecommerce can include plain text, static HTML, and even dynamic information with the help of a full fledged template engine.
  
−
NVelocity is used as the template engine to process the email templates. Templates are written in velocity template language (VTL), which is extremely simple and powerful.
+
nVelocity is used as the template engine to process the email templates. Email templates are written in velocity template language (VTL), which is extremely simple and powerful.
  
 
In a velocity template, certain objects put in the velocity context, can be accessed directly in a straight forward manner. For example if a ‘Store’ object, named “store” is available in the context, then using $store.Name we will get the name of the store. Similarly any method available in the ‘Store’ object can be called directly.
 
In a velocity template, certain objects put in the velocity context, can be accessed directly in a straight forward manner. For example if a ‘Store’ object, named “store” is available in the context, then using $store.Name we will get the name of the store. Similarly any method available in the ‘Store’ object can be called directly.
  
−
While writing templates for email messages in AbleCommerce, certain objects are automatically made available to the context, depending on the type of event.
+
In Ablecommerce certain pre-defined objects are made available to the velocity context for an email template depending on the event that triggered the email. The following table illustrates these objects and their availability for different events.
  
−
The following table illustrates the objects and their availability for different events.
+
{| {{Prettytable}}
−
<code>
+
|- {{Hl3}}
−
<pre>
+
!Object!!Type!!Available For
−
Object           Type                         Available To
+
|-
−
----------------------------------------------------------------------------------------------------
+
|$store||CommerceBuilder.Stores.Store||All Events
 +
|-
 +
|$order||CommerceBuilder.Orders.Order||OrderStatusUpdated<br/>PaymentAuthorized<br/>PaymentCaptured<br/>PaymentCapturedPartial<br/>PaymentAuthorizationFailed<br/>PaymentCaptureFailed<br/>OrderPlaced<br/>OrderCancelled<br/>OrderPaidPartial<br/>OrderPaid<br/> OrderPaidNoShipments<br/>OrderPaidCreditBalance<br/>ShipmentShipped<br/>OrderShipped<br/>OrderShippedPartial<br/>GiftCertificateValidated<br/>OrderNoteAddedByCustomer
 +
|-
 +
|$customer||CommerceBuilder.Users.User||OrderStatusUpdated<br/>PaymentAuthorized<br/>PaymentCaptured<br/>CustomerPasswordRequest<br/>PaymentCapturedPartial<br/>PaymentAuthorizationFailed<br/>PaymentCaptureFailed<br/>OrderPlaced<br/> OrderCancelled<br/>OrderPaidPartial<br/>OrderPaid<br/>OrderPaidNoShipments<br/>OrderPaidCreditBalance<br/>ShipmentShipped<br/>OrderShipped,OrderShippedPartial<br/>GiftCertificateValidated<br/>OrderNoteAddedByCustomer
 +
|-
 +
|$oldstatusname||System.String||OrderStatusUpdated
 +
|-
 +
|$products||CommerceBuilder.Products.Product||LowInventoryItemPurchased
 +
|-
 +
|$payment||CommerceBuilder.Payments.Payment||PaymentAuthorized<br/>PaymentCaptured<br/>PaymentCapturedPartial<br/>PaymentAuthorizationFailed<br/>PaymentCaptureFailed
 +
|-
 +
|$resetPasswordLink||System.String||CustomerPasswordRequest
 +
|-
 +
|$shipment||CommerceBuilder.Shipping.OrderShipment||ShipmentShipped
 +
|-
 +
|$giftcertificate||CommerceBuilder.Payments.GiftCertificate||GiftCertificateValidated
 +
|-
 +
|$note||CommerceBuilder.Orders.OrderNote||OrderNoteAddedByCustomer
  
−
store            CommerceBuilder.Stores.Store    All Events
+
|}
  
−
order            CommerceBuilder.Orders.Order    OrderStatusUpdated, PaymentAuthorized,
 
−
                                                  PaymentCaptured, PaymentCapturedPartial,
 
−
                                                  PaymentAuthorizationFailed,
 
−
                                                  PaymentCaptureFailed, OrderPlaced, OrderCancelled,
 
−
                                                  OrderPaidPartial, OrderPaid, OrderPaidNoShipments,
 
−
                                                  OrderPaidCreditBalance, ShipmentShipped,
 
−
                                                  OrderShipped, OrderShippedPartial, 
 
−
                                                  GiftCertificateValidated, OrderNoteAddedByCustomer
 
−
 
−
customer          CommerceBuilder.Users.User      OrderStatusUpdated, PaymentAuthorized,
 
−
                                                  PaymentCaptured, CustomerPasswordRequest, 
 
−
                                                  PaymentCapturedPartial,
 
−
                                                  PaymentAuthorizationFailed,
 
−
                                                  PaymentCaptureFailed, OrderPlaced, OrderCancelled,
 
−
                                                  OrderPaidPartial, OrderPaid, OrderPaidNoShipments,
 
−
                                                  OrderPaidCreditBalance, ShipmentShipped,
 
−
                                                  OrderShipped,OrderShippedPartial,
 
−
                                                  GiftCertificateValidated, OrderNoteAddedByCustomer
 
−
 
−
oldstatusname    System.String                    OrderStatusUpdated
 
−
 
−
products          CommerceBuilder.Products.Product LowInventoryItemPurchased
 
−
 
−
payment          CommerceBuilder.Payments.Payment PaymentAuthorized, PaymentCaptured,
 
−
                                                  PaymentCapturedPartial,
 
−
                                                  PaymentAuthorizationFailed,
 
−
                                                  PaymentCaptureFailed
 
−
resetPasswordLink System.String                    CustomerPasswordRequest
 
−
 
−
shipment          CommerceBuilder.Shipping.        ShipmentShipped
 
−
                  OrderShipment
 
−
 
−
giftcertificate  CommerceBuilder.Payments.        GiftCertificateValidated
 
−
                  GiftCertificate
 
−
 
−
note              CommerceBuilder.Orders.OrderNote OrderNoteAddedByCustomer
 
−
 
−
</pre>
 
−
</code>
 
  
 
Using the above objects in email templates, almost any type of email can be generated. Here are few examples.
 
Using the above objects in email templates, almost any type of email can be generated. Here are few examples.
  
 
Merchant Enters:
 
Merchant Enters:
−
 
+
<code><pre>
−
Dear $customer.PrimaryAddress.FirstName $customer.User.PrimaryAddress.LastName,
+
Dear $customer.PrimaryAddress.FirstName $customer.PrimaryAddress.LastName,
−
 
+
</pre></code>
 
AbleCommerce Sends:
 
AbleCommerce Sends:
−
 
+
<code><pre>
 
Dear Joe Smith,
 
Dear Joe Smith,
 +
</pre></code>
  
 
The example shown below demonstrates how a merchant might include an HTML table of items ordered.
 
The example shown below demonstrates how a merchant might include an HTML table of items ordered.
Line 99: Line 79:
  
 
</table>
 
</table>
 +
</pre></code>
  
−
AbleCommerce Sends:
 
  
 +
AbleCommerce Sends:
 +
<code><pre>
 
<table>
 
<table>
  
Line 150: Line 132:
 
In short, all basic programming constructs can be used in VTL. Loops can be done using #foreach, conditional statements can be done using #if-else.
 
In short, all basic programming constructs can be used in VTL. Loops can be done using #foreach, conditional statements can be done using #if-else.
  
−
'''Note:''' One important thing, that is often overlooked, is that in velocity templates, mathematical and conditional operators can be directly used only with integers. If you want to perform mathematical operations on non integer values (e.g. long or double) or want to compare non-integer values, you should use utility methods in VelocityUtils class.
+
For more information on nVelocity please visit [http://www.castleproject.org/others/nvelocity/index.html nVelocity Home Page].
  
−
'''For example:'''
+
[[Category:AbleCommerce 7]]
−
 
+
[[Category:AbleCommerce Gold]]
−
<code>
+
−
<pre>
+
−
VelocityUtils.compare(x,y)
+
−
 
+
−
returns
+
−
 
+
−
    *
+
−
 
+
−
      0 if x and y are equal,
+
−
    *
+
−
 
+
−
      greater than 0 if x is greater than y
+
−
    *
+
−
 
+
−
      less than 0 if y is greater than x
+
−
 
+
−
So if you want to check if x and y are equal, you can do something like this
+
−
 
+
−
#if ($VelocityUtils.compare($x,$y)==0)
+
−
 
+
−
  ....
+
−
 
+
−
  ....
+
−
 
+
−
#end
+
−
</pre>
+
−
</code>
+
−
 
+
−
Similarly multiplication, division, subtraction and addition can be done using VelocityUtils. For example;
+
−
<code>
+
−
<pre>
+
−
#set ($result = $VelocityUtils.multiply($x,$y) )
+
−
</pre>
+
−
</code>
+

Latest revision as of 11:40, 15 August 2013

Merchants can fully customize the emails sent by Ablecommerce. The email templates defined in Ablecommerce can include plain text, static HTML, and even dynamic information with the help of a full fledged template engine.

nVelocity is used as the template engine to process the email templates. Email templates are written in velocity template language (VTL), which is extremely simple and powerful.

In a velocity template, certain objects put in the velocity context, can be accessed directly in a straight forward manner. For example if a ‘Store’ object, named “store” is available in the context, then using $store.Name we will get the name of the store. Similarly any method available in the ‘Store’ object can be called directly.

In Ablecommerce certain pre-defined objects are made available to the velocity context for an email template depending on the event that triggered the email. The following table illustrates these objects and their availability for different events.

Object Type Available For
$store CommerceBuilder.Stores.Store All Events
$order CommerceBuilder.Orders.Order OrderStatusUpdated
PaymentAuthorized
PaymentCaptured
PaymentCapturedPartial
PaymentAuthorizationFailed
PaymentCaptureFailed
OrderPlaced
OrderCancelled
OrderPaidPartial
OrderPaid
OrderPaidNoShipments
OrderPaidCreditBalance
ShipmentShipped
OrderShipped
OrderShippedPartial
GiftCertificateValidated
OrderNoteAddedByCustomer
$customer CommerceBuilder.Users.User OrderStatusUpdated
PaymentAuthorized
PaymentCaptured
CustomerPasswordRequest
PaymentCapturedPartial
PaymentAuthorizationFailed
PaymentCaptureFailed
OrderPlaced
OrderCancelled
OrderPaidPartial
OrderPaid
OrderPaidNoShipments
OrderPaidCreditBalance
ShipmentShipped
OrderShipped,OrderShippedPartial
GiftCertificateValidated
OrderNoteAddedByCustomer
$oldstatusname System.String OrderStatusUpdated
$products CommerceBuilder.Products.Product LowInventoryItemPurchased
$payment CommerceBuilder.Payments.Payment PaymentAuthorized
PaymentCaptured
PaymentCapturedPartial
PaymentAuthorizationFailed
PaymentCaptureFailed
$resetPasswordLink System.String CustomerPasswordRequest
$shipment CommerceBuilder.Shipping.OrderShipment ShipmentShipped
$giftcertificate CommerceBuilder.Payments.GiftCertificate GiftCertificateValidated
$note CommerceBuilder.Orders.OrderNote OrderNoteAddedByCustomer


Using the above objects in email templates, almost any type of email can be generated. Here are few examples.

Merchant Enters: 

Dear $customer.PrimaryAddress.FirstName $customer.PrimaryAddress.LastName,

AbleCommerce Sends: 

Dear Joe Smith,

The example shown below demonstrates how a merchant might include an HTML table of items ordered.

Merchant Enters: 

<table>

<tr>

<th>Name</th>

<th>SKU</th>

<th>Quantity</th>

</tr>

#foreach( $orderItem in $order.orderItems )

<tr>

<td>$orderItem.Name<br>

<td>$orderItem.Sku</td>

<td align=center>$orderItem.Quantity</td>

</tr>

#end

<tr>

</table>


AbleCommerce Sends: 

<table>

<tr>

<th>Name</th>

<th>SKU</th>

<th>Quantity</th>

</tr>

<tr>

<td>128MB PC2100 DDR DIMM 184 Pin Memory Module</td>

<td>16X64D2100-CUSA</td>

<td align=center >1</td>

</tr>

<tr>

<td>CG814M Wireless Cable Modem</td>

<td>CG814MNA</td>

<td align=center >1</td>

</tr>

<tr>

<td>5.1 Channel PCI Surround-Sound Card</td>

<td>11000975</td>

<td align=center >1</td>

</tr>

</table>

In short, all basic programming constructs can be used in VTL. Loops can be done using #foreach, conditional statements can be done using #if-else.

For more information on nVelocity please visit nVelocity Home Page.

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