|Classes of Christian Vigh||PHP RTF Tools||help/README.templater.md||Download|
The RtfTemplater class is an abstract class that allows you to preprocess Rtf template files, using either the RtfStringTemplater or RtfFileTemplater derived classes.
It includes a small macro language that you can use to generate customized output Rtf files.
The following example instantiates an RtfFileTemplater object, passing it the name of a template Rtf file (template.rtf), then saves the preprocessed contents to output file sample.rtf. Note that a set of variables is also included in the templating process, provided by the $variables array :
The above example will be used throughout the Templating language reference guide.
Example Rtf file
A sample Rtf file (template.rtf) will also be used to demonstrate the capabilities of the RtfTemplater class and its macro language ; if you open it using some editor such as Microsoft Word, you will see the following contents :
Some text after VNAME1, then VNAME2 with spurious RTF tags interspersed :
%$VNAME2 . ? catenated with coucou?%
A hardcoded percentage result : 12,5%
A second hardcoded percentage result : 12,5%% (2) this example shows double percent signs
An undefined variable : %$TOTO%
Current date/time : %( date ( ?Y/m/d H:i:s? ) )%
%IF( $VNAME1 == ?1 )%Text for VNAME1 = 1% ELSEIF ($VNAME1 == ?2? )%Text for VNAME1 = 2% ELSEIF ($INDEX == 16 )%INDEX is equal to 16% ELSEIF ($INDEX == 17)%Index is equal to 17% ELSE%VNAME1 is neither equal to 1 nor to 2 (%$VNAME1%)%END%
%REPEAT ( $index = 10 )%Repeated line #%$index% %END%
%FOR ( $i = 1 TO 10 )%FOR Line #%$i% %END%
%FOREACH ($var IN $ARRAY)%CONTENTS WITH FOREACH : %$var% %END%
Templating language reference
The templating pseudo-language implements a few simple control structures. All expressions can reference variables that have been passed to the constructor of the RtfStringTemplater or RtfFileTemplater class constructor :
Array keys are simply variable names, which are case-sensitive, while values represent variable values.
Note that in the above example, one of the variables, 'ARRAY', is not scalar ; such an array variable can be used in FOREACH constructs.
Templating allows you to generate an output file based on a template, which will use the variables you specified to the class constructor.
The following section describes the various macro-language constructs that can be used in a Rtf template.
Expressions can reference variables passed to the class constructor, but they can also use any operators or functions provided by PHP. Expressions are replaced with their evaluation result in the output contents. As for PHP, variable names must be prefixed by the "$" sign ; for example (using our example $variables array in the above example) :
will be substituted with :
will be substituted with :
Note that some compromises have to be done ; the above expression for example, has been enclosed in parentheses, otherwise it would have been recognized as pure text ("2 + $INDEX"). This is due to the fact that the delimiter has been fixed to be the percent sign, and that the class allows you, for flexibility reasons, to specify a percent sign in your template, such as in :
Undefined variables will be expanded to an empty string and a warning will be issued, unless the $warnings parameter of the class constructor has been set to false.
IF constructs can be specified with conditions that use the same elements as expressions ; for example :
will be substituted with the string "Index = 17!!!" if the $INDEX variable passed in the $variables array to the constructor is equal to 17.
An IF construct can have as many ELSEIF statements as needed and an optional ELSE statement :
will be substituted in the output with :
Well, in fact you will see two empty lines in the output result, because paragraph marks have been put in the template RTF contents after the IF and ELSEIF constructs. If you would like no line break to be inserted, then you should rewrite you expression this way :
Paragraph marks (line breaks) between the enclosing percent signs of an instruction are ignored.
FOR loops are a way to repeat text a certain number of times. Specify a start and end index :
will output "This is line #1" through "This is line 16". You can also specify an optional step :
which will output "This is line #1", then "This is line #3", "This is line #5", etc.
Repeat loops are simply a notational shortcut :
is equivalent to :
FOREACH loops are based on array variables (look at the 'ARRAY' entry of the $variables array in the example above).
The following instruction will display the text "string a", "string b", "string c" on separate lines :
The following variables are predefined and can be referenced anywhere :
Coping with percent signs
The templater class does its best in distinguishing control statements from pure text. It will for example correctly handle the following case :
which will expand to :
However, if you follow "20%" with a sign that is recognized as the start of an expression, such as an opening parenthesis :
then it will try to interpret the string "% (since 2016) some other text%" as an expression and will issue a warning.
To avoid such situations, simply double the percent sign, as in the following :
Under the hood
Imagine that your user references the following variable in his template :
This will give the following RTF code :
but put in boldface the "%V" and "2%" portion of the variable reference ; you will now have to deal with the following Rtf code :
The code that includes the percent sign has been omitted here ; but note the start of the VNAME2 variable on line 2 ("VN"), the middle on line 3 ("AM") and the remaining on line 4 ("E2").
The RtfTemplater class correctly handles such crazy cases, by extracting the Rtf tags from the whole contents and reconstituting the original text ("%VNAME2%").
The following section describe the properties and methods available in the RtfTemplater classes.
An Rtf templater object can be instantiated with one of the following instructions :
The parameters are the following :
Returns the preprocessed contents of a template file as a string :
Preprocesses the contents of an Rtf template and write them to an output file :