This is a rough draft for template. It will eventually be transfered
to an XML manual.

Templates

The fastest way to use templates are to use the process function like so:

$template = array("HEADING" => "Welcome", "CONTENT" => "This is beginning");
$module = "mymod";
$file  = "welcome.tpl";

PHPWS_Template::process($template, $module, $file);


The 'welcome.tpl' file will look something like the following:

<div class="title">{HEADING}</div>
<span class="content">{CONTENT}</span>

The template class uses the module variable to look for the template file.
It will first look in the theme (e.g. theme/mytheme/templates/mymod/welcome.tpl)
then it will look in the template directory (e.g. templetes/mymod/welcome.tpl).
Finally it will look in the mod directory itself (e.g. mod/mymod/templates/welcome.tpl).

(Note: this order may change depending on your template config file.)

The process function will return your template file with the tabs filled in.


Sometimes you may want to create your own template object. This comes in handy for
repeated rows.

Lets say the template looked like the following:

{TITLE}
<ol>
  <!-- BEGIN repeat_row -->
   <li>{NAME} {POSITION}</li>
  <!-- END repeat_row -->
</ol>
{CONCLUSION}

To have the line item repeat you would put the row array INSIDE the
row definition. 

This will repeat the 'li' line over and over within the same template.
Here is an example:

$template['TITLE'] = 'Names of Cabinet';
$template['CONCLUSION'] = 'Visit office for more information.';

$template['repeat_row'][] = array('NAME' => 'Tom Horn',
			          'POSITION' => 'President');

$template['repeat_row'][] = array('NAME' => 'Jane Plymore',
			          'POSITION' => 'Vice President');

The template class will then expect a repeated row named 'repeat_row'
and it will try to plug in the values from the array.

Note: If you are getting repeats outside of your BEGIN/END tags MAKE
SURE your tags are set properly:

<ol>
  <!-- BEGIN repeat_row-->
   <li>{NAME} {POSITION}</li>
  <!-- END repeat_row -->
</ol>

The above won't work. It's so small it is hard to notice. Look at the
BEGIN line. There isn't a space between the 'repeat_row' and the
'-->'.
One added or missing character can cause it not to work. Compare the
BEGIN and END comments character by character.


Embedded Rows
---------------------------------------------------------------------
Sometimes you will have repeat rows inside other repeated rows. This
is beyond the abilities of the above example. You will need to
instantiate a template object.

First run the constructor:

$tpl = & new PHPWS_Template($module);

Now set the file:

$result = $tpl->setFile($template_file);

The result will either be TRUE or a PHPWS_Error object.

To have the line item repeat you would use setCurrentBlock, like so:

$tpl->setCurrentBlock("repeat_row");

$tpl->setData(array('NAME'=>'Sam', 'COLOR'=>'red'));
$tpl->parseCurrentBlock();

$tpl->setData(array('NAME'=>'Ted', 'COLOR'=>'green'));
$tpl->parseCurrentBlock();

$tpl->setData(array('NAME'=>'Pat', 'COLOR'=>'blue'));
$tpl->parseCurrentBlock();

To get your data for presentation call get like so:
$content = $tpl->get();

Another hint. If you are imbedding repeating rows, the parent row must
be parsed _after_ the the child rows.

For example, lets say you want a list of families by last name. Inside,
the first names of the family members are listed. Here is what the
template may look like.

<ol>
<!-- BEGIN lastname-list -->
  <li>
    {LAST_NAME}
    <ol>
      <!-- BEGIN firstname-list -->
      <li>{FIRST_NAME}</li>
      <!-- END firstname-list -->
    </ol>
  </li>
<!-- END lastname-list -->
</ol>

Here is the code:

foreach ($families as $lastname){
  foreach ($members[$lastname] as $firstname){
    $tpl->setCurrentBlock("firstname-list");
    $tpl->setData(array("FIRST_NAME"=>$firstname));
    $tpl->parseCurrentBlock();
  }

  $tpl->setCurrentBlock("lastname-list");
  $tpl->setData(array("LAST_NAME"=>$lastname));
  $tpl->parseCurrentBlock();
}


If the lastname rows were put before the first name list, the first
names would be put under the wrong last names.

Remember to work inside to outside for order of importance.