Joomla Mail Templates in Phoca Cart

Phoca Cart 5 integrates with the native Joomla! Mail Templates system. All transactional emails sent by Phoca Cart — order confirmations, cancellation (withdrawal) notifications, gift vouchers, stock watchdog alerts, ask-a-question notifications, submit item notifications, and subscription events — are managed through the standard Joomla! Mail Templates interface in administration.

This chapter describes the Phoca Cart mail template types, how to view and edit them, and how to override their layout files using the standard Joomla! template override mechanism.

Overview of Joomla Mail Templates

Joomla Mail Templates allow site administrators to customise the subject and body of every system email sent by Joomla! core and third-party extensions including Phoca Cart. The templates support both plain text and HTML formats and can contain dynamic placeholder tags that are replaced with real data at the moment the email is sent.

Mail Templates are accessed from:

Joomla! Administration → System → Templates panel → Mail Templates

The list shows all registered mail templates grouped by extension. Filter the list by selecting Phoca Cart in the Filter by Component dropdown to see only Phoca Cart templates.

Phoca Cart Mail Template Types

Phoca Cart registers mail templates for all major transactional emails. The templates are identified by a key in the format com_phocacart..

Order Status Templates

Order status templates are dynamically created per order status. Each order status defined in Phoca Cart generates its own set of mail templates when that status is saved. The template keys contain the numeric ID of the order status.

These templates are generated automatically. Go to Administration → Phoca Cart → Order Statuses, open any status, and configure whether it sends emails to the customer, to others, or for gift vouchers. Joomla! Mail Templates will then contain entries for it, which you can edit in System → Mail Templates.

The placeholder tags available in order status templates include {html.document}, {text.document}, {document}, {ordernumber}, {status_title}, and {sitename}. The {html.document} and {text.document} tags are replaced with the fully rendered output of the Phoca Cart mail layout files — see the Phoca Cart Mail Layout Files section below.

Cancellation (Withdrawal) Templates

Ask a Question Templates

Submit Item Templates

Stock Watchdog Template

Gift Voucher Templates

Gift voucher emails are sent as part of the order status flow using the gift and gift_notification variants of the order status templates described above. The layout used for rendering the gift voucher content is gift.php (see Phoca Cart Mail Layout Files below).

Subscription Templates

Subscription emails are sent for various subscription lifecycle events:

Editing a Mail Template

To edit a Phoca Cart mail template:

1. Go to Joomla! Administration → System → Mail Templates
2. Filter by Phoca Cart in the Filter by Component dropdown
3. Click on the mail template title you want to edit

The mail template editor contains the following fields:

For order status templates, the Body (HTML) field typically contains {html.document} and the Body (Plain Text) field typically contains {text.document}. These tags are replaced at send time with the rendered output of the corresponding Phoca Cart layout file (see below). You can add extra text or HTML above or below these tags directly in the editor.

Options Tab

Each mail template has an Options tab that allows overriding the site-wide mail settings for that specific template:

Phoca Cart Mail Layout Files

Phoca Cart provides dedicated PHP layout files that build the HTML (and plain text) content of each email. These are the files that produce what ends up in the {html.document} and {text.document} placeholder tags. The layout files are organised into two parallel folder trees inside the component:

components/com_phocacart/layouts/phocacart/mail/html/    ← HTML format layouts
components/com_phocacart/layouts/phocacart/mail/text/    ← Plain text format layouts

Each mail type has an entry-point file at the root of html/ or text/, which orchestrates a set of sublayout files stored in a subfolder of the same name. The entry-point calls $this->sublayout(...) to render each section, assembles the results into a $blocks array, and outputs the complete HTML structure.

Entry-point layout files

These are the top-level files, one per mail type. Each exists in both html/ and text/ variants:

Order sublayout files

The order type is the most complex. It is split into the following sublayouts, present in both html/order/ and text/order/:

Other sublayout files

Note: The text/ folder mirrors the html/ folder structure but all files output plain text instead of HTML. There is no styles.php in text/ layouts since plain text emails carry no CSS.

Overriding Phoca Cart Mail Layout Files

Phoca Cart mail layout files follow the standard Joomla! layout override mechanism. Copy any file from the component to the corresponding path inside your active site template and edit it there. Your changes will not be lost when Phoca Cart is updated because the component files are never modified.

Override path structure

