Differences

This shows you the differences between two versions of the page.

--- document [2020/03/14 16:29] – ddam
+++ document [2020/03/14 22:53] (current) – ddam
@@ Line 1: / Line 1: @@
-Document templates are used by Hoteldruid to generate all kinds of records that might be needed for daily operations (reports, invoices, contracts, guest communication, etc.). This page will use the following terminology: a template will be called a "document", whereas the data generated when using the template will be called a "record".
+Document templates are used by Hoteldruid to generate all kinds of records that might be needed for daily operations (reports, invoices, contracts, guest letters, etc.). This page will use the following terminology: a template will be called a "document", whereas the data generated when using the template will be called a "record".
 Thanks to the use of variables, repetitions and conditions, documents are a powerful tool that can save a lot of time once properly set up.
@@ Line 17: / Line 17: @@
 === RTF/HTML documents ===
-To easily create an RTF or HTML document, you can write the text in your preferred word processing software (like Microsoft Word or LibreOffice/OpenOffice Writer) and save it in RTF or HTML format, using all needed variables inside the document. Once edited, saved and closed, you can reopen the RTF or HTML file with a text editor (like Notepad on Windows, or Leafpad on Linux), then copy all the raw text (i.e. RTF/HTML code) and paste it inside a document from Hoteldruid.
+To easily create an RTF or HTML document, you can write the text in your preferred word processing program (like Microsoft Word or LibreOffice/OpenOffice Writer) and save it in RTF or HTML format, using all needed variables inside the document. Once edited, saved and closed, you can reopen the RTF or HTML file with a text editor (like Notepad on Windows, or Leafpad on Linux), then copy all the raw text (i.e. RTF/HTML code) and paste it inside a document from Hoteldruid.
 === Variables (all document formats) ===
-Inside documents, you can use predefined variables that will take the corresponding value when the document is generated by Hoteldruid. Combined with repetitions, variables allow to iterate through lists of reservations, guests, rooms, costs, etc. If a variable is empty (i.e. is not set by Hoteldruid because data is missing), it will be replaced by spaces in order to be filled in by hand.\\
+Inside documents, you can use predefined variables that will take the corresponding value when the record is generated by Hoteldruid. Combined with repetitions, variables allow to iterate through lists of reservations, guests, rooms, costs, etc. If a variable is empty (i.e. is not set by Hoteldruid because data is missing), it will be replaced by spaces in order to be filled in by hand.\\
 == Inline document editing ==
@@ Line 113: / Line 113: @@
 ===== "Custom variables and conditions" page =====
-On the lowest part of the Document modification page, you will find a button called "Custom variables and conditions", which lead you to the "Document custom variables" page.
+On the lowest part of the Document modification page, you will find a button called "Custom variables and conditions", clicking it leads you to the "Document custom variables" page. Here you can define rules (unfortunately named "conditions" inside Hoteldruid, and hereafter referred to as "rule conditions"), that will set your custom variables to the desired values, at the moment the record is being generated.
-*nesting conditions: all rule conditions are repeated inside each repetition, unless you use exclusive rule conditions (in that case, only that set of rule conditions will be repeated)
+=== Custom variables and arrays ===
+You can create whichever variable you want, valid for just this document, or usable in all.\\
+**WARNING:** when deleting a variable, all rule conditions that use it will be deleted as well !
-Rules to consider when editing a document:
+Arrays are variables of variables. They are key/value pairs: at each key (or index, or position) inside the array, is stored a value.
+You can create arrays of any existing variable (custom or built-in). They can be useful when working with periods (e.g. arrays of days (r4)), or when you don't know exactly how many variables your document will need.
+For instance, let's assume you want to count your guests by nationality: the number of variables needed to count all present nationalities varies from one period to another. But you can create an array of the nationality_guest variables, like [arr_nationalities(nationality_guest)], and then have it incremented inside a guest repetition (r2): the key will be set to the value of nationality_guest (i.e. a country name), while the value of the array at that key can be set to whatever you like (incremented by 1, in this example).
+==== (Rule) conditions ====
+Rule conditions are at the heart of documents. By configuring them, ordering them, and nesting them (i.e. deciding inside which kind of repetition they should be used), you can set all your custom variables to the values you need, and then have those values appear inside the record.
+**Caveat:** When nesting a repetition inside another one, e.g. an extra-costs repetition inside a reservation repetition, like: <code>[r][r3][something][/r3][/r]</code> In such a case, all rule conditions are repeated inside each repetition, so they will be repeated twice here. If you want them to only repeat once, you can set a (dummy) exclusive rule condition where you want to avoid the second repetition.
+------
+TBC
   * you can compare dates with format YYYY-MM-DD in "if" conditions, then the date format is changed when they are displayed or assigned to other variables