Advanced document template customization

The document template editor in Rentman lets you easily customize your templates to your liking and to the needs of your company. Our editor offers you a number of options to customize your template with a WYSIWYG (what you see is what you get) system, without needing to know or touch any code.

That said, we wanted to give our more advanced users the possibility to make more sweeping changes to their templates, changes not limited to what is possible through the WYSIWYG options. Because of this, we give you the possibility of editing the CSS of your documents, manipulating variables and implementing logic in them, as well as applying conditional styling.

Note: To make use of these options you need technical knowledge. If you do not have such knowledge, we recommend contacting a third party to make these changes for you, or making use of our Document template customization service. We do not offer support in the implementation or debugging of CSS, variables, or conditional styling, as you can read in our Scope of Support.

CSS

If you wish to manually change the CSS of your document so that it looks as you wish, you can do so from the Style menu of the document template editor:

f130f10d-dc63-40c4-9a31-c5269a6385bf.png

Before starting to change your CSS, we recommend first applying a theme. This will give you a structure to start from, then you can then tweak to your liking.

CSS Classes

Every element in the Rentman document template has a CSS class, which you can use in your CSS to address the specific element to style it individually. While we do not have a comprehensive list of classes we can share, you can easily see which is the CSS class you should be addressing by using the Inspect element of your browser over the document preview:

24173d7d-5290-47d2-ad20-58c4cbd18135.png

In the example above, you can see that rows containing rental items in the equipment module have classitem rental.

Tip: Rows can be dynamically generated, and might have the same class. All rental items will have the above class, for example. To address specific ones, you might want to use pseudo-selectors like :nth-child(i)

PHP

If you edit the text block in any system template, you will see that how the information is presented changes. Whereas before editing the field you maybe saw your client name as “Rentman”, you now see it as {$f.customer.displayname}. This is a variable. What that variable does is that it retrieves the displayname of the customer for the project you are generating the document from, and inserts it in the generated document in place of the variable.

Variable modifiers

In most cases, all you need to do to display a specific variable is simply to add it to your document. However, there are some scenarios where you might want or need to manipulate a certain variable. For example, before you can compare a price to a number (for an if statement, see the section below), you will need to convert the price to be a numeral. 

This can be done by adding a variable modifier to the variable itself. Following from example above, and using the regex_replace modifier, this is what the variable for the total price of the project, {$f.project_total_price}, looks when converted to be a numeral:

{$f.project_total_price|regex_replace:'/[^0-9]/':''|intval}

Please refer to the documentation on variable modifiers to see what kind of variable manipulation can be accomplished.

Note: Not all variable modifiers are allowed in the template editor. When a modifier is not allowed, the editor will inform you that is the case. Please refer also to the section below for some custom modifiers and functions you can use in our template editor

Custom modifiers and allowed PHP functions
Custom modifiers

The following are custom modifiers you can apply to your variables:

"lcfirstLocal",
"lcfirstlocal",
"ucfirstLocal",
"ucfirstlocal",
"formatTime",
"formatBytes",
"formatDateTime",
"formatDiscount",
"formatDistance",
"formatDuration",
"formatMonth",
"formatDay",
"formatDate",
"formatBoolean",
"formatNumber",
"formatPrice",
"formatPercentage",
"formatSpellout",
"formatPriceCustom",

Example: {$number|formatPrice} will display the integer returned by {$number} as a price using the decimal/thousands separator and currency according to your Configuration and document template country setting. If your currency is € and the country of the document Netherlands and the value returned by {$number} 10000, this will be shown as €10.000,00.

Allowed PHP functions

In our template editor you can also use some PHP functions, which you can read below. Please refer to the PHP documentation for the corresponding function to read about the syntax and use of a given function.

public const F_TYPE = [
'is_array',
'is_bool',
'is_countable',
'is_int',
'is_integer',
'is_object',
'is_null',
'is_string',
'is_float',
'is_double',
'isset',
];

public const F_CAST = [
'intval',
'boolval',
'doubleval',
'floatval',
];

public const F_DATETIME = [
'time',
'date',
];

public const F_ARRAY = [
'empty',
'count',
'sizeof',
'current',
'explode',
'array_key_exists',
'array_keys',
'array_values',

];

public const F_REGEX = [
'regex_replace',
];