Source location (original files inside the component, do not edit these directly):

components/com_phocacart/layouts/phocacart/mail/html/
components/com_phocacart/layouts/phocacart/mail/text/

Override location (files you create inside your active site template):

templates//html/layouts/com_phocacart/phocacart/mail/html/
templates//html/layouts/com_phocacart/phocacart/mail/text/

Replace with the folder name of your active site template, for example cassiopeia or phoca_premiere.

Example — override the order email products block

To change how the product list is rendered in order emails, copy only the products sublayout:

FROM:

components/com_phocacart/layouts/phocacart/mail/html/order/products.php

TO:

templates/phoca_premiere/html/layouts/com_phocacart/phocacart/mail/html/order/products.php

Edit the copy and make your changes. Phoca Cart will automatically pick up the override.

Example — override the order totals block

FROM:

components/com_phocacart/layouts/phocacart/mail/html/order/totals.php

TO:

templates/phoca_premiere/html/layouts/com_phocacart/phocacart/mail/html/order/totals.php

Example — override the full order email structure

To change the overall layout and block arrangement of the HTML order email (for example, to move the product list above the address blocks, or to add a completely new section):

FROM:

components/com_phocacart/layouts/phocacart/mail/html/order.php

TO:

templates/phoca_premiere/html/layouts/com_phocacart/phocacart/mail/html/order.php

Inside this entry-point file you can rearrange, add, or remove the $displayData['blocks'] that are assembled and output. Each block is still rendered by its own sublayout file (which itself can be independently overridden).

Example — override the cancellation email (customer)

FROM:

components/com_phocacart/layouts/phocacart/mail/html/cancellation/customer.php

TO:

templates/phoca_premiere/html/layouts/com_phocacart/phocacart/mail/html/cancellation/customer.php

Tip: You can override just the individual sublayout files you need without touching the entry-point file. Joomla! resolves each sublayout file independently through the override system, so for example overriding only order/billing.php is perfectly valid and has no effect on the other order blocks.

Tip: Always override both the html/ and text/ variants if you are changing content (e.g. adding a field). The text/ layout is used when the site sends plain-text or multipart emails and should reflect the same information as the HTML version.

Overriding the Joomla Mail Wrapper Layout

In addition to the Phoca Cart layout files above, Joomla! supports a global HTML wrapper layout that surrounds all HTML emails with a branded outer frame (logo, header, footer). This is a standard Joomla! feature entirely separate from the Phoca Cart sublayout system.

To create a custom Joomla mail wrapper layout:

1. Go to Joomla! Administration → System → Site Templates → open your active template
2. Click the Create Overrides tab
3. Select joomla → mail from the tree
4. Joomla will copy the base wrapper file to:

templates//html/layouts/joomla/mail/mailtemplate.php

5. Edit this file to customise the outer HTML frame — brand colours, logo, header, footer.

You can create multiple files in this folder, for example mailtemplate_order.php and mailtemplate_minimal.php. All .php files found in this folder appear in the Layout dropdown inside each mail template's Options tab.

To apply your custom wrapper to a specific Phoca Cart mail template: go to System → Mail Templates, open the template, click the Options tab, set Mail Template Layout to Enabled, and select your layout file from the dropdown.

Mail Format Settings

The email format for all outgoing emails is controlled globally in:

Joomla! Administration → System → Mail Templates → Options button

Note: The Body (HTML) field in the editor and the html/ layout files are only used when Mail Format is set to HTML or Both. When set to Plain Text, only the text/ layout files and the plain text body are used.

How It All Fits Together

The following diagram shows the complete flow when Phoca Cart sends an order status email:

Phoca Cart triggers email (e.g. order status changes to "Shipped")
        │
        ▼
MailHelper::renderBody('order', 'html', $data, $mailData)
  Loads: components/com_phocacart/layouts/phocacart/mail/html/order.php
  Override: templates//html/layouts/com_phocacart/phocacart/mail/html/order.php
        │
        ├─ sublayout('styles')      → html/order/styles.php
        ├─ sublayout('header')      → html/order/header.php
        ├─ sublayout('info')        → html/order/info.php
        ├─ sublayout('billing')     → html/order/billing.php
        ├─ sublayout('shipping')    → html/order/shipping.php
        ├─ sublayout('products')    → html/order/products.php
        ├─ sublayout('totals')      → html/order/totals.php
        ├─ sublayout('link')        → html/order/link.php
        ├─ sublayout('downloads')   → html/order/downloads.php
        ├─ sublayout('taxes')       → html/order/taxes.php
        └─ sublayout('rewardpoints')→ html/order/rewardpoints.php
        │
        │   (each sublayout can be individually overridden in the template folder)
        │
        ▼
