Designing templates using the DocumentBuilder editor

Guided tours available

The guided tours Documentbuilder-Basic settings and DocumentBuilder-Editor are available in the Setup » Documents » DocumentBuilder menu. The tours show you the most important functions step by step.
You can find the tours in the bottom left corner of the Setup » Documents » DocumentBuilder menu. Click on rocket_launch Guided tours to start the tour.

Use the DocumentBuilder editor to design your template structure and to add content. You do this using the Editor’s various widgets, which you drag and drop into the template and then configure to suit your needs.

Open a template and click on edit to open the Editor screen:

EN orders docbuilder editor 640 324

  • Widgets: This is where you select the widgets that you want to drag into the template. The first three widgets are structure widgets. Use these to create your template structure. Below them are the content widgets. Use these to create your template content.
    Note: Among the content widgets is the order-items widget, a combination of structure widget and content widget that serves to dynamically list order items.

  • Toolbar: Click on save to save changes, on visibility to preview the template, and on settings to open the output settings for the template.

  • Main window: This is where you edit the template that you have selected. The image above shows a template for which the content structure has already been created. Click on the explanation below for a brief description of how the structure and content were created in the DocumentBuilder editor.

Explanation of editor screen image above

  • The order items table was created using the order-items widget.

  • The table structures outside the order item table were created using structure widgets.

  • The names of the fields were created using text widgets.

  • The variables (black background) were added using text widgets.

  • The addresses were added using address widgets.

  • The fields with a grey and white checked background indicate that the respective field is empty and can accommodate a widget.

  • The pink and white lines indicate that a restriction has been set for the text widget located here.

1. Inserting widgets into a template

To insert a widget into a template, proceed as follows:

  1. Open the Setup » Documents » DocumentBuilder menu.

  2. Click on Search (search) to list the existing templates.

  3. Click on the template you want to edit.
    → The template opens.

  4. Click on Open Editor (edit).
    → The editor opens and the widgets are loaded.

  5. Click on the widget you want to insert and drag and drop it into a checked field.

  6. Click on settings to carry out the settings. Refer to the sub-chapter Available Widgets for detailed information on the individual widgets.

  7. Save (save) the settings.

2. Available widgets

DocumentBuilder contains structure widgets for designing the template structure and content widgets for creating the template content. The following sub-chapters provide detailed information on how to use the various widgets.

2.1. Structure widgets

Use the structure widgets listed below to create the information fields in a DocumentBuilder template.

Click on one of the links or scroll through Table 1. Structure widgets in DocumentBuilder for detailed information on the individual structure widgets.

Note: You can create more than three columns by inserting further widgets into an existing widget.

Table 1. Structure widgets in DocumentBuilder
Widget Explanation

One-column layout

Creates a one-column structure in which to display content.

Settings:
Click on settings to open the settings. This is where you can define the width of the border, the padding or the margin in mm. To do this, select (done) the respective setting and use the drop-down list to set the size in mm. use the Colour setting to select the colour for the widget background and for the font used in the widget.

Inserting further widgets:
You can drag and drop further widgets into a structure widget. For more information on this, refer to the section Inserting further widgets into an existing structure widget.

Restrictions:
Use the restrictions feature to specify that the content of the widget be displayed in a document only if the corresponding order meets the conditions defined in the restriction. For more information on using widget restrictions, see the section Widget restrictions.

Click on Delete widget (delete) to remove the widget. Click on Close settings (close) to close the settings.

Two-column layout

Creates a two-column structure in which to display content.

Settings:
Click on settings to open the settings. Use the Orientation setting to define whether the widget should have a column structure (vertical) or a row structure (horizontal). Use the Layout setting to set the ratio of the two columns to each other. The following ratio options are available:

  • 50% / 50% (standard)

  • 30% / 70%

  • 70% / 30%

  • Custom layout (use this setting to set your own ratio by defining the percentage of the left-hand column to the right-hand column)

You can also define the width of the Border, the Padding and Margin in mm. Select (done) the respective setting and choose the desired size in mm from the drop-down list.

Inserting further widgets:
You can drag and drop further widgets into a structure widget. For more information on this, refer to the section Inserting further widgets into an existing structure widget.

Restrictions:
Use the restrictions feature to specify that the content of the widget be displayed in a document only if the corresponding order meets the conditions defined in the restriction. For more information on using widget restrictions, see the section Widget restrictions.

