From Jomres v4 manual

Introduction

This is a very simplified introduction to adding code to the Jomres output. It's designed to show the casual user the basics of adding generated code to a template's output.

If you want to edit a core Jomres file, don't change the file in core-minicomponents. This is because the file will be overwritten next time you upgrade Jomres. What you should do is copy the file to the /jomres/remote_plugins/custom_code folder (create the folder if you need to) then use the rebuild registry button in the administrator area (this feature allows Jomres to build a new registry of plugin files that it can use). Once you've rebuilt the registry Jomres will use the copy in /remote_plugins/custom_code instead of core-minicomponents. You don't have to use the folder custom_code, you could call it "freds_taxis" but if you then choose to install a plugin called "freds_taxis" then you'll lose your changes. The likelihood of a plugin actually being called "freds_taxis" is low, but you should nevertheless be aware of the possibility.

Also, ensure that you don't have two copies of j000nnxxxx.class.php in two different folders in /remote_plugins. If you were to, for example, have one file in /remote_plugins/test1 and another of exactly the same name in /remote_plugins/test2 then you'll trigger an error in Jomres where it'll complain of an event collision. This is because Jomres will see that you're trying to run the same file twice. Rename one of the files to xj000nnxxxx.class.php and rebuild the registry again to resolve this.

The basic structure

As mentioned elsewhere, the Jomres output is (for the most part) managed via patTemplates, however if you want to add some custom code to a template there are a few things you need to know.

The template files generally take the form roughly like the following:

<div class="someClass">{GENERATEDTEXT}</div>

The "<div..." stuff is normal html whereas the {GENERATEDTEXT} represents data that's been inserted into an array in the minicomponent that's called the template.

In a bit more detail

Let's look at what the calling script (the minicomponent) is doing.

The calling script will be

1. Pulling information from the database.
2. It'll do some stuff to the data.
3. It'll be passing this data to the template for display.

A working example

Let's take a look at j06000editnote.class.php. It allows the receptionist/manager to edit a note which has been added to a booking and is a nice simple example that we can use to demonstrate how things work.

Let's look at the code we're interested in. I've left out the toolbar generation to make it more readable.

$defaultProperty=getDefaultProperty();
$pageoutput=array();
$output=array();
$note_id				= jomresGetParam( $_REQUEST, 'note_id', 0 );
if ($note_id==0)
	return;
 
$query="SELECT `note` FROM #__jomcomp_notes WHERE `id`='".(int)$note_id."' AND `property_uid`='".(int)$defaultProperty."' LIMIT 1";
$output['NOTE']= doSelectSql($query,1);
$output['HNEWTEXT']=jr_gettext('_JOMCOMP_BOOKINGNOTES_EDIT',_JOMCOMP_BOOKINGNOTES_EDIT);
$output['NOTE_ID']= $note_id;
 
$output['JOMRESTOKEN'] ='<input type="hidden" name="jomrestoken" value="'.jomresSetToken().'"><input type="hidden" name="no_html" value="1"/>';
$output['JOMRES_SITEPAGE_URL']=JOMRES_SITEPAGE_URL;
 
$pageoutput[]=$output;
$tmpl = new patTemplate();
$tmpl->setRoot( JOMRES_TEMPLATEPATH_BACKEND );
$tmpl->addRows( 'pageoutput',$pageoutput);
$tmpl->readTemplatesFromInput( 'edit_note.html' );
$tmpl->displayParsedTemplate();

The template looks like this:

<patTemplate:tmpl name="pageoutput" >
<div id='jomresmenu_hint' style=color:red; >&nbsp;</div>
<form action="{JOMRES_SITEPAGE_URL}" method="post" name="adminForm">
{JOMRESTOOLBAR}
<table>
	<tr>
		<td><b>{HNEWTEXT}</b></td>
		<td><textarea class="inputbox" cols="40" rows="6" name="newtext">{NOTE}</textarea></td>
	</tr>
</table>
{JOMRESTOKEN}
<input type="hidden" name="note_id" value="{NOTE_ID}" />
<input type="hidden" name="popup" value="1" />
<input type="hidden" name="task" value="savenote" />
</form>
</patTemplate:tmpl>

First we need to know the receptionist/manager's current property.

$defaultProperty=getDefaultProperty();

Next we need to create a few empty arrays. Whilst PHP will not actually fail if these arrays aren't created it's good practice and a security measure to create them.

$pageoutput=array();
$output=array();

Now we need to find the unique id of the note that we're pulling from the database. This will have been passed via the $_REQUEST variable. If the ID hasn't been passed then we'll just drop out of the script altogether.

$note_id				= jomresGetParam( $_REQUEST, 'note_id', 0 );
if ($note_id==0)
	return;

