User documentation · Version 1.0.2
VM Mail & Invoice Studio
Give your VirtueMart order emails and invoice PDFs a consistent design, using your shop name, logo and accent colour.
This guide covers both editions: VirtueMart 4.2.6–4.8 with Joomla 5 and VirtueMart 5 with Joomla 6. The Studio workflow and design features are the same; choose the installation package for your platform.
1. Choose the correct edition
| Requirement | VM4 edition | VM5 edition |
|---|---|---|
| Joomla | 5.x | 6.x |
| VirtueMart | 4.2.x (4.2.6 or later), 4.4.x, 4.6.x and 4.8.x | 5.x |
| PHP | 8.1 or later | 8.3 or later |
| PDF engine | VirtueMart’s separately installed TCPDF package | |
| Core installation ZIP | pkg_vmmailinvoicestudio_vm48_v1.0.2.zip |
pkg_vmmailinvoicestudio_v1.0.2.zip |
The VM4 edition supports 4.2.x from 4.2.6, 4.4.x, 4.6.x and 4.8.x on Joomla 5. Versions below 4.2.6, development branches and prereleases are not supported. Enable Joomla’s backward compatibility plugin where required by VirtueMart. Both editions use the same Studio extension identifiers. Install only the edition matching your site.
The VM4 core and design-pack ZIP names retain vm48; these are also the correct downloads for the supported 4.2, 4.4 and 4.6 versions.
You need administrator access with permission to manage Studio settings and write its template overrides. The site-template directory must be writable when applying or removing overrides.
2. Install and activate Studio
- Back up your site and try the installation on a staging copy first.
- Check that the matching Joomla, VirtueMart and TCPDF packages are installed. For the VM4 edition, use Joomla 5 with PHP 8.1 or later and one of the VirtueMart versions listed above.
- In Joomla administration, open System → Install → Extensions and upload the appropriate core ZIP. Upload the complete package; do not extract and install its child ZIPs separately.
- Open Components → VM Mail & Invoice Studio.
- Set your branding, choose the designs under Order email and Invoice, and set Enable this design → Yes for each document type you want styled. Click Save in Studio.
- In VirtueMart configuration, enable template layout overrides (
useLayoutOverrides). - In Studio’s Use Studio in your shop section, find the site template selected in VirtueMart and click Apply Studio overrides. Confirm its status is Studio overrides applied.
- Enable HTML order emails in VirtueMart, then test a new order email and a newly generated invoice.
Both document designs start disabled on a fresh installation. Saving a design and applying the template overrides are separate steps: both must be complete for real documents to use Studio.
If VirtueMart uses a different site template from Joomla’s default, apply Studio to the template VirtueMart actually uses. Repeat for any other templates your shop uses for these documents.
3. Set your brand identity
| Field | How it works |
|---|---|
| Shop name | Enter the name shown in the design heading. Leave blank to use the VirtueMart vendor store name in real documents. |
| Accent colour | Choose the colour used by the design’s heading and other accents. This setting is shared by order emails and invoices. |
| Additional brand logo | Optionally select a PNG, JPG or GIF inside Joomla’s images/ folder. External image URLs are not accepted. This logo appears in the document body. |
| Introduction / Closing note | Optional plain text, configured separately for email and invoice. Line breaks are supported. These fields are not HTML or PHP template editors. |
VirtueMart still controls the recurring PDF header and footer, including its vendor logo. Leave Additional brand logo empty if you want only the existing letterhead logo.
After changing settings, click Save and wait for Design saved.
4. Configure order emails
- Expand Order email in Studio.
- Set Enable this design → Yes.
- Choose a Design template: Classic, Modern or a compatible installed pack design.
- Optionally add an introduction and closing note, then click Save.
- Select Order email in the preview, then check a real shopper and vendor email from a test order.
VirtueMart’s native messages, addresses, items, payment/shipment content and plugin output remain the source of email content. Which emails are sent, when they are sent and who receives them remain VirtueMart settings.
Studio styles HTML emails. Plain-text messages cannot display the HTML design. Email clients may render spacing, fonts and images differently from the browser preview.
5. Configure invoice PDFs
- Expand Invoice in Studio.
- Set Enable this design → Yes and choose a Design template.
- Optionally add invoice-specific introduction and closing text, then click Save.
- Check the Invoice preview and open Sample PDF.
- Place a new test order and move it to a status that generates an invoice according to your VirtueMart configuration. Inspect that newly generated PDF.
VirtueMart controls invoice generation, numbering, paper size, orientation, margins, recurring header/footer and terms. Studio styles the invoice body. Delivery notes use the native VirtueMart layout.
Studio includes a Unicode font for supported PDF text, including Slovenian characters such as č, Č, š, Š, ž and Ž. If the customer record itself contains a question mark instead of the correct character, correct that source data as well.
6. Classic and Modern
Classic and Modern are always included with the core application. They do not require a separate design pack. Email and invoice selections are independent: for example, you can use Modern for emails and Classic for invoices.
| Feature | Classic | Modern |
|---|---|---|
| Heading | Plain background with accent-coloured branding | Filled accent-colour banner |
| Details layout | Compact invoice details above billing and shipping details | Billing details in the left column; invoice details in the right column |
| Customer name | Separate native name fields | First, middle and last name combined where available |
| Address | Separate native address fields | Street, postcode and city combined; additional address and custom fields retained |
| Ship to block | Shown | Hidden |
| Order date and order status in top details | Shown | Hidden |
| Order-history panel: Date / Order Status / Comment | Shown | Hidden |
| Invoice/delivery dates, order number, payment/shipment methods and totals | Retained when supplied by VirtueMart | Retained when supplied by VirtueMart |
These omissions apply to the Modern invoice layout. They do not delete order data or remove information from VirtueMart administration. They also do not remove product-status columns supplied by the native item table.
7. Understand the previews
Browser preview
Use the Order email and Invoice buttons to view the saved design with fictional data. Save changes before refreshing the preview. Sample names, items and amounts are not taken from your orders.
Sample PDF
Uses VirtueMart’s PDF engine and current vendor paper settings. Check it for PDF-specific layout and character rendering. It is a sample document, not a tax invoice.
Real documents include your actual vendor details, order fields, product options, tax breakdowns, plugin content and terms. Their length and page breaks can differ from the sample. Always check a newly generated invoice and real order emails after setup.
8. Add optional design packs
Design packs are separate Joomla plugins. A pack can add email designs, invoice designs or both, and can be supplied or sold separately from Studio. Install a pack made for your Joomla/Studio edition.
- Install the matching Studio core 1.0.2 package. Pack 1 requires core 1.0.1 or later; the news banner and add-on notices require core 1.0.2.
- Upload the separate design-pack ZIP through Joomla’s extension installer.
- Open System → Manage → Plugins, locate the pack and enable it. Keep its Access set to Public so it is available when shopper documents are generated.
- Return to Studio and select the new design under Order email or Invoice. Only designs supporting that document type are listed.
- Click Save, check the preview/Sample PDF and test real documents.
Pack 1: VMStudioDesign - Mail Invoice TP 1
This separately purchased pack is release 1.0 and has the same install name in both editions: VMStudioDesign - Mail Invoice TP 1. Choose the ZIP matching your site:
| Edition | Pack 1 ZIP |
|---|---|
| VM4 / Joomla 5 | plg_vmmailinvoicestudio_vm48_template_pack_v1.0.zip |
| VM5 / Joomla 6 | plg_vmmailinvoicestudio_template_pack_v1.0.zip |
The four designs are Monochrome Professional, Blue Professional, Minimal Signature and Pink & Teal. Each supports HTML email and invoice layouts. Palettes are fixed. Minimal Signature uses a white layout, fine grey item rules, a compact right-aligned invoice heading and a narrow right-aligned totals block. It adds no handwritten or digital signature.
The pack number identifies a separate product; its release version identifies maintenance updates. A future Pack 2 can be a separate plugin installed alongside Pack 1.
Optional example pack
The example plugin is named Studio Design – Example Pack and adds Editorial — Studio Example Pack to the selectors. It is not installed with the core package.
| Edition | Example ZIP |
|---|---|
| VM4 / Joomla 5 | plg_vmstudiodesign_studioexample_vm48_v1.0.0.zip |
| VM5 / Joomla 6 | plg_vmstudiodesign_studioexample_v1.0.0.zip |
If a pack is disabled or removed
Classic and Modern remain available. Studio preserves the saved pack selection, but uses Modern for new emails or Classic for new invoices while the pack is unavailable. Re-enabling a compatible pack restores that selection unless you saved a different design. A pack that fails to load or render can also trigger the bundled fallback.
9. Updates and download keys
Use updates for your installed edition. The VM4/Joomla 5 and VM5/Joomla 6 editions have separate package filenames and update feeds.
- For the core download key, open System → Manage → Plugins → Installer – VM Mail & Invoice Studio Updates.
- Enter the key supplied with your purchase, save and keep the installer plugin enabled. Alternatively, use the core update site’s Download Key field in Joomla.
The core uses Joomla’s update system with the matching edition’s published update service. Design packs do not register Joomla update sites. To update a purchased pack, download its matching ZIP from your shop account and upload it through System → Install → Extensions over the existing plugin. You do not enter a pack update key in Joomla Update Sites. Installing the current core or pack removes previous Studio design-pack update associations.
Add-ons & News
The bottom of Studio displays the published news article as a banner and reads the article’s hidden JSON for edition-specific add-on notices. A notice can show a pack available to purchase, an available update, an up-to-date installed version or a requirement for a newer Studio core. Installed versions are checked even when a design plugin is disabled. Notices link to the shop; they do not purchase or install anything.
Article content is cached for up to one hour. To fetch an edit immediately, click Refresh news at the bottom of Studio. The button requires permission to configure Studio. A temporarily unavailable article does not prevent designing or sending documents.
In Studio’s Options → Add-ons & News, administrators can disable notices or set the public HTTPS news article URL. Normal article content supplies the banner; a single hidden pre block with ID vmstudio-data supplies the JSON. Edit visible article text to change the banner and JSON to change version notices and shop links. Safe inline formatting and the supported card/grid classes are preserved; external scripts and stylesheets are not imported. Light cards retain readable dark text in dark admin themes.
Download keys control protected update downloads. Installed designs have no runtime licence lock: an expired update entitlement does not switch off invoice or email styling.
10. Troubleshooting
| Problem | What to check |
|---|---|
| Preview is styled, but real documents are not | Enable the relevant document design and Save. Apply Studio overrides to the template selected in VirtueMart. Enable VirtueMart layout overrides. For emails, confirm HTML format is enabled. |
| An invoice still shows an old colour or design | Check whether it is an archived PDF. A status change on an existing order may reuse it. Test an invoice first generated after the settings were saved. |
| Enable this design resets to No | Use the Save button inside Studio and check for a success or error message. Reload to confirm persistence. Install the current build for your edition, which includes the saved-settings/cache fixes. |
| The selected design is marked unavailable | Install/enable its matching design-pack plugin, check compatibility and set Access to Public. Or choose Classic or Modern and Save. |
| Admin preview uses a pack but shopper documents do not | Check the pack’s Access level. Restricted plugin access can make it visible to administrators but unavailable to shopper requests. Also verify the document type is supported. |
| PDF contains Ajdovš?ina or missing characters | Use the current build and generate a new PDF. Check the customer/vendor source text contains the correct characters. Studio replaces standard PDF fonts with its bundled Unicode font; a custom font configured in VirtueMart must also contain the characters you need. |
| The logo appears twice | Keep the VirtueMart letterhead logo and clear Studio’s Additional brand logo if a second body logo is not wanted. |
| Studio reports an override conflict | Review the existing invoice/email overrides in the selected site template. Studio will not overwrite third-party or modified files. Have a developer reconcile the customizations. |
| No invoice is generated | Check VirtueMart’s invoice-generation statuses and PDF setup. Studio does not decide when an invoice is issued. Try Sample PDF to check the PDF engine separately. |
| Browser preview and PDF have different spacing | PDFs use TCPDF rather than the browser’s layout engine. Check Sample PDF and a real newly generated invoice, especially with long product options, custom fields and vendor letterhead. |
| Article edits do not appear in the banner | Click Refresh news to clear Studio’s one-hour article cache. Check the configured article URL and that the article is published with Public access. |
| The banner appears but add-on notices do not | Check that the article retains exactly one hidden pre block with ID vmstudio-data, containing valid JSON with schema 1, the matching vm4/vm5 edition, plugin element, release version, minimum core version and HTTPS shop URL. Use the HTML/source editor so the JSON is not altered. |
| An update download fails | For a core update, check the edition, download key, entitlement, permitted domain and published update service. For a design pack, use your shop account to download the correct ZIP and install it manually. |
When reporting an issue, include Joomla, VirtueMart, PHP and Studio versions; the selected design; whether it occurs in preview, email or PDF; and whether the PDF was newly generated. Include the exact error message. Remove customer details and download keys from screenshots.
11. Disable or uninstall
- Disable one document design: set Enable this design to No in Order email or Invoice and Save. Future rendering for that document type uses the native VirtueMart layout.
- Remove Studio from a site template: click Remove Studio overrides for that template. Only unchanged Studio-owned wrappers are removed; modified or third-party files are preserved.
- Remove an optional pack: disable or uninstall its plugin. Choose a bundled design first if you want to control the replacement explicitly.
- Uninstall Studio: use Joomla’s extension manager to uninstall the Studio package. Review any message about preserved modified overrides.
Disabling or removing Studio does not rewrite archived invoices or modify the original VirtueMart implementation files.