View source for Mail Merge Specification: Technical Req'mts: Placeholders

=WORK IN PROGRESS=
'' '''THIS PAGE IS WORK IN PROGRESS!''' ''

'''NOTE:''' Please refer to the [[Specification for Mail Merge (former 'Form Letters' in Petra 2.x)#Terminology|Terminology]] for the exact definition of words and phrases!

==Types of Placeholders==
Various kinds of Placeholders will need to be available.<br>
We will specify them at a later stage in detail, but they will include the following as a minimum: 

* Textual Placeholders (such as Name, Last Name, Address);
** multiple lines per Textual Placeholder must be possible (e.g. for Address)!
* Numeric Placeholders;
** with formatting options such as integer, decimal, currency, etc
** for floating-point numbers one must be able to specify the number of digits before and after the decimal point
** for currency one must be able to specify the 'currency symbol' (i.e. 'EUR', 'USD', etc) and one must be able to specify whether it should be printed right or left of the of the amount
* Date Placeholders (but not for time);
** with various formatting options ''(possibly)''
** in case we don't implement various formatting options then dates will need to be formatted using the OpenPetra date formatting standard (e.g. '23-JAN-2013') which is the same for every .NET Culture (i.e. everywhere in the world)
* [[Mail Merge Specification: Technical Req'mts: Placeholders#Tabular_Data_Placeholders|Tabular Data Placeholders]];
** with various formatting options
*** alignment of content per column [left, right, centre]
*** 'show header cells' [yes/no] ''(possibly)''
**** if this is to be implemented then also the alignment of content per column should be implemented as separate option for the header cells 
*** 'banding effect' [yes/no]  ''(possibly)''
**** that is, 'row shading' in the table alternating between two colours
* Image Placeholder ''(possibly)'';
** images would be loaded from files 
*** the file path to the images would need to be specified in some way, possibly by 
**** convention (all files would need to be accessible from a certain fixed path that will need to be configurable though a site-wide system parameter or configuration file parameter), or
**** through parametrisation of the image Placeholders (could potentially allow different paths per image contained in the Mail Merge Document, and even per Merged Document!)
* Placeholders for the insertion of single empty lines (i.e. CR+LF) ''(possibly)'';
* Placeholders for the insertion of page breaks. ''(possibly)''.

===Tabular Data Placeholders===
With Tabular Data we mean 1..n lines of text that each consist of 1..n columns and which will need to be laid out using a Table. Example: A list of all Gifts given in a year by a particular donor, contained in a ‘thank you’ letter that is sent to  all donors who made at least one donation in that year.

===General=== 
The list of available Placeholders will be static/hard-coded, hence there will be no need to allow users to add new Placeholders.

'''TODO:''' We still need to determine whether there will be a need for having the types of Placeholders that are annotated with '(possibly)' in the above list.

'''TODO'''

==Parameterised Placeholders==
It must be possible to parameterise certain Placeholders.<br>
Parameterisation for such Placeholders must be possible either by 
* the user, or 
* by some programmatic logic. 


Examples for parametrisation ...
* by the user: selection of a particular Address Layout for a particular Mail Merge Document that the user chooses, 
* by some programmatic logic: 'calculated fields' and even 'calculated Tabular Data' (such as the list of Gifts mentioned above). 

'Calculated fields' could be as simple as "today's date" or be based on programmatic logic. 

The 'programmatic logic' for 'calculated fields' and 'calculated Tabular Data’ could be quite complex and would fill Placeholders differently for different Merged Documents, depending on arbitrary data available for decisions (e.g. site-wide system parameters, configuration file parameter, user preferences, database query results, etc) or even depending on the results returned by Placeholder-specific C# Methods that return a result of a certain Type [e.g. Boolean, string, Date, decimal, DataTable]).

'''TODO'''