Now we'll get the actual note from the database. As this example is very simple we're only pulling one element from the database table and we put the output directly into the $output array. Most of the time there's much more information pulled from the table's row and the data has to go through some extra processing before it's ready to be sent to the template file.

$query="SELECT `note` FROM #__jomcomp_notes WHERE `id`='".(int)$note_id."' AND `property_uid`='".(int)$defaultProperty."' LIMIT 1";
$output['NOTE']= doSelectSql($query,1);

After adding some more stuff to the $output array we're ready to show the template. First we need to add the $output array to the $pageoutput array. Then we create a new instance of patTemplate (don't worry if you don't know what that means) and we tell the $tmpl object where the file is located (setRoot). Next the $pageoutput array is given to the $tmpl object, the edit_note.html template file is read in and finally the template is displayed.

$pageoutput[]=$output;
$tmpl = new patTemplate();
$tmpl->setRoot( JOMRES_TEMPLATEPATH_BACKEND );
$tmpl->addRows( 'pageoutput',$pageoutput);
$tmpl->readTemplatesFromInput( 'edit_note.html' );
$tmpl->displayParsedTemplate();

Adding output to our working example

Ok, so we've seen how some existing code works. Now we can look at adding something to it.

Let's say that we want to get the timestamp from the same table and put that under the <textarea> where the note is edited. First we need to query the database for the timestamp:

$query="SELECT `timestamp` FROM #__jomcomp_notes WHERE `id`='".(int)$note_id."' AND `property_uid`='".(int)$defaultProperty."' LIMIT 1";
$output['TIMESTAMP']= doSelectSql($query,1);

In the script, it would look something like this:

$query="SELECT `timestamp` FROM #__jomcomp_notes WHERE `id`='".(int)$note_id."' AND `property_uid`='".(int)$defaultProperty."' LIMIT 1";
$output['TIMESTAMP']= doSelectSql($query,1);
$query="SELECT `note` FROM #__jomcomp_notes WHERE `id`='".(int)$note_id."' AND `property_uid`='".(int)$defaultProperty."' LIMIT 1";
$output['NOTE']= doSelectSql($query,1);

Not terribly efficient, database query-wise, but it's a readable example for those new to editing php.

So, we've now added the value of the timestamp column to the $output array, next we need to edit the template file edit_note.html to include the output.

<table>
	<tr>
		<td><b>{HNEWTEXT}</b></td>
		<td><textarea class="inputbox" cols="40" rows="6" name="newtext">{NOTE}</textarea></td>
	</tr>
	<tr>
		<td><b>This is the time when the note was last edited</b></td>
		<td>{TIMESTAMP}</td>
	</tr>
</table>

And there you have it. The resulting popup will show a table row underneath the text area with a legend "This is the time when the note was last edited" and the timestamp as pulled from the database.

Summary

To summarise, if you want to add output from the database to a template you need to do the following:

1. Pull the data from the database (or some other source)
2. Work with the data if it needs to be played around with before it's displayed
3. Add it to the arrays that are passed to the template object. ( here: $tmpl->addRows( 'pageoutput',$pageoutput); )
4. Add elements to the template file to show this new output.

Notes

Capitalisation

The stuff in the template, eg {TIMESTAMP} must be recorded in the template file in uppercase. It's not necessary when it's done within the calling script but I generally do it to indicate that the data is destined for a template file.

$output['NOTE']= doSelectSql($query,1);

doSelectSql($query,1);

The doSelectSql function can have several arguments.

doSelectSql($query);

Pulls an array from the database. Each element of the array is an object with the columns as variables of that object. If no data was found then the array will have zero elements in it.

doSelectSql($query,1);

Expects a query that will return just one row's column as the result and passes that back. If more than one is returned it'll trigger an error which should be recorded in the error log.

doSelectSql($query,2);

Expects a query that will return just one row, and will put the column names into an indexed array which is then passed back.

Repeated rows

For the most part the template files can be relied upon to follow similar patterns of $pageoutput and $rows to be the containing arrays passed to the template. There are exceptions to this, for either historic or other reasons, but normally the rule holds.

$pageoutput Generally will hold headers (for columns), jomresToolbar icons and form elements.

If a template has repeating data (for example a list of guests, rather than just one guest's details) then the repeating data will be put into the $rows array which would then be parsed slightly differently. The following is from the list_extras.html template.

<patTemplate:tmpl name="rows" unusedvars="nbsp">
<tr>
	<td class="jradmin_rowtoolbar">{EDITLINK}</td>
	<td class="jradmin_field_la">{EXNAME}</td>
	<td class="jradmin_field_la">{EXDESC}</td>
	<td class="jradmin_field_ca">{CURRENCY} {EXPRICE}</td>
</tr>
</patTemplate:tmpl>