Printed Forms
This is a design document for the printed forms module.
The printed forms module is used to print "standardized" or "official" forms based upon the data in the system. For example, it might be the registration number for a nurse.
The output will be either PDF (which Carl prefers) or html (which Luke prefers).
Source Data
The source data for the printed form will be based on a form relationship.
Page Interaction
At the first phase of this module, the only interaction is to produces the printed forms based on what is stored in magic data. There will be no "document design" component. The standard form will be accessed through a URL with the name of the standardized form and a GET/POST variable containing one or more of the id's for the primary form in the form relationship. For example:
http://<SITE_URL>/PrintedForms/print/registration?ids[]=person|12&ids[]=person|14&ids=[]person|22
Hitting this URL would cause the following to happen:
- verify that a standardized form called registration exists
- verify that the user has the appropriate permission to view this standardized form:
- Check to see if the user has the task 'printed_forms_all_generate'
- If not, check to see if the task 'printed_forms_generate_registration' exists and the user has this task
- for each of the ids, person|12, person|14, person|22 fill out the details of the standardized report by using the corresponding row in the report table if it exists (see below).
Menu
One should be able to see which forms can be generated for a given id. Calling
http://<SITE_URL>/PrintedForms/menu?id=person|12
will show all the printed forms whose primary form is person. Then for each of these you will have a link to the corresponding print page.
You should also link to the corresponding archive page and show which PDF forms have already been archived for that person sorted by type and date.
Archive
You should also create a form, say generated_doc which contains the following fields:
- document: A binary field which will contain the PDF it
- date: the date it was generated by
- type: the print standard form (e.g. registration in the above example)
When calling the archive page as:
http://<SITE_URL>/PrintedForms/archive/registration?ids[]=person|12&ids[]=person|14&ids=[]person|22
It will:
- check to see if 'generated_form' is a child form of person. If not execution stops.
- for each of the id's it will created the PDF form (only one on each page/document) and save it as a child generated_doc form
View Person
There should be links added to the view person page to the appropriate menu page as well as showing a list of the archived forms for that person sorted by type and date.
Magic Data Details
All standardized forms will be stored under the magic data node:
/modules/PrintedForms/forms
In the example above the details defining the registration form would stored under:
/modules/PrintedForms/forms/registration
The details for a specific form are as follows (all measurements are in mm):
- relationship: Required scalar node. the name of the form relationship that this form is based off of. It needs to be the name of a child node of /modules/CustomReports/relationships
- displayName: Optional scalar node. The name of the printed letter as displayed to the end user.
- layout_details: Optional parent node describing the page layout details for the form. It contains the following child nodes.
- encoding: Optional scalar node. The encoding used by the renderer(PDF). Defaults to ASCII
- hyphenation_file: Optional scalar node. File used for hyphenation. Defaults to hyph_en_US.dic'
- orientation: Optional scalar node. Defaults to 'P' for portrait. The other option is 'L' for landscape
- size: Optional scalar node. Defaults to 'A4' to describe the paper to be used. Should be one of the ISO 216 standard paper sizes, e.g. 'A4', or one of the North American paper sizes, e.g. 'letter' or 'legal'
- rows: Optional scalar node: Defaults to 1. The number of rows of forms to be printed on the page.
- cols: Optional scalar node: Defaults to 1. The number of columns of forms to be printed on the page.
- border: Optional scalar node. Defaults to 0 if rows and columns are 1, otherwise it to defaults to 1. The width of the border drawn around the forms.
- vert_pad: Optional scalar node. Defaults to 10. The vertical padding used on the page boundary
- horiz_pad: Optional scalar node. Defaults to 10. The horizontal padding used on the page boundary
- vert_pad_border: Defaults to 0. The vertical padding used between forms
- horiz_pad_border: Defaults to 0. The vertical padding used between forms
- text_properties: An optional parent node defining the default text properties of the element types of the document. Child node names are the name of the element types (image or text). Possible values are:
- font: Optional scalar node. Defaults to helvetica. Should be limited to one of the standard pdf fonts: times,helvetica, courier
- size: Optional positive integer node.Size in points of font. Defaults to 12.
- alignment: Optional scalar node. Defaults to 'L' for left. Can be 'R' or 'J', 'L' or 'C'
- color: Optional color foreground/text color. Use html style hex colors. Defaults to black #000000 ,
- bg_color: Optional background color. Use html style hex colors. Defaults to 'none' for transparent.
- style: Optional scalar node. Default to blank. Can contain any of the following characters, B for bold, U for underline, I for italic
- elements: Parent node. Children should be numerically indexed. Elements are added to the standard document in increasing numeric order of the node name of the element. Elements can be composed of sub-elements which can be composed in turn of sub-sub-elements, which can be composed of in turn of sub-sub-elements... The properties of an element are inherited by all of its sub-elements. Each of the child nodes will contain the following:
- elements: An optional parent node containing a list of all its sub-elements. The details of a sub-element are as above.
- text_properties: An optional parent node defining the properties which applies to this node and all of its sub-elements of this. The definition is the same as above.
- element: An optional parent node which describe some visual element to be placed:
- type: Required scalar node. Should be one of 'text' 'image' or 'value'
- definition: Depends on the type. See below.
Definition for type: Text
The text element is just certain text to be placed in the document. It should consist of the following nodes:
- printf: Optional scalar node. The a printf string to be placed here. Defaults to . Example: "%s, %s has registation number %s"
- printf_args: Optional parent node. An array of arguments to subsititute into the printf as follows
- formname+field: a report form fields to substitute into the printf. E.g. "person+surname,person+fisrtname,registation+number":
- +relationshipFunction: The evaluation of the named function in the the form relationship. Example +age65 which be the year the person turns 65 in the staff relationship
- ++date(XYZ): The data formatted according to XYZ (unquoted) via strfrtime functions. Example ++date(%Y) is the four digit year
- ++date: The date. This is the same as ++date(%x).
- ++user: The name of the user printing the form
- ++eval(XYZ): Evaluate the php code XYZ. Example is ++eval(strftime("%Y")+60) would add 60 to the current year
- horiz_min: Required numeric scalar node. If the alignment is 'L' it is the left most coordinate to place this text. If the alignment is 'R' it is the right-most cooridnate of the text
- horiz_max: Optional numeric scalar node. If not set and the allignment is 'J' then the alignment reverts to 'L'. If set and allignment if 'L' is the right-most coordinate. If set and alignment is 'R' then it is the left-most coordinate. If set and alignment is 'J' then the this is the right-most coordinate and horiz-min is the left-most coodinate.
- vert_max: Optional numeric scalar node. The bottom most coordinate to place this text.
- vert_min: Required numeric scalar value. The top most coordinate to place this text.
Definition for Type: Image
- image: Required standard node. the name of the image file to place. the search path used is "PDF_IMAGES"
- horiz_min: Required numeric scalar node. The left most coordinate to place the image.
- vert_min: Required numeric scalar node. The top most coordinate to place the image
- horiz_max: Optional numeric scalar node. The right most coordinate to place the image. If set, image is rescaled if needed.
- vert_max: Optional numeric scalar node. The bottom most coordinate to place the image. If set, image is rescaled if needed.
Example
For example, to produce this sample Staff Hire Letter you would define it as: <source lang='php'>
array(
'relationship'=>'staff',
'displayName'=>'Staff Hire Letter',
'layout_details'=>array(
'cols'=>2,
'rows'=>3
),
'elements'=>
array(
-1=>array(
'element'=>array(
'type'=>'image',
'definition'=>array(
'image'=>'iHRISManage_logo_whiteBG.png',
'horiz_min'=>'35',
'vert_min'=>'1'
)
)
),
0=>array(
'text_properties'=>array(
'style'=>'BIU'
),
'element'=>array(
'type'=>'text',
'definition'=>array(
'horiz_min'=>50,
'vert_min'=>10,
'printf'=>"iHRIS Sample Letter"
)
)
),
1=>array(
'element'=>array(
'type'=>'text',
'definition'=>array(
'horiz_min'=>3,
'vert_min'=>50,
'printf'=>
'The person %s %s, was hired on %s and should retire in the year %s. I am the user %s, and today\'s date is %s, The year is %s , and the log of 4.2 is %f '
. "\nThis is a line that was manually broken\nNow we need to put in a word hippopotomonstrosesquipedaliophobia"
,
'printf_args'=>array(
'person+firstname',
'person+surname',
'staff+start_date',
'+age65',
'++user',
'++date',
'++date(%Y)',
'++eval(log(4.2))'
)
)
)
)
)
)
</source>