Click on Delete widget (delete) to remove the widget. Click on Close settings (close) to close the settings.

Three-column layout

Creates a three-column structure in which to display content.

Settings:
Click on settings to open the settings. Here you can first select the Orientation (horizontal/vertical). You can also define the width of the Border, the Padding and Margin in mm. Select (done) the respective setting and choose the desired size in mm from the drop-down list.

Inserting further widgets:
You can drag and drop further widgets into a structure widget. For more information on this, refer to the section Inserting further widgets into an existing structure widget.

Restrictions:
Use the restrictions feature to specify that the content of the widget be displayed in a document only if the corresponding order meets the conditions defined in the restriction. For more information on using widget restrictions, see the section Widget restrictions.

Click on Delete widget (delete) to remove the widget. Click on Close settings (close) to close the settings.

2.1.1. Inserting further widgets into an existing structure widget

After you add a structure widget to a DocumentBuilder template, you have the following two options:

  • Insert content widgets into the structure widget (only one content widget per column possible).

  • Insert further structure widgets to create the additional information fields you need (multiple further structure widgets per column possible).

Click here for instructions on creating a structure made of multiple widgets:
EN orders docbuilder.multiple widgets 640 178

To create the four-column structure in the image above, proceed as follows:

  1. Drag one two-column widget into the template.

  2. Open the widget settings (settings)
    → The widget settings open in the column on the right

  3. Use the Layout dropdown to change the ratio of the columns to each other from 50:50 (default) to 30:70

  4. Close the widget settings
    Note: You must close the widget settings to continue editing the template

  5. One by one, drag four three-column widgets into the right-hand column of the original two-column widget
    Note: When you drag in a further widget, blue lines light up as you move across the original widget. These indicate the available drop zones for the further widget. Use them to correctly place the further widgets.

2.1.2. Identifying the correct settings icons in structures created using multiple widgets

To adjust the settings in a multi-widget structure, you need to identify the settings icons (settings) belonging to the individual widgets. For this, note the following rules:

  1. The settings icon (settings) for the original widget appears in the top right corner of the widget structure.

  2. The settings icon (settings) for each further widget inserted into the original widget appears in the middle of the respective further widget.

  3. If you add more widgets to a further one-column widget or to the central column of a further three-column widget, the following applies:
    The settings icons (settings) will all appear in the middle, as in rule 2 above, but in sequential order from left to right based on the order in which the further widgets were inserted.

Hover over a settings icon (settings) to identify the corresponding widget

If you hover over a settings icon (settings) in a widget, a tooltip will appear indicating the widget type that the settings icon belongs to.

2.2. Content widgets

Use the content widgets listed below to create the content for a template. Click on one of the listed links or scroll through Table 2 for detailed information on the individual content widgets.

Table 2. Content widgets in DocumentBuilder

Widget

Explanation

Image

Use this widget to …​

  • …​upload an image file for your template (e.g. to display your company logo in documents), or…​

  • …​link a template with the image stored in the Item UI for an item or a variation (e.g. to display images of the ordered items in order confirmations).
    Important: This will only function if you insert the image widget into an order items widget.

Settings:
Click on settings to open the settings. In the Image type setting, select one of the following options:

  • General: If you select this option, the line*Image source* appears. Here, click on the three dots to upload an image file or select from previously uploaded image files.

  • Items: If there is an image saved in the Item UI for a particular item, this option creates a link to that image. If you have multiple images saved for an item, use the setting Position number of the item image to select the image you want to link to.
    Example: If you select position "0", for example, the image that has been assigned "Position 0" in the Item UI will be displayed.

  • Variation: If there is an image saved in the Item UI for a particular variation of an item, this option creates a link to that image.

Use the other settings to set the height and width of the image in px, and to set the Rotation and the Alignment for the image.

Restrictions:
Use the restrictions feature to specify that the content of the image widget be displayed in a document only if the corresponding order meets the conditions defined in the restriction. For more information on using widget restrictions, see the section Widget restrictions.

Click on Delete widget (delete) to remove the widget. Click on Close settings (close) to close the settings.

Address

Use this widget to display address fields.

Settings:
Click on settings to open the settings.
From the first dropdown list, select the Address type that you require. Use the other settings to set the Font and the Alignment for the address.
Note: You set the layout of the different addresses in the menu Setup » CRM » Address layout.

