Skip to content

Commit 4715e95

Browse files
DavidLambauerDavidLambauer
committed
Add email_templates.md.
1 parent 3a159d0 commit 4715e95

File tree

1 file changed

+156
-0
lines changed

1 file changed

+156
-0
lines changed

‎email_templates.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Email Templates XML Reference Documentation
2+
3+
This reference documentation provides detailed information on the structure and usage of the `email_templates.xml` file
4+
in Magento 2. It is intended for developers familiar with PHP and Magento 2, and aims to provide authoritative and
5+
knowledgeable guidance on creating and configuring email templates using XML.
6+
7+
## Introduction
8+
9+
The `email_templates.xml` file is an important configuration file used in Magento 2 to define email templates that can
10+
be used for various email communications sent by the system. It allows developers to create customizable email templates
11+
with dynamic content and configuration options.
12+
13+
This document provides a comprehensive guide on how to create, configure, and utilize email templates using
14+
the `email_templates.xml` file in Magento 2.
15+
16+
## Structure of email_templates.xml
17+
18+
The `email_templates.xml` file follows a specific XML structure that defines the email templates and their associated
19+
configurations. Here is a basic example of the structure:
20+
21+
```xml
22+
23+
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
24+
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Email:etc/email_templates.xsd">
25+
<template id="template_id" label="Template Label" file="file_name.html" type="html">
26+
<variables>
27+
<!-- Variable definitions -->
28+
</variables>
29+
<styles>
30+
<!-- CSS definitions -->
31+
</styles>
32+
</template>
33+
</config>
34+
```
35+
36+
The root `<config>` element contains the XML namespace declaration and the schema location for validation.
37+
Inside `<config>`, there can be one or more `<template>` elements representing individual email templates.
38+
39+
Each `<template>` element requires the following attributes:
40+
41+
- `id`: A unique identifier for the template, typically in lowercase with underscores.
42+
- `label`: A human-readable label or name for the template.
43+
- `file`: The file name of the template HTML file (e.g., `file_name.html`).
44+
- `type`: The content type of the template, typically `html` for HTML email templates.
45+
46+
## Creating Email Templates
47+
48+
To create a new email template, you need to add a `<template>` element inside the `<config>` element of
49+
the `email_templates.xml` file. Here's an example:
50+
51+
```xml
52+
53+
<template id="custom_template" label="Custom Template" file="custom_template.html" type="html">
54+
<!-- Variable definitions and CSS styles go here -->
55+
</template>
56+
```
57+
58+
In the above example, we have defined a new email template with the ID `custom_template`, label `Custom Template`, and
59+
associated HTML file `custom_template.html`.
60+
61+
## Using Variables
62+
63+
Email templates often require dynamic content, such as customer names, order details, or product information. Magento 2
64+
provides a way to include variables in email templates to dynamically populate data.
65+
66+
To define variables for an email template, you need to add `<variable>` elements inside the `<variables>` section of
67+
the `<template>` element. Here's an example:
68+
69+
```xml
70+
71+
<template id="custom_template" label="Custom Template" file="custom_template.html" type="html">
72+
<variables>
73+
<variable name="customer_name" xsi:type="string">John Doe</variable>
74+
<variable name="order_id" xsi:type="string">12345</variable>
75+
</variables>
76+
<!-- CSS styles and email content go here -->
77+
</template>
78+
```
79+
80+
In the above example, we have defined two variables: `customer_name` and `order_id`. These variables can be accessed
81+
within the email template HTML file using the following syntax:
82+
83+
```html
84+
<p>Dear {{var customer_name}},</p>
85+
<p>Your order with ID {{var order_id}} has been processed.</p>
86+
```
87+
88+
During email rendering, the variables will be replaced with their corresponding values.
89+
90+
## Configuring Templates
91+
92+
Apart from variable definitions, you can configure various aspects of an email template using the `<template>` element's
93+
attributes. These attributes allow you to specify the subject, sender, and other settings for the email template.
94+
95+
Here's an example of configuring an email template:
96+
97+
```xml
98+
99+
<template id="custom_template" label="Custom Template" file="custom_template.html" type="html"
100+
subject="Custom Template Subject" sender_name="Store Name" sender_email="[email protected]">
101+
<!-- Variable definitions, CSS styles, and email content go here -->
102+
</template>
103+
```
104+
105+
In the above example, we have added the `subject`, `sender_name`, and `sender_email` attributes to the `<template>`
106+
element. These attributes control the subject line, sender name, and sender email address for the email template.
107+
108+
## Advanced Configuration
109+
110+
The `email_templates.xml` file supports advanced configuration options to customize email headers, attachments, and
111+
more. Here are a couple of examples:
112+
113+
### Adding Custom Headers
114+
115+
You can add custom headers to the email template by using the `<headers>` element inside the `<template>` element.
116+
Here's an example:
117+
118+
```xml
119+
120+
<template id="custom_template" label="Custom Template" file="custom_template.html" type="html" ...>
121+
<headers>
122+
<header name="X-Custom-Header">Custom Value</header>
123+
</headers>
124+
<!-- Variable definitions, CSS styles, and email content go here -->
125+
</template>
126+
```
127+
128+
In the above example, we have added a custom header `X-Custom-Header` with the value `Custom Value` to the email
129+
template.
130+
131+
### Adding Attachments
132+
133+
To include attachments in the email template, you can use the `<attachments>` element inside the `<template>` element.
134+
Here's an example:
135+
136+
```xml
137+
138+
<template id="custom_template" label="Custom Template" file="custom_template.html" type="html" ...>
139+
<attachments>
140+
<attachment type="mimetype" encoding="encoding_type">attachment_content</attachment>
141+
</attachments>
142+
<!-- Variable definitions, CSS styles, and email content go here -->
143+
</template>
144+
```
145+
146+
In the above example, we have added an attachment with the specified `type`, `encoding`, and `attachment_content`.
147+
Replace these values with the appropriate attachment details.
148+
149+
## Conclusion
150+
151+
The `email_templates.xml` file plays a crucial role in defining and configuring email templates in Magento 2. By
152+
understanding its structure and utilizing its features, you can create customizable email templates with dynamic
153+
content, variables, and advanced configuration options.
154+
155+
This reference documentation has provided you with a comprehensive understanding of `email_templates.xml` and equipped
156+
you with the knowledge to create and configure email templates in Magento 2.

0 commit comments

Comments
 (0)