User Tools

Site Tools


document

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
document [2018/04/13 07:47] ddamdocument [2020/03/14 22:53] (current) ddam
Line 1: Line 1:
-Document templates (simply called "documents" hereafter) are used by hoteldruid to generate all kinds of records that might be needed for daily operations (reports, invoices, contracts, etc.). Thanks to the use of variables, repetitions and conditions, documents are a powerfull tool that can save a lot of time once properly set up.+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.
  
-=== The Documents section === +====== Editing documents ======
-Click on "Configure", then "Documents", to land on the Documents page. Here you can create and modify documents. Clicking on a document's number, you will open the Document modification page, where you can edit its content. Documents can be created in HTML, RTF, e-mail and text format. Here's an [[example]] of an invoice using HTML. +
-You'll find more examples of alredy usable documents after a fresh intall of hoteldruid.+
  
 +It's important to understand the logic of how documents function, which can be a little offsetting at first. There is two sides to documents: the first side is the visual part of the document, i.e. which data to display where inside the generated record. This happens on the main document modification page. The second side is the creation of the content itself, where you can use variables and rules that set those variables, as the record is being generated. This happens on the "Custom variables and conditions" page.
  
-=== RTF Documents === +===== Document modification page ===== 
-To easily create an RTF document, you can write the text in your preferred word processing software (like Microsoft Word or LibreOffice/OpenOffice Writer) and save it in RTF format, using all needed variables inside the document. In order to make sure formatting is kept, it might help to use the provided RTF example file as a starting point (some advanced formatting might get lost when starting from scratch): to download the example file, just click "View document" inside its modification page. Once edited, saved and closed, you can reopen the RTF file with a text editor (like Notepad on Windows, or Leafpad on Linux), then copy all the raw text (i.e. RTF code) and paste it inside a document from hoteldruid.+ 
 +As administrator, click on "Configure", then "Documents", to land on the Documents section. Here you can create and modify documents. Clicking on a document's number, you will open the Document modification page, where you can edit the document's content. 
 + 
 +==== Document formats ==== 
 + 
 +Documents can be created in HTML, RTF, e-mail and text format. Here's an [[example]] of an invoice using HTML. Please note that the officially supported format is HTML (for support provided when subscribed to the hosted version). 
 +You'll find more examples of already usable documents after a fresh install of Hoteldruid, or by restoring them from the Documents backup page. 
 + 
 + 
 +=== RTF/HTML documents === 
 +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) === === 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.\\ 
-If you choose to edit your document directly on the document modification page (instead of using an external editor/word processor), you can use the ''Variables'' drop-down menu to easily add some variable: first choose a variable, then place the cursor where you want the variable inside the document, then click on the ''Add'' button.+ 
 +== Inline document editing == 
 +For simple documents created for internal use (mainly text format documents), you may choose to edit your document directly on the Document modification page (instead of using an external editor/word processor); in that case, you can use the ''Variables'' drop-down menu to easily add some variable: first choose a variable, then place the cursor where you want the variable inside the document, then click on the ''Add'' button. 
 + 
 +== Available built-in variables ==
 Some available variables that can be inserted are (the complete list is in the  Some available variables that can be inserted are (the complete list is in the 
-drop-down menu of the document modification page): +drop-down menu of the Document modification page): 
  
 Client's data: Client's data:
Line 54: Line 68:
  respective values  respective values
 [sel_extra_cost_name] name of the extra cost selected before  [sel_extra_cost_name] name of the extra cost selected before 
- viewing the document+ viewing the record
 [sel_extra_cost_value] value of the extra cost selected before [sel_extra_cost_value] value of the extra cost selected before
- viewing the document+ viewing the record
 [today] today date [today] today date
 [price_tot_p], as the previous ones without final _p   [price_tot_p], as the previous ones without final _p  
Line 67: Line 81:
  
 <file>[repetition_error] when not empty the current reservation  <file>[repetition_error] when not empty the current reservation 
- is not added to the document+ is not added to the record
 [email_already_sent] 1 if an email with the same subject has  [email_already_sent] 1 if an email with the same subject has 
  already been sent to client, otherwise 0  already been sent to client, otherwise 0
Line 73: Line 87:
  instead of the document</file>  instead of the document</file>
  
 +== Custom variables ==
 +You may create and use custom variables as you see fit. Please refer to the "Custom variables and conditions" section.
  
 === Repetitions === === Repetitions ===
 +Repetitions allow to iterate through lists: by enclosing variables
 +inside repetition tags, Hoteldruid will automatically replace the
 +variable names with the corresponding data, and loop through all
 +elements of the list. Example: <code>[r][surname][/r]</code>
 +will display surnames for all reservations from the current view (e.g. "Arrivals", or any other table of reservations).
 The document parts that are enclosed in [r][/r] tags will be  The document parts that are enclosed in [r][/r] tags will be 
-repeated for each reservation (if these tags are not present the  +repeated for each reservation. Inside these parts, other lists 
-whole document will be repeated). Inside these parts, other lists +
 can be inserted with tags [r2][/r2] (for guests) or [r3][/r3]  can be inserted with tags [r2][/r2] (for guests) or [r3][/r3] 
-(for extra costs). When creating a list with guest data (which is done with a [r2] repetition), you need to use the variables that end with the "_guest" suffix+(for extra costs). 
-You can use the ''Limits of'' drop-down menu (same usage as variables+You can use the ''Limits of'' drop-down menu (same usage as variable drop-down menu
-on the document modification pageto easily add repetitions inside your documents. +on the Document modification page to easily add repetitions inside your documents.\\
-----+
  
 +== Caveats when using repetitions ==
  
-Rules to consider when editing document:+__Use specific variables inside repetitions__ 
 +  *r2 repetitions: when creating a list with guest data, you need to use the variables ending with the "_guest" suffix inside this repetition. These variables are only defined inside a guest repetition.\\ 
 +  *r6 repetitions: when creating list with room data, you need to use the variables beginning with "unit_" inside this repetition. These variables are only defined inside a room repetition.\\ 
 +__Special cases__ 
 +  *r4 repetitionswhen you have a repetition of reservations ([r][/r]) inside a repetition of dates ([r4 array="dates_array"][/r4]), then only reservations that are present in current date will be repeated.\\ 
 +  *The tags for reservations repetition ([r][/r]) are forbidden in multilingual mode (i.e. the whole document is repeated for each reservation).\\
  
-  * when you have repetition of reservations ([r][/r]) inside a repetition of dates ([r4 array="dates_array"][/r4])then only reservations that are present in current date will be repeated.+===== "Custom variables and conditions" 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. 
 + 
 +=== Custom variables and arrays === 
 +You can create whichever variable you want, valid for just this document, or usable in all.\\ 
 +**WARNING:** when deleting variable, all rule conditions that use it will be deleted as well ! 
 + 
 +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 caseall 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   * 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
 +
document.1523605672.txt.gz · Last modified: 2018/04/13 07:47 by ddam