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 a report which is based on a form relationship.

Interaction

At the first phase of this module, the only interaction is to produces the reports 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 report relationship. For example:

http://<SITE_URL>/StandardForm/registration?ids[]=person|12&ids[]=person|14&ids=[]person|22

Hitting this URL would cause the following to happen:

• verify that a standarized 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 'can_view_standarized_forms_all'
  • If not, check to see if the task 'can_view_standarized_form_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).

Magic Data Details

All standardized forms will be stored under the magic data node:

/modules/StandardForm/forms

In the example above the details defining the registration form would stored under:

/modules/StandardForm/forms/registration

The details for a specific form are as follows:

• report: Required scalar node. the name of the report that this form is based off of. It needs to be the name of a child node of /modules/CustomRepoumrts/reports
• layout_details: Optional parent node describing the page layout details for the form. It contains the following child nodes.
  • 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'
  • unit: Optional scalar node: The unit of measurement for all dimensions. Defaults to 'mm'. Should be one of 'mm','in' or 'cm'.
  • 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.
• content: Required parent node defining the content of the standard form.
  • properties: An optional parent node defining the default properties of the element types of the document. Possible values are:
    • text: Optional parent node containing the following nodes:
      • direction: Optional scalar node: Defaults to 'LTR' can also be 'RTL'.
      • alignment: Optional scalar node. Defaults to 'L' for left. Can be 'R' or 'J'
      • color: Optional color. Defaults to black (not sure if we should use hex colors, rgb triples or what here)
      • background color. Defaults to none (transparent).
      • underline: Optional scalar node. Defaults to 0. If evaluates to true we underline the entire element
      • bold: Optional scalar node. Defaults to 0. If evaluates to true we bold the entire element
      • italic: Optional scalar node. Defaults to 0. If evaluates to true we italicize the entire element
    • image: Optional parent node containing the following nodes. Nothing defined here
  • 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.
    • 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 scalar node. A comma separted list of the report form fields to substitute into the printf. E.g. "person+surname,person+fisrtname,registation+number"
• 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: Required numeric scalar node. The bottom most coordinate to place this text.
• vert-min: Optional numeric value. If set, then height = vert-min - vert-max

Note: If the direction is RTL then the meanings of horiz-max and horiz-min are opposite in that left and right should be swapped.

Definition for Type: Image

• image: Required standard node. the name of the image file to place. the search path used is "IMAGES"?
• left: Required numeric scalar node. The left most coordinate to place the image.
• bottom: Required numeric scalar node. The bottom most coordinate to place the image

Processing Content

The standardized form should be produced on the standardized form class by something like: <source lang='php'>

function processContent($output_type, $layout_details, $contentNode, $ids) {
   $outputClass = "StandardForm_Output_$output_type";    
   $outputObj  = new $outputClass($layout_details);
   foreach ($ids as $id) {
     if (!$this->report->hasRow($id)) {
       continue;
     }
     $outputObj->setValues($this->report->getRow($id));
     $outputObj->addContent($contentNode);
  }
  return $outputObj
 }

</source>

The standardized form output base class should have something like: <source lang='php'>

 public function addConennt($contentNode) {
    $this->beginNewForm();  //goes to the space in the document to put a form
    $this->processContent($contentNode);     
 }

 protected function processConent($contentNode, $properties = array()) {
    $t_properties = array();
    $contentNode->getAsArray($t_properties,'properties',true);
    $properties = I2CE_Util::array_merge($properties,$t_properties);  //something like this
    $this->addElement($contentNode,$properties)
    if ($contentNode->is_parent('elements')) {
       $keys = $contentNode->getChildNames('elements'));
       sort($keys)
       foreach ($keys as $key) {
          if (!$contentNode->is_parent("elements/$key")) {
             continue;
          }
          $this->_processConent($contentNode->elements-$key,$properties);
        }
    }
 }

</source>

The addElement() method will (after some validity checking) class should call something like the following methods:

• $this->add_Element_text($properties,$definition)
• $this->add_Element_value($properties,$definition)
• $this->add_Element_image($properties,$definition)

this is so that new element types and output can be added in as modules.