Difference between revisions of "Customizing Email Templates"

From AbleCommerce Wiki
Jump to: navigation, search
Line 52: Line 52:
 
note              CommerceBuilder.Orders.OrderNote OrderNoteAddedByCustomer  
 
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.
 +
 +
Merchant Enters:
 +
 +
Dear $customer.PrimaryAddress.FirstName $customer.User.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:
 +
<code>
 +
<pre>
 +
<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>
 +
</pre>
 +
</code>
 +
 +
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 example:'''
 +
 +
<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>
 
</pre>
 
</code>
 
</code>

Revision as of 05:22, 2 September 2008

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.

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.

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.

The following table illustrates the objects and their availability for different events. 

Object            Type              	            Available To
----------------------------------------------------------------------------------------------------

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

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.User.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.

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 example: 

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

Similarly multiplication, division, subtraction and addition can be done using VelocityUtils. For example; 

#set ($result = $VelocityUtils.multiply($x,$y) )

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