Restrictions:
Use the restrictions feature to specify that the content of the image widget be displayed in a document only if the corresponding order meets the conditions defined in the restriction. For more information on using widget restrictions, see the section Widget restrictions.

Click on Delete widget (delete) to remove the widget. Click on Close settings (close) to close the settings.

Barcode

Use this widget to display barcodes.

Settings:
Click on settings to open the settings.

  • Barcode type: Choose whether the barcode/QR code applies to the order in general or to the item in an order item.

  • Barcode / QR code: Select the appropriate barcode/QR code from the dropdown list.

  • Use the additional settings to adjust the layout, rotation, height, width, and alignment of the barcode/QR code.

The following two checkboxes appear only if you select a Giro code or Swiss QR code from the Barcode / QR code dropdown-list:

  • Overwrite bank master data: Check this box if, for the specific Giro-Code/Swiss QR code, you want to overwrite the bank master data stored in the Setup » Settings menu.

  • Overwrite company master data: Check this box if, for the specific Giro code/Swiss QR code, you want to overwrite the company master data stored in the Setup » Settings menu.

Detailed explanation of the checkboxes Overwrite bank master data / Overwrite company master data:

To generate a Giro code/Swiss QR code in a document, the corresponding DocumentBuilder template pulls the required bank and company data directly from the data entered in the Setup » Settings menu and transfers this data into the Giro-Code/Swiss QR code.

In plentysytems, only one set of master bank / company data can be configured per system.

To generate Giro code/Swiss QR codes for a client (webshop) that has different bank / company data than that stored in the system, the template-transferred data needs to be automatically overwritten. This is what the checkboxes Overwrite bank master data and Overwrite company master data are for.

To overwrite the master bank / company data for a Giro code/Swiss QR code, proceed as follows:

  1. Activate the checkboxes Overwrite bank master data and/or Overwrite company master data.

  2. In the fields that appear, enter the data required for the Giro code/Swiss QR code.

  3. Save (save) the settings to automatically replace the master data pulled for the Giro code/Swiss QR code with the newly entered information.

  • Restrictions:
    Use the restrictions feature to specify that the content of the barcode widget be displayed in a document only if the corresponding order meets the conditions defined in the restriction. For more information on using widget restrictions, see the section Widget restrictions.

Click on Delete widget (delete) to remove the widget. Click on Close settings (close) to close the settings.

Text

Use this widget to enter text and add variables. You can also format the text you entered. To open the format settings for the text, simply select the text that you want to format.

Inserting variables:
Click on edit to open the list with the variables on the left side of the screen. Use the search function to find the variables or find the appropriate variables by expanding the individual areas (chevron_right). Click on the variable you want to insert. Enter additional text in the widget, if needed.

The manual page Using variables provides a list of the available variables, divided into categories.

Setting restrictions (in the old text widget):

The instructions below apply to the legacy restriction methodology used in the old text widget described here.

The other widgets, including the new text widget described below, use the updated restriction methodology, which enables you to create more precise restriction rules.

Click on settings to open the settings. If required, you can set a restriction for the text widget here. If you set a restriction, the content of the text widget will only appear in the document if the value selected in the restriction also exists in the corresponding order.
Note: Pink and white lines in a widget indicate that a restriction has been set for the widget.

Restrictions available for a text widget
Restriction Example of use

Payment methods restriction

If you select the payment method "Bank posting", the content of the text widget will only appear in a document if the payment method in the corresponding order is also "Bank posting".

Languages restriction

If you select the languages "German" and "English", the content of the text widget will only appear in a document if the language of the corresponding order is either German or English.

Referrer restriction

If you select the referrers "Amazon UK" and "Amazon USA", the content of the text widget will only appear in a document if the referrer of the corresponding order is either Amazon UK or Amazon USA.

Invoice countries restriction

If you select "Germany" as the invoice country, the content of the text widget will only appear in a document if the invoice country in the corresponding order is also Germany.

Delivery countries restriction

If you select "United Kingdom" as the country of delivery, the content of the text widget will only appear in a document if the country of delivery in the corresponding order is also United Kingdom.

Tex relevance restriction

If you select the payment status "EU export", the content of the text widget will only appear in a document if the value for tax relevance in the corresponding order is also "EU export".

Payment terms restriction

If you select the payment term "Payment due", the content of the text widget will only appear in a document if a value for "Payment due" exists in the corresponding order.

Payment status restriction

