Functions in document templates

From Planfix
Jump to: navigation, search

Functions can be used when automatically formatting documents using templates. Functions simplify how data is displayed in your documents. For example, you can use formulas to automatically display numbers as words or calculate order costs.

Formulas

To add a formula to a document, use the following syntax: %%%FORMULA%%%.

A FORMULA is an expression for calculating the value of a field, just like in a calculated field.

Example:

%%%TEXT({{DataTag.Service.Quantity}}*{{DataTag.Service.Cost}};".2f")%%%


In the example above, data from the "Service" data tag is added to the formula using the corresponding variables. The two values are multiplied, and the result is the value of the total cost of a specific service or product. The TEXT() function formats the value as a human-readable text string.

Important

For example:

  • Formulas must be written in a single string and cannot be split by pressing Enter. If you need to insert a line break, use the sequence "\n".
  • Without a line break
%%%IF({{Datatag.Service calculation.Service}}=""; ""; {{Datatag.Service calculation.Service}} + " - " + {{Datatag.Service calculation.Quantity}} + " " + {{Datatag.Service calculation."Unit"}} + " (" + {{Datatag.Service calculation.Comment}} + ")" )%%%
  • With a line break
%%%ЕСЛИ({{Datatag.Service calculation.Service}}=""; ""; {{Datatag.Service calculation.Service}} + " - " + {{atatag.Service calculation.Quantity}} + " " + {{{Datatag.Service calculation."Unit"}} + "\n (" + {{Datatag.Service calculation.Comment}} + ")" )%%%
  • Variables in the formula cannot be formatted, for example, in bold or italics.
  • If you want the result of the formula to appear in bold, apply the formatting to the entire formula, including the percentage symbols.

Functions

All functions available in document template formulas:


The SUM function

SUM() is a function that adds up all values obtained when calculating a formula. It is applied to each element of a multiplying variable.

For example, say you have a "Service" data tag and you want to calculate the total cost of all services in a document. You would use the following function: 

SUM({{DataTag.Service.Cost}})


In order to get the total cost of services provided, you must multiply the cost of the service by the number of times it was ordered. Here's the formula you should use in your document: 

SUM({{DataTag.Service.Cost}}*{{DataTag.Service.Quantity}}))


Note that the SUM() function can contain any formula made up of functions.

The PLURALFORM Function

Used to append a suffix to a word or to change the word itself if it is an irregular noun based on the number given before it in the document template.


Format: 

PLURALFORM (number; "text1"; "text2";)


Depending on the calculated value of the number, the function selects one of two parameters. The parameters must be specified in strict order according to the algorithm.

For example, you need to inflect the word "dollar." Follow the algorithm:

First, write the required word with the number 1:

  • 1 dollar

This means that the first parameter in the function "should be the word "dollar" instead of "text1".


Then, write the word with the number 2:

  • 2 dollars

This means that the second parameter in the function "should be the word "rubles" instead of "text2".

Finally, you can specify the following PLURALFORM() function in the document:

PLURALFORM(SUM({{Datatag.Service.Cost}}*{{Datatag.Service.Quantity}}); "ruble"; "rubles")

The NUMBERASWORDS function

This is a function that returns a number as words. Only the integer part of the number is written out.

Format: NUMBERASWORDS(number; Output; "language")

Where:

  • number — is a number or formula
  • Output — defines how the numeral will be displayed (from 0 to 6)
  • language— string that specifies the output language. If left empty the language of the user generating the document is used.

Languages and their Output methods:

  • English ("en")
    • 0-3 – default (cardinal number)
    • 4-6 – capitalized default
  • German ("de")
    • 0 – default (gender-neutral)
    • 1 – written in feminine
    • 2 – written in masculine
    • 3 – written in neuter
    • 4 – capitalized in feminine
    • 5 – capitalized in masculine
    • 6 – capitalized in neuter
  • French ("fr"
    • 0 – default (cardinal number)
    • 1 – written in feminine
    • 2 – written in masculine
    • 4 – capitalized in feminine
    • 5 – capitalized in masculine


For example, to display a number as words in a document, use the following function: 

NUMBERASWORDS(SUM({{DataTag.Service.Cost}}*{{DataTag.Service.Quantity}}); 2; "en")

The FRACTIONALPART function

This function displays the fractional part of a number. You can specify the number of digits after the decimal point you would like to see.


Format: 

FRACTIONALPART(number; NumberOfDigitsAfterDecimal)


For example, to output the number of cents for the cost of a service in a document, use the following function: 

FRACTIONALPART(SUM({{DataTag.Service.Cost}}*{{DataTag.Service.Quantity}}); 2)


This function displays the two digits after the decimal point:

  • 176.03 — function returns 3.
  • 15.15 — function returns 15.
  • 16.156 — function rounds first two decimal points to 16.


Go To

Retrieved from "http://planfix.com/help/index.php?title=Functions_in_document_templates&oldid=21824"