Important
You are browsing the documentation for version 4.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.
See our Release Process documentation for more information on the currently supported and upcoming releases.
Configure Email Templates in the Back-Office¶
With the Oro applications, you can easily send numerous personalized emails using one template. For example, you can make a single template that welcomes {username}, assign it to an email campaign, and each of your subscribers will get a mail sent specifically to them.
Create a New Email Template¶
Navigate to System > Emails > Templates.
Click Create Template.
Define the general settings for the template.
The following fields are mandatory and must be defined:
Template Name — Name used to refer to the template in the system.
Type — Use html or plain text.
Owner — Limits the list of users that can manage the template, subject to the access and permission settings.
Optional field Entity Name is used to define an entity, variables whereof can be used in the template. If no entity name is defined, only system variables are available.
Important
If you want to use the template for autoresponses, the Entity Name field value should be Email.
Define the email template. Click on the necessary variable to add it to the text box.
Note
In the example below, the template contains a link to the website page composed with a piece of tracking code. Every time a user follows the link, visit event will be tracked for the campaign.
Click Preview to check your template.
Click Save if you are satisfied with the preview.
Note
You can delete , edit , and clone email templates on the page of all templates.
Important
Keep in mind that the ability to view, edit, clone, or delete email templates depends on specific roles and permissions defined in the system configuration. For more information about available access levels and permissions, see the Understand Roles and Permissions guide.
Hint
If you want to track the user-activity related to the emails sent within the email campaign, add a piece of tracking website code to the email template.
View Available Template Variables and Functions¶
For the security reasons, the only available variables are currently the ones listed on the Email Templates edit page in the back-office. However, there are a few exceptions. These are several Twig functions enabled in email templates that can be used to obtain some specific data in email templates.
The full list of these functions is the following:
Important
Keep in mind that when editing HTML email templates, you pass them to the WYSIWYG editor. WYSIWYG automatically tries to modify the given HTML template against the HTML specifications. Therefore, the text and tags that violate the HTML specifications should be wrapped up in the HTML comment. For example, there should not be any other tags or text between the <table></table> tags except thead, tbody, tfoot, th, tr, td.
Examples:
Invalid template:
1 <table>
2 <thead>
3 <tr>
4 <th><strong>ACME</strong></th>
5 </tr>
6 </thead>
7 {% for item in collection %}
8 <tbody>
9 {% for subItem in item %}
10 <tr>
11 {% if loop.first %}
12 <td>{{ subItem.key }}</td>
13 <td>{{ subItem.value }}</td>
14 {% endif %}
15 </tr>
16 {% endfor %}
17 </tbody>
18 {% endfor %}
19 </table>
Valid template:
1 <table>
2 <thead>
3 <tr>
4 <th><strong>ACME</strong></th>
5 </tr>
6 </thead>
7 <!--{% for item in collection %}-->
8 <tbody>
9 <!--{% for subItem in item %}-->
10 <tr>
11 <!--{% if loop.first %}-->
12 <td>{{ subItem.key }}</td>
13 <td>{{ subItem.value }}</td>
14 <!--{% endif %}-->
15 </tr>
16 <!--{% endfor %}-->
17 </tbody>
18 <!--{% endfor %}-->
19 </table>
Functions¶
date¶
1date()
Description: Converts an argument into a date to allow date comparison.
Example: See the Twig doc
oro_config_value¶
1oro_config_value(string $configSettingName)
Description: Returns the Oro config setting value.
Returns: string
calendar_date_range¶
1calendar_date_range(
2 \DateTime $startDate = null,
3 \DateTime $endDate = null,
4 $skipTime = false,
5 $dateType = null, \\IntlDateFormatter constant or it's string name
6 $timeType = null, \\IntlDateFormatter constant or it's string name
7 $locale = null,
8 $timeZone = null
9)
Description: Returns a string that represents a range between $startDate and $endDate, formatted according the given parameters.
Returns: string
- $endDate is not specified
Thu Oct 17, 2013 - when $skipTime = true
Thu Oct 17, 2013 5:30pm - when $skipTime = false
- $startDate equals to $endDate
Thu Oct 17, 2013 - when $skipTime = true
Thu Oct 17, 2013 5:30pm - when $skipTime = false
- $startDate and $endDate are the same day
Thu Oct 17, 2013 - when $skipTime = true
Thu Oct 17, 2013 5:00pm – 5:30pm - when $skipTime = false
- $startDate and $endDate are different days
Thu Oct 17, 2013 5:00pm – Thu Oct 18, 2013 5:00pm - when $skipTime = false
Thu Oct 17, 2013 – Thu Oct 18, 2013 - when $skipTime = true
Example:
1calendar_date_range(entity.start, entity.end, entity.allDay, 'F j, Y', 1)
calendar_date_range_organization¶
1calendar_date_range_organization(
2 \DateTime $startDate = null,
3 \DateTime $endDate = null,
4 $skipTime = false,
5 $dateType = null, \\IntlDateFormatter constant or it's string name
6 $timeType = null, \\IntlDateFormatter constant or it's string name
7 $locale = null,
8 $timeZone = null,
9 OrganizationInterface $organization = null
10)
Description: The same as ‘calendar_date_range’ but for a specific organization.
Returns: string
get_event_recurrence_pattern¶
1get_event_recurrence_pattern(Entity\CalendarEvent $event)
Description: This method is aimed at showing text description of a recurring event in email invitations.
Returns: string
Example:
1<!--{% if get_event_recurrence_pattern(entity) %}-->
2 <tr>
3 <td style="width: 65pt; padding: 0 5pt 0 9pt; line-height: 1.3em; font-family: Arial, Helvetica, sans-serif; font-size: 10pt; vertical-align: top"><strong>Repeats:</strong></td>
4 <td style="padding: 0 9pt 0 0; line-height: 1.3em; font-family: Arial, Helvetica, sans-serif; font-size: 10pt; vertical-align: top">{{ get_event_recurrence_pattern(entity) }}</td>
5 </tr>
6<!--{% endif %}-->
website_path¶
1website_path(string $route, array $routeParams, Website|null $website = null)
Description: Returns the absolute path for a specific route and parameters.
Returns: string
Example:
1<p>Please follow this link to confirm your email address: <a href="{{ website_path('oro_customer_frontend_customer_user_confirmation', {'username': entity.username, 'token': token}, entity.website) }}">Confirm</a></p>
website_secure_path¶
1website_secure_path()
Description: The same as ‘website_path’ but returns Secure (HTTPS) URL.
url¶
1 url()
Description: Returns the absolute URL (with scheme and host) for the given route.
Example: See the Symfony Twig Extensions (URL)
path¶
1 path()
Description: Returns the relative URL (without the scheme and host) for the given route.
Example: See the Symfony Twig Extensions (Path)
get_payment_methods (OroCommerce Only)¶
1get_payment_methods(Order $entity)
Description: Returns the allowed payment methods for orders.
Returns: array of OroBundlePaymentBundleTwigDTOPaymentMethodObject objests with payment method label and options (can be used as array of strings thanks to PaymentMethodObject::__toString method)
Example:
1 {% set payment_methods = get_payment_methods(entity) %}
2
3 <!--{% if payment_methods|length == 1 %}-->
4 <h4>Payment Method:</h4>
5 <!--{{ payment_methods[0] }}-->
6 <!--{% elseif payment_methods|length > 1 %}-->
7 <h4>Payment Methods:</h4>
8 <!--{{ payment_methods|join(', ') }}-->
9 <!--{% endif %}-->
Alternative example:
1{% set payment_methods = get_payment_methods(entity) %}
2{% if payment_methods|length == 1 %}
3 <strong>Payment Method: </strong>
4{% elseif payment_methods|length > 1 %}
5 <strong>Payment Methods: </strong>
6{% endif %}
7{% for payment_method in payment_methods %}
8 {{ payment_method.label }}
9 {% if payment_method.options|length > 0 %}
10 {{- ' (' ~ payment_method.options|join(', ') ~ ')' -}}
11 {% endif %}
12 <br/>
13{% endfor %}
get_payment_status_label (OroCommerce only)¶
1get_payment_status_label(Order $entity)
Description: Returns the translated label for the payment status.
See the \Oro\Bundle\PaymentBundle\Formatter\PaymentStatusLabelFormatter::formatPaymentStatusLabel method for details.
Returns: string
Example: See an example for the get_payment_status (OroCommerce only) method.
get_payment_status (OroCommerce only)¶
1get_payment_status(Order $entity)
Description: Returns the payment status for requested order.
Returns: string, one of OroBundlePaymentBundleProviderPaymentStatusProvider class statuses (‘full’, ‘partially’, ‘invoiced’, ‘authorized’, ‘declined’, ‘pending’)
Example:
1<strong>Payment Status: </strong>{{ get_payment_status_label(get_payment_status(entity)) }}
oro_order_shipping_method_label (OroCommerce only)¶
1oro_order_shipping_method_label(string $shippingMethod, string $shippingMethodType)
Description: Returns the translated label of the order`s shipping method.
Returns: string
Example:
1{% set shipping_method = oro_order_shipping_method_label(entity.shippingMethod, entity.shippingMethodType) %}
2<strong>Shipping Method: </strong>{{ shipping_method }}<br/>
rfp_products (OroCommerce Only)¶
1rfp_products(Oro\Bundle\RFPBundle\Entity\Request $entity)
Description: Returns a list of products requested by a buyer in this request for quote.
Returns:
1array: [
2 345 => [ \\Product ID
3 'name' => 'Yarn', \\ string, Product name
4 'sku' => 'YRN345erer', \\ string, Product SKU
5 'comment' => 'Most interesting product for us', \\ string, Comment in RFP for this product
6 'items' => [ \\array, Requested product items
7 38473 => [ \\Product Item ID
8 'quantity' => 49.86, \\ float, Product Item quantity
9 'price' => $price, \\ \Oro\Bundle\CurrencyBundle\Entity\Price object, Product Item price
10 'unit' => 'ft', \\ string, Product Item unit
11 ],
12 139473 => [ \\Product Item ID
13 'quantity' => 21.98, \\ float, Product Item quantity
14 'price' => $price, \\ \Oro\Bundle\CurrencyBundle\Entity\Price object, Product Item price
15 'unit' => 'item', \\ string, Product Item unit
16 ],
17 ...
18 ],
19 ],
20 ...
21]
Example:
1{% set products = rfp_products(entity) %}
2{% if products|length %}
3 <table style="border: 1px solid black;margin-top: 10px">
4 <thead>
5 <tr>
6 <th><strong>SKU</strong></th>
7 <th><strong>Product</strong></th>
8 <th><strong>Quantity</strong></th>
9 <th><strong>Target Price</strong></th>
10 <th><strong>Comment</strong></th>
11 </tr>
12 </thead>
13 <!--{% for product in products %}-->
14 <!--{% set numItems = product.items|length %}-->
15 <tbody>
16 <!--{% for item in product.items %}-->
17 <tr>
18 <!--{% if loop.first %}-->
19 <td rowspan="{{ numItems }}">{{ product.sku }}</td>
20 <td rowspan="{{ numItems }}">{{ product.name }}</td>
21 <!--{% endif %}-->
22
23 <td>{{ item.quantity }} {{ item.unit }}</td>
24 <td>{{ item.price ? item.price|oro_format_price : '' }}</td>
25
26 <!--{% if loop.first %}-->
27 <td rowspan="{{ numItems }}">{{ product.comment }}</td>
28 <!--{% endif %}-->
29 </tr>
30 <!--{% endfor %}-->
31 </tbody>
32 <!--{% endfor %}-->
33 </table>
34{% endif %}
line_items_discounts (OroCommerce only)¶
1line_items_discounts(Order $entity)
Description: Returns array of discount total sum for every order line item.
Returns: array
1array: [
2 '123123' => [ // Line Item ID
3 'value' => 15.065, \\ float, total sum of discount for the line item
4 'currency' => 'USD', \\ string, Currency of discount
5 ],
6 ...
7]
Example: See an example for order_line_items (OroCommerce only) method.
order_line_items (OroCommerce only)¶
1order_line_items(\Oro\Bundle\OrderBundle\Entity\Order $entity)
Description: Returns order line items.
Returns:
1array: [
2 'lineItems' => [
3 [
4 'product_name' => 'Boat', \\ string, Product name
5 'product_sku' => 'BO1BIG', \\ string, Product SKU
6 'quantity' => 1.00, \\ float, Product quantity
7 'unit' => 'item', \\ string, Product unit
8 'price' => $price, \\ \Oro\Bundle\CurrencyBundle\Entity\Price object, Product price
9 'comment' => 'Comment for this line Item', string
10 'ship_by' => $price, \\ \DateTime, Line item ship by field
11 'id' => $id, \\ int|string, Line item identifier value
12 'subtotal' => $price, \\\Oro\Bundle\CurrencyBundle\Entity\Price object, Line Item subtotal
13 ],
14 ...
15 ],
16 'subtotals' => [
17 [
18 'label' => 'Shipping', \\ string, Subtotal name
19 'totalPrice' => $price, \\\Oro\Bundle\CurrencyBundle\Entity\Price object, Subtotal Price
20 ],
21 ...
22 ],
23 'total' => [
24 'label' => 'Total', \\ string, label for Total
25 'totalPrice' => $price, \\\Oro\Bundle\CurrencyBundle\Entity\Price object, Total sum Price for all order line items
26 ],
27]
Example:
1<table style="border: 1px solid black;margin-top: 10px">
2 <thead>
3 <tr>
4 <th><strong>Item</strong></th>
5 <th><strong>Quantity</strong></th>
6 <th><strong>Price</strong></th>
7 <th><strong>Subtotal</strong></th>
8 <th><strong>Ship By</strong></th>
9 <th><strong>Notes</strong></th>
10 </tr>
11 </thead>
12 <tbody>
13 <!--{% set data = order_line_items(entity) %}-->
14 <!--{% set lineItemDiscounts = line_items_discounts(entity) %}-->
15 <!--{% for item in data.lineItems %}-->
16 <tr>
17 <td>
18 {{ item.product_name }}
19 <br>
20 SKU #: {{ item.product_sku }}
21 <br>
22 </td>
23 <td>{{ item.quantity|oro_format_short_product_unit_value(item.unit) }}</td>
24 <td>{{ item.price|oro_format_price }}</td>
25 <td>
26 {{ item.subtotal|oro_format_price }}
27 {% set matchedDiscount = lineItemDiscounts[item.id] %}
28 {% if matchedDiscount is not null and matchedDiscount.value > 0 %}
29 <br/>{{ (-matchedDiscount.value)|oro_format_currency({'currency': matchedDiscount.currency}) }}
30 {% endif %}
31 </td>
32 <td>{{ item.ship_by }}</td>
33 <td>{{ item.comment }}</td>
34 </tr>
35 <!--{% endfor %}-->
36 </tbody>
37</table>
Note
If none of these Twig functions cover your cases, you can create a custom Twig function that returns the desired data that you can use in email templates. Please, see OroEmailBundle documentation for details.
Filters¶
On top of functions, you can use filters in email templates. The full set of these filters is the following:
oro_format_datetime_organization
Localize Email Templates¶
To create email templates for different localizations, even the inactive ones, move from tab to tab and create the desired content for required localizations.
To enable the email template fallback to the parent localization, select the Use <localization> (Parent Localization) check box. If the localization does not have a parent, you can enable fallback to the default template value.
Business Tip
Interested in learning more about B2B eCommerce and how it differs from B2C? Read our in-depth information on the subject.