If you select the payment status "Unpaid", the content of the text widget will only appear in a document if the value for Payment status in the corresponding order is also “Unpaid”.

Variables restriction

If you add the variables “Coupon amount net” and “Currency” to a text widget, then select the restriction "Coupon amount net", the content of the text widget will only appear in a document if a value for “Coupon amount net” exists in the corresponding order.

Click on Delete widget (delete) to remove the widget. Click on Close settings (close) to close the settings.

Text (new)

This widget behaves just like the old text widget described above in all aspects – with one important exception: The restrictions. For all functions except the restrictions, please refer to the explanations above.

What is a restriction? You use the restrictions feature to specify that the content of the widget be displayed in a document only if the corresponding order meets the conditions defined in the restriction. For more information on using widget restrictions, see the section Widget restrictions.

Differences between the Text and Text (new) widgets:

Text:
The old text widget uses a legacy restriction methodology. This is explained in the above description of the old text widget.

Text (new):
The new text widget uses an updated restriction methodology that enables the creation of more precise rules. This is described in the section Widget restrictions.

Order items

Use this widget to define how order items should be displayed.

Settings:
Click on settings to open the settings.

Begin by selecting the Order item types from the drop-down list.

If necessary, you can then adjust the Outer spacing in mm, the Frame (header), the Inner spacing in mm (header), the Frame (cell), the Inner spacing in mm (cell) and the Width of the column in mm by ticking the setting (done).

Click on unfold_more to change the order of the columns. Click on Add new entry ( add) to add more columns. Click on Remove entry (delete) to delete columns from the overview.

Click on Delete widget (delete) to remove the widget. Click on Close settings (close) to close the settings.

Code

Use this widget to apply individual styles to a template (e.g. to show the quantities of order items in bold) and to implement more complex approaches to processing and displaying data.

Note: If you use the code widget in a template, the corresponding documents may take a little longer to generate.

Click on to open the list of variables on the left side of the screen. Use the search function to find individual variables or click on a variable category to display the corresponding lists (chevron_right). Click on the variable you want to insert. The variable is inserted at the point where you place the cursor.

Click here for code examples

Click on () to close the widget window.

Click on settings to open the settings.

Click on Delete widget (delete) to remove the widget. Click on Close settings (close) to close the settings.

Page break

Use this widget to set page breaks in your template. Simply drag the widget to where you want a page break to occur.
Note: You cannot use the page break widget inside the header or footer of a template.

There are no further settings for this widget.

Important: To see set page breaks in the preview, select the format PDF in the Show preview window. Page breaks are not visible in HTML format.

Click on Delete widget (delete) to remove the widget.
Changing the Document type setting in existing templates

Note that the range of available widgets can differ depending on the document type. In some cases, if you subsequently change the Document type setting in an existing template, not all of the originally selected widgets will be available for the newly set document type. If this occurs, an error message will appear.

3. Widget restrictions

Use a widget restriction to specify that the content of the respective widget will only appear in a document under certain conditions – for example, only if the associated order has a specific referrer or contains certain items.

3.1. Using widget restrictions

To set up a widget restriction, proceed as follows:

  1. Insert the required widget into the document. For instructions, refer to the section Inserting widgets into a template.

  2. Open the widget settings (settings).
    → The widget settings open in a column on the right.

  3. At the bottom of the right column, click on Restrictions.
    → The widget restrictions window will open.

    1. Option 1: To set the first condition, select a restriction type from the dropdown list.
      → Further settings for the restriction type will appear.

    2. Option 2 (not available for all document types): Select one of the preset restrictions via Add preset restriction (rule_folder) at the top right of the window. These are frequently used restrictions and restriction combinations that are pre-configured.
      Note: If you want to adjust the preset restriction, continue with step 4. Otherwise, jump to step 5.

  4. Perform the further settings. For details, refer to the sections Applying conditions in widget restrictions and Using operators in widget restrictions.

  5. Add additional conditions and sub-conditions as needed.

  6. Confirm the restrictions.

  7. Save (save) the settings.
    Note: The symbol settings with an exclamation mark in a widget indicates that a restriction has been applied to the widget:

EN Settings Orders Docbuilder widget with restrictions

3.1.1. Using conditions in a widget restriction

When you open the Widget restrictions window as described in Using widget restrictions and select the restriction type, the following settings will appear in the window:

EN Settings Orders Docbuilder conditions in widget
Explanation of the functions in the Widget restrictions window
Area Setting Explanation

