Abstract
User documentation for VM Invoices & Book it! Invoice Joomla component. Installation and usage instructions.
Table of Contents
Table of Contents
VM Invoices is a component for Joomla CMS / VirtueMart e-store, that generates PDF invoices for VirtueMart purchases. VM invoices offers a list of orders, where you can generate PDF invoice by one click and download it or send by client by email. Invoices can be sent automatically to shopper emails. An integration with VirtueMart frontend is also possible, so users can download the invoices using the frontend order list.
Core VM Invoices features include:
Automatically generates PDF invoices and delivery notes for VirtueMart customers
Can send invoices and delivery notes to customers' emails
Manual or fully automated operation
Configurable invoice numbering with prefixes.
Configurable order status, when invoice is generated and sent.
Adjustable invoice appearance with custom fields and whole templates.
Editing and creating new orders.
Table of Contents
You can obtain VirtueMart Invoices Generator by purchasing and downloading from ARTIO webpage www.artio.net. Instalation is simple and easy.
To continue following this instalation tutorial, first make sure that:
you have a running and functional Joomla site
you have installed and functional VirtueMart extension.
check the write permissions on Joomla directories, see
log-in to your Joomla! backend with Super Administrator privileges
go to
select downloaded zip file and confirm button upload&install
follow the installer instructions and check for any error
VirtueMart Invoices Generator installation is fully automated in most cases. It will install:
the main VM Invoices component (in
components/com_vminvoiceandadministrator/components/com_vminvoice)
language files (in
languages)database tables (#__vminvoice_config, #__vminvoice_mailsended, #__vminvoice_additional_field)
VM Invoice Autorun system plugin - this sends e-mails in Automatic Mode.
After uninstall, component database (configuratiom, invoice numbers) is kept. You can uninstall and install component without losing that information. Howerver, if you want clear install, remove database tables prefixed with [JoomlaPrefix]_vminvoice_.
Table of Contents
To manage VM Invoices, you need to be loged in Joomla's backend (adminstration). Then navigate to
There are 9 tabs available. First one named is overview with shorcuts to component functions. Next three , and are used for various component settings. is for set yours bank and company details, PDF header, PDF footer. is main page with orders and invoices list, where you can send and print invoices and edit orders. is shortcut for creating new order. section provides informaton about new component version and allows you to automatically or manually upgrade component. provies shortcuts for sources of help and support for component.
This tab does include several options that control how the VM Invoices works as well as buttons to initiate related actions. Any change should be saved by clicking the button located in the right-top corner of the page.
- Operation Mode
You can choose between automatic and manualy sending option.
If you choose the manual option, no emails will be sent or invoices generated unless you launch the particular action.
Note that in autimatic mode, sent are only e-mails for orders modified in last 24 hours.
If you use automatic option, you need to do some more configuration - please read Chaper 4 - 1.
- Required Order Status
(only applies to automatic mode)
The order status, that causes PDF invoice to be generated and sent to client. You can select more statuses by clicking with CTRL.
Also, it affects own invocie numbers assigning (New invoice number will be assigned only if order is in desired status)
- Mailing Interval
(only applies to automatic mode)
This option allows you to set time interval, when emails with newly generated invoices are being sent. (If using cron, this interval should be same or longer than the one configured in your cron script. See more in Chapter 4 - 1.1.)
- Change Currency Sign
If your currency does not generate properly (e.g. when using ¬ sign) you can use this substituon.
Syntax is: original currency string 1 | new currency string 1[, original currency string 2 | new currency string 2, ...]
As a separator between character and name use "|" (pipe) and separator between whole sub.word use "," (comma)
Example : ¬|EUR,$|USD
- Date Pattern
Date pattern format for date in invoice can be e.g. (m-d-Y or d.m.Y); use the PHP syntax for date() function. Also you can use syntax of PHP strftime() function. This syntax gives date ability to be translated based on invoice language. However, be sure you check result is valid for all languages your invocies are avilable in, because behavior of function can vary on different servers. If date your language is not supported, ask your server provider to install new "locale" for your specific language. Also be aware that certian characters (like %e) are not available on Windows servers or behave differently.
- Cache PDF
Invoice PDFs are stored in Joomla! tmp folder in subfolder called "VM Invoice" (in your language) and subfolders divided by year and month. If order was not changed and also was not changed any PDF appearance config, used is previously generated PDF instead of creating new one. If you disable this feature, invoices are created newly every time they are needed. Enabling this feature speeds up performance and also enables you to pre-generate multiple invoices in batch screen.
- Use HTML Tidy (if available)
PHP Tidy library is used to fix and sanitise HTML code before using by PDF generating library.
- Image Paths
Controls how image paths are generated on invoice HTML. Since there are many various server settings, this feature enables more settings to work on your server.
Absolute: http://www.example.com/joomla_site/...path_to_image
Relative to domain root: joomla_site/...path_to_image
Relative to Joomla! root: ...path_to_image
Server path: var/www/html/joomla_site/...path_to_image or c:/wamp/www/joomla_site/...path_to_image
- Debug Mode
When switched on, no PDF will be created, you will only see raw HTML output that is used to create PDF. You can also see any PHP warnings. If you are having issues with creating PDF, try enabling this feature.
- Default Vendor
Default vendor for newly created orders from VM Invoice.
- Default Currency
Default currency for newly created orders from VM Invoice.
- Use Customer Language
If you specify yes, invoice will be generated in customer's default site language. If user have no language specified or selected No, invoices are generated in site default language.
- PDF Font
List of fonts available for PDF generation.
Non-latin languages may use UTF-8 version of the font. The generated PDF however are bigger in size then.
You can upload new .ttf fonts (unicode). Fonts are uploaded into administrator/components/com_vminvoice/libraries/tcpdf/fonts. Program will try to install new *.ttf fonts for using in PDF generation. You will see message "Font was installed" after process. Alternatively, you can upload .php, .z and .ctg.z font files.
- Font size
Here you can regulate overall PDF font size.
- Margins
PDF margins in milimeters.
- Show Contact
Wheater show {contact} tag in template.
- Show Logo
Wheater show {log} tag with vendor logo in template.
- Logo Width
Is showing vendor logo, you can specify it's size in cm. Remember to also adjust template cell to fit bigger or smaller logo (because cells are not expanded automatically)
- Show Signature
Wheater show {signature} tag with ARTIO signature.
- Show Pagination
Wheater show {pagination} tag in template footer. If you place {pagination} tag into header, it will be shown on one page invoices even if you select 'When more pages'.
- Information Fields Position
Where to display (or not) {extra_fields} tag on template. Content is defined in Fields configuration.
- Fields Background Color
Background color of {extra_fields} tag
- Background Image
Background image source.
- Image Position
Background image aligment.
- Image Offset From Left
Optional left offset of image. Use cm. Page width is 210 cm.
- Image Offset From Top
Optional top offset of image. Use cm. Page width is 270 cm.
- Stretch to Page
If stretch background image to page.
- Use Mailer Info From
Here you can define sender E-mail source.
- Send Mail To
Here you can configure recepient of invoice e-mail.
Shopper and shopkeeper - Invoice is sent to customer and as copy to e-mail defined in Use Mailer Info From.
Shopper only - Invoice is sent only to customer.
Shopkeeper only - Invoice is sent only to e-mail defined in Use Mailer Info From.
- Sender Email
E-mail displayed as sender. Only used when Use Mailer Info From is set to VM Invoice Configuration.
- Sender Name
Name of sender displayed in e-mail. Only iused when Use Mailer Info From is set to VM Invoice Configuration.
E-mail subject and body are defined in Invoice E-mail and Delivery Note E-mail configuration sections.
- Invoice Number
You can choose between order or own numbering.
If using order numbering, invoice number will be always same as order id created by VirtueMart. There is no need to wait before order enters required state to generate invoice. (However, state still applies for invoice sending).
If using own numbering, invoice numbers are created sequentially, independently on order id. New invoice numbers are automatically assigned if order enters Required Order Status defined in General Config. Also, configuration option Starting Order For Numbering applies to it.
- Starting Order For Numbering
(only applies to own numbering) Minimal order id for autimatic invoice number assignation. If you are importing old database and don't want to create invoices for old orders, set starting order Id here. If you old orders have already numbers assigned, you can always delete their numbers by "delete created invoices" batch action.
- Numbering prefix
(only applies to own numbering) Prefix before invoice number. Can be for example last two digits of year. Setting only affect newly created invoice numbers, for old invoice numbers edit prefix manually or delete invoices and create them again.
- Start Invoice Number
(only applies to own numbering) Initial invoice number to start automatic numbering from.
- Allow invoice number prefix editing
(only applies to own numbering) If yes, allows manual changing of invoice prefix.
- Address Shown
Whater show {billing_address} and {shipping_address} (or both) in template.
- Show Address Label
Wheater prepend "Billing Address" and "Shipping Address" label to addresses.
- Address Format
Specifies address formatting for {billing_address} and {shipping_address} tags.
- Show Invoice Number
Whater show {invoice_number} tag in template.
- Show Customer Number / ID
Whater show {customer_number} tag in template.
- Show shopper group
Whater show {shopper_group} tag in template.
- Show Date Label
Whater display {invoice_date_cpt} tag.
- Default Invoice Date
Date that will be defaultly assigned as invoice date. Note that after invoice number is created, Invoice date can be changed only manually.
- Show Taxable Payment Date
Whater show {taxable_payment_date} tag in template.
- Taxable Payment Dat
Date used as Taxable Payment Date.
- Show Maturity Date
Whater show {maturity_date} tag in template.
- Maturity (days)
Day offset from Taxable Payment Date.
- Show Shipping Date
Whater show {shipping_date} tag in template. Shipping date is last date of changing order status to "Shipped".
- Show Payment Type
Whater show {payment_type} tag in template.
- Show Variable Symbol
Whater show {variable_symbol} tag in template.
- Variable Symbol
What number will be used as variable symbol.
- Show Customer Note
Whater show {customer_note} tag in template.
- Show Finnish index number
Whater show {finnish_index_number} tag (number used only in Finland) in template.
If is any column hidden in this config section, it is also hidden from invoice template. You don't need to delete that column directly in template.
- Repeat Table Header
Whater repeat table header on every page. Note that for this setting work, {items} tag must be placed outside any HTML table.
- Show Quantity Unit
Wheater show "pcs" after product quantity. Hides {qty_unit} tag.
- Show Product SKU
Wheater show product SKU column. Hides {sku} tag and associated column.
- Show Product Attributes
Wheater show product attributes. Hides {attributes} tag.
- Show Price Excl. Tax
Wheater show column with products verall price before tax. It hides {price_notax} tag and associated column.
- Show Tax Rate
Wheater show column with product % tax rate . It hides {tax_rate} tag and associated column.
- Tax Rate Tolerance
Tax rate is not stored directly in orders table. Because of that, it must be "guessed" on invocies by difference between gross and net and using available tax rates in VirtueMart. That guess can be sometimes inaccurate, so this setting defines offset between computed and real tax rate to be properly assigned. Note that other calculations can be still little misfitting because of that, that is due to VirtueMart storing of prices.
- Product Tax And Subtotal (only in VM 1.x.x)
VirtueMart 1.x.x stores ordered product prices only as net and gross. Due to Tax Rate Tolerance can be assigned tax misfitting on some point.
Taken from VirtueMart (default): Product gross price is taken from order table and tax amount is simply difference between gross and net.
Calculated from base and VAT: Product tax amount and gross price will be calculated from net * assigned tax rate. This override gross price stored in order. NOTE: This affect only ordered products subtotals, NOT order total. Order total stays always the same.
- Show Tax Value
Wheater show column with products tax amount . It hides {tax_price} tag and associated column.
- Show Discount (only in VM 2.x.x)
Wheater show column with products discount. It hides {discount} tag and associated column.
- Always Show Currency Unit
By default, currency is shown only at subtotal column. When you enable it, currency is shown at all prices.
- Show Shipping Details
If enabled, at shipping row is shown also shipping carrier and rate description. It is inserted on place of {attributes} tag.
- Prices Rounding
Manner of prices rounding on invoices.
- Show Tax Summary
Show overview with tax rates and theor amounts. Requied in EU countries.
- Show Tax Summary Label
Show "Tax summary" label before tax summary.
- Show Subtotal
Show subtotal line. Subtotal line constists of net, tax and gross amounts summed up. Shipping costs are counted in. In VM 2.x.x is counted in also payment costs.
- Extended Coupon Discount
If enabled, coupon discount is splitted to row similat to tax summary. You should specify Coupon VAT also. If disabled, coupon discount is displayed as single value.
- Coupon VAT (%)
Is using Extended Coupon Discount, specify VAT applied on copon. Note that coupon value is considered as with tax, so coupon tax is substracted from it.
- Extended Total Line
If enabled, total line contains also overall net price, overall tax, tax rate (only if order uses single tax for all items), and overall . If disabled, total line contains only overall order price.
- Mail Subject
Subject of e-mail with invoice.
- Mail Body
Body of e-mail with invoice. You can use special replacable fields in it:
[%orderId%] - order Id.
[%invoiceId%] - invoice number. Can be different than Order id if using Own numbering.
[%firstName%] - customer billing address first name
[%secondName%] or [%lastName%] - customer billing address last name
From version 1.7 you can define exact layout of invoices and delivery notes. Layout is defined as HTML document. It is divided into Header, Body and Footer separated by pagebreak lines. Header and Footer are displayd on top and bottom of every page. You can always turn your template to default by clicking on Restore template back to original button.
Templates uses {xxx} aliases/tags, which are replaced by proper entity.
Fields:
You can see list of available tags by clicking on Possible replacement fields link at bottom.
{ * _cpt} are captions and are usually replaced by some text contants.
Configuration options still applies for certain tags. For example, when you set "Show Shopper Group" to "No", tags {shopper_group_cpt} and {shopper_group} are not displayed.
General tips:
When you copy & paste something, Joomla! editor (at least TinyMCE) usually copies also format. Usually it wraps content to with specified font and size. Switch to HTML view and clean content or paste directly in HTML mode.
When you save template, switch back to WYSIWIG mode. In some editors (tested with TinyMCE), Joomla doesn't save changed content when is in HTML mode.
Always use % units. Especially font sizes and table widths. It is because PDF paper has different unit measures. Also, it allows you to globaly change font size using Font Size config setting.
TCPDF cannot handle all HTML code and special CSS. Use only basic.
{items} tag s replaced by table of ordered products. Table has always 100% width. (If you want to make it smaller, wrap it to another element with smaller width).
Table header and product row are defined separately at Table Header and Table Row fields. Each fields must have equal number of columns; but "colspan" property is taken into account.
Column widths. If you want to redefine column widths:
ALWAYS use percent widths.
Edit widths only in Table Header. Widths defined in Table row are not taken into account.
You don't have to define width at all columns, but it is recomanded.
Overall sum don't have to make 100%. If fields sum make 90% or 120%, they are recomputed afterwards to do 100%.
Table footer rows (shipping, payment, subtotal, tax summary, total) fields are made dynamically from item row by replacing tags by apripriate values.
Some adjustments are done to HTML code before making template:
If some tag is empty (due to configuration or customer
leaves it blank, like for example {billing_address_2}), it is
removed also with preceding
and following ":". This is
useful for removing blank lines and blank captions: values
pairs.
If some column is removed due to Invoice Items configuration (for example Tax Rate) and column does not contain any other content, whole column is removed from table. Other columns widths are adjusted to fill empty space.
If some text in template before follows this pattern
"something: something" and it is repeated more times with
s between them, it is converted into
