Documents

Creating documents in Shopware

The document creation takes place within the order under the tab Documents. Further information can be found here: Orders

How to create an invoice

An invoice can be quickly created using Shopware’s standard document functionality in the basic settings. First click “Add entry” and fill out the respective fields. After clicking “Save”, the new document will be automatically assigned a consecutive number from the defined number range.

How to create a notice of delivery

You can create a notice of delivery following the same method used for creating an invoice. For the notice of delivery, a consecutive number is automatically assigned from the same number range as for the invoice.

How to create a notice of cancellation

By default, notices of cancellation are not assigned a reference number. If you have to create a notice of cancellation, you go into the details of the individual order ("Customers > Orders > Documents") and enter the invoice number in the field Invoice number. The PDF document will then be assigned a cancellation number that refers to the original invoice.

Please keep in mind that partial cancellations in the standard version of Shopware are not supported! If you wish to create partial cancellations, you can do so using the Shopware ERP powered by Pickware plugin. Within this plugin, a notice of cancellation will be assigned a consecutive number from the number range defined in the plugin itself. Further on, the invoice number can also be specified with a reference number.

How to create a credit

When creating a credit memo, the document will also be assigned a consecutive number from the number range.

Tips & tricks

Documents can be deleted in Shopware, but beforehand you should make sure it is ok to delete the document by consulting your law expert. Before the document is deleted, you get a popup, asking you if you really want to delete the document irretrievably. The right to delete documents can be configured by granting or denying the deleteDocument privilege for the order resource in the user administration.

If you are using the Shopware ERP powered by Pickware plugin, you can use the function, Reset settings, to make adjustments to an invoice or cancellation after it has already been created. The original is neither edited nor deleted. Rather, it is created again with a consecutive number referring to the original invoice.

Further information on how to define the number range for your invoices can be found here: Number ranges

Configuring PDF documents

Overview

With the standard version of Shopware, you can easily create and adapt individual PDF documents to meet your needs. The module can be found under “Configuration > Basic settings > Shop settings > PDF document creation” in your Shopware backend.

The PDF module is divided into 3 separate areas. In the middle column, you will find an overview of all created PDF documents (1). In the upper-right portion of the window, you can define the basic data, settings and template of the document (2). In the lower-right portion of the column, you can access and change all relevant elements of the PDF document (3).

Creating or adjusting a PDF document

Click Add entry (1) to manually create a new document. Click the pen icon (2) to open the details column, where you can make adjustments to the basic data, template and elements of that particular PDF document. 

Details

• (1) Name: Name of the document
• (2) Number range: Specifies the number range used for this document.
• (3) Template: Name of the template in the template folder /_default/documents/
• (4) Spacing: Distance from the left, right and top of the document (measured in mm).
• (5) Items per page: Number of individual items listed per page.
• (6) Pagination: PDF document is assigned consecutive page numbers (Yes/No).
• (7) Preview: Use this button to generate a preview of the PDF.
• (8) View structure: Displays a schematic view of the document’s structure

The "(6) pagination" does only refer to the preview and not to the generation of the document.

 

Elements

In the overview, you will find all elements available within your document structure. Use the dropdown field (1) to select an element.

After selecting an element, you can adjust its content (2). Below the content field, you will find a style field for defining the element’s CSS properties (3).

By clicking the button “Use the config. for all forms” (1), the system applies the changes you’ve made to all other document types. Click the “Save” button to confirm all changes.

Do not drag and drop elements into the editor. Always use the editor function to insert and edit an image. 

Customise PDF documents

Here, we describe the basic structure of the PDF documents that you can easier understand how they work and extend each other to let you individualise them easier.

Find template files

Before you search the template files, check in the shop settings first which "Document template" is set. Depending on this setting, you have to search the document files in that particular template folder. If "Bare" or "Responsive" is set, first, choose your own theme, so you can extend the files from the default ones and remain update safe.

The single files are located in the theme folder:

• Invoice: themes/frontend/MyTheme/documents/index.tpl
• Credit note: themes/frontend/MyTheme/documents/index_gs.tpl
• Delivery note: themes/frontend/MyTheme/documents/index_ls.tpl
• Cancellation invoice: themes/frontend/MyTheme/documents/index_sr.tpl

Inheritance of the document files

The invoice (index.tpl) is the main template, this generated the invoice while all the others extend from this file and overwrite their (not) needed elements which are (not) needed. If you want to change e.g. the delivery note, first look in the delivery note template, because changes in the index.tpl will appear in all other documents too, which you may not want.

Individualise documents

In the article Making changes in the template we describe how customisation of your template works.

When you want to individualise your templates, this works the same as in other templates, the documents work with Smarty and you can use the known workflow: Templates from the Bare theme are the default, never change these files because at updating Shopware, they might be overwritten! Instead, change your document template in the shop settings to your own theme. If you made no changes, the theme will fall back to the default. After you created the necessary files in your theme's document folder, you can customise them.

Example: You want to change the logo in your invoice: Create in /themes/frontend/YOURTHEME/documents a file named index.tpl and make your changes there. Your theme now uses your customised file, which extends from the default one.

The document templates are not completely covered in smarty blocks, so you can use the extension only for changes you make in smarty blocks.

If you make changes in areas that are not in a smarty block, you need to copy the whole file and make your change there.

Available data

Here we list the available data which you can use in the documents. The easiest way to find your needed variable is to print the arrays using {$VARIABLE|print_r} and search for your needed variable.

Variable	Description
{$Containers}	Document settings which you made in the backend
{$Document}	Data of the document itself
{$Order}	Data of your order
{$position}	Data of each position in these order
{$User}	customer data

Display free text field on documents

Additional information can be easily added in Shopware using the free text fields. To show those in the documents as well, you just have to do some little changes in your own theme.

Create free text fields

First, you have to create a free text field for your product. As an example, we define the field attr5 with the field type "Simple text - VARCHAR(500)" for the table s_articles_attributes. As the label, we use Content for this example. With a click on save, the new free text field is created.

From now on you can fill this field in every product's core data mask which can be filled specifically for every product. In this example, we entered three sorts of tea with the respective content.

Edit document template

For product-free-text-fields

Now you want to show the free text field on your documents. In order to do this, please open the template file which creates your document. By default, this is the index.tpl for the invoice and index_ls.tpl for the delivery note. The default document templates can be found in the folder themes/frontend/Bare/documents. If you want to change the documents, you should copy the .tpl file into your own folder and edit it there. Changes in the default folder are not secure for updates. How to create your own theme and basics about theme changes can be found at our Dev Docs. The individual document theme should also be selected at configuration > basic settings > shop settings > shops for your shop.

In the template file you can now edit the block with the name 'document_index_table_name, here you replace the else-area of the if-selection with this:

{else}
        {s name="DocumentIndexPositionNameDefault"}{$position.name|nl2br|wordwrap:65:"
\n"}{/s}<br>
		{$position.attr5}
{/if}

This creates a line break behind the product name and displays the free text field value, what looks like this:

For order-free-text-fields

Maybe you do not want to display a product-related free text field, but a global order free text field. This can be created, just like explained before, for the table s_order_attributes.

You could add the following variable to a fitting block. Here is an example of a free text field with the name attribute6:

{$Order._order.attributes.attribute6}