1.

AND & OR Conditions (playlist_add)
Nested levels (library_add)
Add preset restriction (rule_folder)

Use these settings to add further restriction conditions and determine the relationships between them. You can also add preset restrictions (rule_folder).

For more details on the functions, refer to the section Using conditions and preset restrictions.

2

Restriction type

Use this setting to select the restriction type from the dropdown list. This determines which field in the order data is checked against the conditions set in the restriction.

3.

Operator

Use an operator to define how the value in the order data is compared with the value in the input field. For more details on available operators, refer to the section Using operators.

4.

Input field

Use this setting to enter or select the values for which the restriction will apply.

3.1.2. AND & OR, using conditions and preset restrictions

Use the settings explained below to add restriction conditions (material:playlist_add) or sub-conditions (material:library_add) to a widget restriction and define the relationships between them, and to add preset widget restrictions if appropriate.

Conditions in widget restrictions

Setting Explanation

Adding conditions and sub-conditions:

Condition (material:playlist_add)

Use a condition to define the criteria that an order must meet for the widget content to appear in the document. The first condition is pre-inserted and ready to set. Use material:playlist_add to add additional conditions.

Nested Level (material:library_add)

Use nested levels to create sub-conditions within a condition. This allows you to build complex hierarchies within conditions.

Determining the relationships between conditions:

AND

Select AND when an order must meet all linked conditions for the widget content to appear in the document.

OR

Select OR when an order must meet one of the linked conditions for the widget content to appear in the document.

Using a preset restriction:

Add preset restriction (material:rule_folder)

Choose one of the following options to add a preset restriction or combination of restrictions directly:

  • Payment due

  • Payment due and valuta date

  • Payment due and early payment and discount

  • Payment due, valuta date and early payment and discount

Notes:

The preset options are customizable.

The symbol for Add preset restriction (material:rule_folder) only appears for document types where the preset restrictions listed above are relevant.
Example of a widget restriction
DocBuilder Widget einschraenkungen mit inhalt 700 264

When this restriction is set in a widget, the system checks whether the associated order came directly through an own webshop and contains a specific item. If so, the document is generated with the widget content. Otherwise, it is generated without the widget content.

3.1.3. Using an operator in a condition

Use the operators listed below to define how the value in the order being checked is compared with the value in the input field.

Note: For many restriction types, only a limited selection of the operators listed below is available.

Operators for widget restrictions

Operator Explanation

=

Equal

The restriction applies to objects (e.g. order datasets) that exactly match the value in the input field.

Example: The widget content will only appear in the document for orders where the referrer is Amazon.

IN

In

The restriction applies to objects (e.g. order datasets) that contain one of the selected values in the input field.

Example: The widget content will only appear in the document for orders where the payment status is Paid.

NIN

Not In

The restriction applies to objects (e.g. order datasets) that do not contain any of the selected/entered values in the input field.

Example: The widget content will only appear in the document for orders where the payment status is anything but Paid.

>=

Greater than or equal

The restriction applies to objects (e.g. order datasets) in which the corresponding value is greater than or equal to the value in the input field.

Example: The widget content will only appear in the document for orders with a postal code of 2000 or higher.

⇐

Less than or equal

The restriction applies to objects (e.g. order datasets) in which the corresponding value is less than or equal to the value in the input field.

Example: The widget content will only appear in the document for orders with a postal code of 2000 or lower.

>

Greater

The restriction applies to objects (e.g. order datasets) in which the corresponding value is greater than the value in the input field.

Example: The widget content will only appear in the document for orders with a total weight greater than 5 kg.

<

Less

The restriction applies to objects (e.g. order datasets) in which the corresponding value is less than the value in the input field.

Example: The widget content will only appear in the document for orders with a total weight less than 5 kg.

[]

Between

The restriction applies to objects (e.g. order datasets) in which the corresponding value lies between the two values in the input field.

Example: The widget content will only appear in the document for orders placed between July 1 and 30, 2022.

∃

Exists

The restriction applies to objects (e.g. order datasets) in which the corresponding field contains a value.

Example: The widget content will only appear in the document for orders that contain a value in the field Loyalty program.

∄

Does not exist

The restriction applies to objects (e.g. order datasets) in which the corresponding field does not contain a value.

Example: The widget content will only appear in the document for orders that do not contain a value in the field Loyalty program.