Rendered HTML stored as $mailData['html.document']
Same flow for 'text' format → $mailData['text.document']
        │
        ▼
Joomla Mail Template (System → Mail Templates)
  com_phocacart.order_status.
  Body (HTML) field e.g.: "Dear customer, {html.document}"
  {html.document} is replaced with the rendered layout output
        │
        ▼
Optional: Joomla mail wrapper layout
  templates//html/layouts/joomla/mail/mailtemplate.php
  Branded outer HTML frame: logo, header, footer
        │
        ▼
Email delivered to customer / vendor / administrator

The same flow applies to plain text using renderBody('order', 'text', ...) and the {text.document} tag.

Step-by-Step: Customising an Order Email

Step 1 — Find the correct mail template

Go to System → Mail Templates and filter by Phoca Cart. Order status templates are listed as com_phocacart.order_status.. Find the entry for the order status you want to customise (the ID corresponds to the status ID visible in Phoca Cart → Order Statuses).

Step 2 — Edit the subject and body text

Click the template. In the Body (HTML) field you will typically find {html.document} which is replaced at send time by the rendered layout. You can add introductory text above it or a closing remark below it directly in this field without touching any layout files.

Step 3 — Override a sublayout to change the HTML content

To change what appears inside the email — for example to show additional product fields in the product list — copy:

components/com_phocacart/layouts/phocacart/mail/html/order/products.php

to:

templates/phoca_premiere/html/layouts/com_phocacart/phocacart/mail/html/order/products.php

Edit the copy. No other files need to be changed.

Step 4 — Override styles to adjust the visual design

To change fonts, colours or spacing copy:

components/com_phocacart/layouts/phocacart/mail/html/order/styles.php

to:

templates/phoca_premiere/html/layouts/com_phocacart/phocacart/mail/html/order/styles.php

The styles.php sublayout defines inline CSS style strings (referenced as $styles['fs-normal'], $styles['w100'], etc.) that are used by all other order sublayout blocks.

Step 5 — Add a branded outer frame (optional)

Create a Joomla mail wrapper override as described in Overriding the Joomla Mail Wrapper Layout, then assign it to the mail template in its Options tab.

Step 6 — Test

Place a test order through your shop and trigger the relevant status change, or use Global Configuration → Server → Send Test Mail to verify the email renders correctly in your email client.

Multilingual Mail Templates

If your site runs in multiple languages, Joomla! Mail Templates supports per-language subject and body content. To translate a Phoca Cart mail template:

1. Go to System → Mail Templates, open the desired Phoca Cart template
2. Use the language switcher in the editor to switch to a different language
3. Enter the translated subject and body for that language
4. Save

Phoca Cart passes the user's language ($order->user_lang) or the site's default language ($order->default_lang) to the mail template when sending emails, so the correct language version is automatically selected.

Tips and Troubleshooting

HTML emails are not being sent

Check System → Mail Templates → Options and verify that Mail Format is set to HTML or Both. When set to Plain Text, the HTML body field and all html/ layout files are ignored.

The layout override is not being picked up

Make sure the override path is exact. The correct structure is:

templates//html/layouts/com_phocacart/phocacart/mail/html/.php
templates//html/layouts/com_phocacart/phocacart/mail/html//.php

Note the two-level sub-path phocacart/mail/ inside layouts/com_phocacart/. Folder names are case-sensitive on Linux servers.

Overriding one sublayout does not affect other blocks

Each sublayout is resolved independently. You can safely override only order/products.php and leave all other blocks (billing.php, totals.php, etc.) untouched — they will continue to use the originals from the component.

The {html.document} tag appears literally in the received email

This means the Phoca Cart html/ layout failed to render, most likely due to a PHP error in an overridden file. Check your server error log. When rendering fails the tag is not replaced.

Wrapper layout is not applied

In the mail template's Options tab verify that Mail Template Layout is set to Enabled and a layout file is selected. Also confirm that Per Template Mail Settings is set to Yes in the global Mail Templates Options button.