public const F_STRING = [
'nl2br',
"ucfirst",
"lcfirst",
"ucwords",
"htmlentities",
"htmlspecialchars",
"trim",
"ltrim",
"rtrim",
"strtolower",
"strtoupper",
"mb_strtoupper",
"count",
"escape",
"strlen",
"mb_strlen",
"substr",
"mb_substr",
"str_replace",
'str_pad',
'wordwrap',
'sprintf',
'strip_tags',
'urlencode',
];

public const F_MISC = [
'min',
'max',
'abs',
'rand',
'number_format',
'round',
'ceil',
'floor',
];

public const F_RENTMAN = [
"Rentman\\getTemplateVal",
"sumprice",
"substr",
"multiplyprice",
"removePrice",
"toDate",
'buildrow',
'roundcents',
];

If statements

If statements, as the name suggests, are a way to have your documents do something if a certain condition is met, otherwise do something else. You can find one such statement in the very first text block of all our system templates for quotation, contracts, and invoices. If you edit that text block, you will see the following code:

{$f.customer.displayname}
{iff $f.contact > 0}attn. {$f.contact.firstname} {$f.contact.surfix} {$f.contact.lastname}
{/iff}{$f.customer.post_street} {$f.customer.post_number}
{$f.customer.post_postalcode} {$f.customer.post_city} {iff $f.customer.country != $company.country}{$f.customer.country}{/iff}

The condition in this case is the following, and is always defined at the beginning of the if statement:

{iff $f.contact > 0}

If the value returned by the variable {$f.contact} (the number of contact persons that client has) is greater than 0, the document will print what is inserted before the closing tag {/iff}. In this case, that is the text “attn.” and the name, suffix, and last name of the contact person. If this condition is not met (the client has no contact person), everything inside the if statement is ignored and no such information is printed. 

An other example of an extra input field with Yes/No input

{iff $f.project.custom_1 == 'Yes'}
The answer was yes
{else}
The answer was no
{/iff}

This can be done also with more than a single condition, by using {elseif}. For example:

{iff $name ='Fred'}
  Welcome Sir.
{elseif $name = 'Wilma'}
  Welcome Ma'am.
{else}
  Welcome, whatever you are.
{/iff}

Conditional styling

Conditional styling lets you apply a CSS class you define if the column you choose has a certain value. For example, let’s say you have an extra input field for your equipment that can have two values: blue and orange. Through conditional styling, you can say that equipment rows which have the color blue will have the CSS class .blue, while equipment rows that have the color orange will have the CSS class .orange.

This done, you can now style the equipment rows separately based on the class they have: for example, you can have “orange” equipment to have an orange background in your table, whereas “blue” ones will have a blue background.

Once you successfully use conditional styling, the number of visual changes you can make to your document are nearly endless. Any styling you can apply to your documents, you can apply to the classes you define via the conditional styling.

Conditional styling can be defined in the Options cut/paste of a selected module:

86c81090-016c-4882-a736-fba99f543836.png

Structure

When opening the Options cut/paste, you will be presented with a window of this type:

558cd2db-1494-4402-9e08-94fac5d83814.png

To apply conditional styling, you can append the following code right before the closing bracket of the Options cut/paste:

,
"conditionalstyling": [
  {
    "condition": {
      "field": "templVarName",
      "comparator": "comparatorValue",
      "value": {
        "value": "valueValue"
      }
    },
    "class": "cssClass"
  }
]

You then need to edit the snippet above to specify your conditions, where:

  • templVarName = the value you will see for the field templVar for the column you wish to check the condition on. Using the screenshot above as an example, if you were to define a condition based on the value of the factor (staffel), you would write “staffel”
  • comparatorValue = the kind of comparison you wish to make between the value in the field you defined above and the value you define as the comparison. You can use various comparators, such as: = (equals), != (does not equal), > (greater than), < (lesser than), *= (contains), *!= (does not contain). If you wanted to check whether the factor was greater than 3, you would use > here.
  • valueValue = the value you wish to compare to. If you wanted to check whether the factor was greater than 3, you would write 3 here. It is also possible to compare to the value of another field, like this: "value":{"value":"templVarName", "type: "templVar"}}
  • cssClass = the CSS class you wish to give to the rows that satisfy the condition you defined. For example, factorGreaterThanThree
Was this article helpful?
0 out of 0 found this helpful

Comments

1 comment
  • Hello,
    "value":{"value":"templVarName", "type: "templVar"}}
    has a Quotations mark missing after type, it should be
    "value":{"value":"templVarName", "type": "templVar"}}

    0
    Comment actions Permalink

Please sign in to leave a comment.