mirror of
https://github.com/EGroupware/egroupware.git
synced 2024-10-06 02:02:24 +02:00
697 lines
32 KiB
HTML
697 lines
32 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<html><head>
|
|
<meta http-equiv="CONTENT-TYPE" content="text/html; charset=utf-8"><title>eGroupWare: eTemplates - Templates and Dialog-Editor</title>
|
|
|
|
<meta name="GENERATOR" content="NeoOffice 1.2 (Unix)">
|
|
<meta name="CREATED" content="20060219;14431900">
|
|
<meta name="CHANGED" content="20060220;16434900">
|
|
<!-- $Id$ -->
|
|
|
|
<style>
|
|
<!--
|
|
H1 { color: #000000 }
|
|
P { color: #000000 }
|
|
PRE { border: 1px solid #000000; padding: 0.08in; color: #000000; font-family: monospace }
|
|
H3 { color: #000000 }
|
|
H2 { color: #000000 }
|
|
-->
|
|
</style></head>
|
|
|
|
<body bgcolor="#ffffff" dir="ltr" lang="en-US" text="#000000">
|
|
<h1>eTemplate - Templates and Dialog-Editor for eGroupWare</h1>
|
|
<h3>by Ralf Becker <a href="#" onclick="document.location='mai'+'lto:RalfBecker'+unescape('%40')+'outdoor-training'+unescape('%2E')+'de'; return false;">RalfBecker
|
|
AT outdoor-training DOT de</a></h3>
|
|
<h3>Updated by Raphael Alla <a href="#" onclick="document.location='mai'+'lto:raphael'+unescape('%40')+'olineopensolutions'+unescape('%2E')+'com'; return false;">>raphael AT olineopensolutions
|
|
DOT com</a></h3>
|
|
<p>A developers tutorial how to write an application with the new
|
|
eTemplates.<br>It is also an introduction how to write a eGW- and
|
|
setup(3)-compatible app.</p>
|
|
<hr>
|
|
<h1>Introduction - The concept of the eTemplates</h1>
|
|
<p>The eTemplates
|
|
</p>
|
|
<ul>
|
|
<li><p style="margin-bottom: 0in;">consist out of rows and cols with
|
|
input-fields of several types
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">there is a dialog-editor (one part
|
|
of the etemplate-app) to create the eTemplate
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">eTemplates can be (and are
|
|
usually) nested, eg. a template-field can contain an other eTemplate
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">each field / cell of the template
|
|
can have a label which is automaticaly run through lang() (the
|
|
content of the field can be run through lang() too)
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">the dialog editor can write all
|
|
labels in a lang-file (mergeing it with the existing ones)
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">eTemplates have a name of the form
|
|
app.function[.subtemplate] which is used to call them up
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">they can have further keys, on
|
|
loading the class picks the most appropriate one for a user:
|
|
</p>
|
|
<ol>
|
|
<li><p style="margin-bottom: 0in;">group: the id of a group if the
|
|
template is just for that group (that allows admin to show differnt
|
|
views to each group)
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">lang: the 2 or 5 letter language
|
|
code (or empty for a non-language specific template)
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">template set: they belong too (if
|
|
the template-set key is empty it is an default-template)
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">version: version number like:
|
|
'0.9.15.001'
|
|
</p>
|
|
</li></ol>
|
|
</li><li><p style="margin-bottom: 0in;">they are stored in an array and in
|
|
serialized form in the db-table 'phpgw_etemplate'
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">the dialog editor can dump all
|
|
templates of an app for distribution (so they can be in the CVS too)
|
|
</p>
|
|
</li><li><p>they encapsulate differnt UI (User Interface) types from the
|
|
app: at the moment only a HTML one is ready, but a GTK one (using
|
|
<a href="http://gtk.php.net/" target="_blank">php-gtk</a>, <b>running
|
|
as native app under linux and win32</b>) and XUL is under
|
|
development.<br>Here is a first screenshot of the DB-Tools as native
|
|
Linux Application:
|
|
</p>
|
|
</li></ul>
|
|
<p style="margin-bottom: 0in;"><img src="gtk.png" name="Graphic1" align="bottom" border="0" height="575" width="1049">
|
|
</p>
|
|
<hr>
|
|
<h1>Tutorial / Example: a simple media database</h1>
|
|
<p>As an example we will run now through the necessary steps to
|
|
create a simple media database using eTemplates and other tools and
|
|
classes from the eTemplate app: db-tools and class.so_sql.inc.php.</p>
|
|
<p>Out media database should have the usual fields: name, author,
|
|
description, type: BOOK, CD, VIDEO and should be able to edit records
|
|
and search for them.</p>
|
|
<p>As a preaquistion you need to get / checkout the etemplate app,
|
|
install the app via setup/manage applications and enable your account
|
|
for using the app (Admin/User account: check eTemplates).</p>
|
|
<h2>1. Creating a new eGW app directory</h2>
|
|
<p>Each app need a name, eg. 'et_media'. We now need to create the
|
|
following directory structur above the eGroupWare dir:
|
|
</p>
|
|
<pre>et_media that has to be identical to our app-name
|
|
+ setup files necessary for the setup Programm, give the webserver write-permission to that dir
|
|
+ inc class-files
|
|
+ templates templates, still needed to store the images and get around a lot of complains from the api
|
|
+ default
|
|
+ images here goes our images / icons</pre><h2>
|
|
2. creating et_media/setup/setup.inc.php</h2>
|
|
<p>That files contains the necessary information for setup to install
|
|
the app.
|
|
</p>
|
|
<pre><?php
|
|
$setup_info['et_media']['name'] = 'et_media';
|
|
$setup_info['et_media']['title'] = 'eT-Media';
|
|
$setup_info['et_media']['version'] = '0.9.15.001';
|
|
$setup_info['et_media']['app_order'] = 100; // at the end
|
|
$setup_info['et_media']['tables'] = array('phpgw_et_media');
|
|
$setup_info['et_media']['enable'] = 1;
|
|
|
|
/* Dependencies for this app to work */
|
|
$setup_info['et_media']['depends'][] = array(
|
|
'appname' => 'phpgwapi',
|
|
'versions' => Array('1.2.005','1.2.006')
|
|
);
|
|
$setup_info['et_media']['depends'][] = array( // this is only necessary as long the etemplate-class is not in the api
|
|
'appname' => 'etemplate',
|
|
'versions' => Array('1.2')
|
|
);</pre><h2>
|
|
3. setting up the db-table with the db_tools and setup</h2>
|
|
<p>To enable setup to create a db-table for us and to supply the
|
|
<b>so_sql</b>-class with the necessary information, we need to define
|
|
the type and size of the fields / columns in our db-table.</p>
|
|
<p><br><br>
|
|
</p>
|
|
<p><img src="dbtools.jpg" name="Graphic2" align="left" border="0" height="340" width="950"><br clear="left"><br>We
|
|
can use the db-Tools from the etemplate application to create the
|
|
file for us:
|
|
</p>
|
|
<ol>
|
|
<li><p style="margin-bottom: 0in;">start the etemplate app and click
|
|
on the button up, right which says db-Tools
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">select Application: eT-Media
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">type 'egw_et_media' in the field
|
|
in front of the [Add Table] button and click on the button
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">now use [Add Column] to create the
|
|
necessary fields as shown on the screenshot
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">Click on [Write Table] (you need
|
|
to give the webserver write-permission to the setup-dir of et_media
|
|
or you will get an error message, leave the write-permission as it
|
|
is necessary later on too, click on write again)
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">log out and log into setup and
|
|
start manage applications
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">eT-Media is shown as not installed
|
|
and only install is offerd, check it and submit
|
|
</p>
|
|
</li><li><p>you can now log out from setup, the db-table is now created
|
|
</p>
|
|
</li><li><p>In order to be able to use your eT-Media application, do not
|
|
forget to give yourself access to it (Admin/User account: check
|
|
eT-Media)</p>
|
|
</li></ol>
|
|
<h2>4. creating an eTemplates for the edit-dialog</h2>
|
|
<p>Now we need a nice edit dialog and use the eTemplate editor to set
|
|
it up:
|
|
</p>
|
|
<ol>
|
|
<li><p style="margin-bottom: 0in;">start the etemplate app and type
|
|
<b>'et_media.edit'</b> in the name field. Save the template in order
|
|
to create it</p>
|
|
</li><li><p style="margin-bottom: 0in;">an empty template is displayed. An
|
|
eTemplate can be thought off as a “grid”. The first cell may be
|
|
a bit tricky to find, but will be highlighted when moving the mouse
|
|
over it. On my computer this cell appears in pink as illustrated
|
|
below:</p>
|
|
</li><li><p style="margin-bottom: 0in;"><img src="step0.jpg" name="Graphic3" align="left" border="0" height="509" width="922"><br clear="left">Double
|
|
click on the pink spot will bring the following dialog:</p>
|
|
</li><li><p style="margin-bottom: 0in;"><img src="step1.jpg" name="Graphic7" align="left" border="0" height="544" width="851"><br clear="left">The
|
|
top row allows you to add column and rows to the template. We will
|
|
need 2 columns and 6 rows</p>
|
|
</li><li><p style="margin-bottom: 0in;">Create the following label in the
|
|
first top left cell:</p>
|
|
</li></ol>
|
|
<p style="margin-bottom: 0in;"><img src="step2.jpg" name="Graphic8" align="left" border="0" height="533" width="853"><br clear="left"><br>
|
|
</p>
|
|
<p style="margin-bottom: 0in;"><br>
|
|
</p>
|
|
<ol start="6">
|
|
<li><p>In the top right cell, we will create a user entry and call
|
|
it “name”: this is the same name as thee column in our
|
|
egw_et_media table. This is important as those fields will be
|
|
populated automatically for us by eGroupWare:</p>
|
|
</li><li><p><img src="step3.jpg" name="Graphic9" align="left" border="0" height="560" width="852"><br clear="left">Complete
|
|
the template as follows. The widget used for “type” is a
|
|
Selectbox, the one used for “description” is a textarea. Note
|
|
that the name of the input is “descr” and not description, as
|
|
this is the name of the column in the table. Finally on the last row
|
|
we have two widgets of type “Submitbutton” of names “read”
|
|
and “save” and of corresponding label.</p>
|
|
<p><img src="step4.jpg" name="Graphic4" align="left" border="0" height="380" width="922"><br clear="left"></p>
|
|
</li></ol>
|
|
<p>Then before moving to the next stage save the template as an XML
|
|
file by clicking on “Export XML”. Once again the server must have
|
|
write permissions on the directory.</p>
|
|
<h2>5. Setting up the index page</h2>
|
|
<p>The index page is only used if someone clicks on the navbar icon
|
|
(or on the black cross as we haven't supplied one so far).<br>Create
|
|
the file <b>/et_media/index.php</b> with the following content:</p>
|
|
<pre><?php
|
|
$GLOBALS['phpgw_info']['flags'] = array(
|
|
'currentapp' => 'et_media',
|
|
'noheader' => True,
|
|
'nonavbar' => True
|
|
);
|
|
include('../header.inc.php');
|
|
$GLOBALS['egw']->redirect_link('/index.php', 'menuaction=raphatest.ui_et_media.edit');
|
|
</pre><h2>
|
|
6. The code for our application</h2>
|
|
<p>An eGroupWare application is organised around 3 application
|
|
layers:</p>
|
|
<ol>
|
|
<li><p>the storage layer, managed by a “Storage Object” (so).
|
|
This object is responsible for handling all access to the storage
|
|
engine</p>
|
|
</li><li><p>the business layer, managed by a “Business Ojbect” (bo).
|
|
This object is responsible for all the business logic</p>
|
|
</li><li><p>the user interface layer, managed by a “User Interface”
|
|
(ui) object. This object is responsible for all interaction with the
|
|
user, including displaying and gathering data to and from the user</p>
|
|
</li></ol>
|
|
<p>For this, we create 3 files in the “inc” directory, called
|
|
class.so.et_media.inc.php, class.bo_et_media.inc.php,
|
|
class.ui_et_media.inc.php. In this simple application, the bo and so
|
|
layers will be fairly minimal, this said it is a good idea to create
|
|
the application using the right standards from the start.</p>
|
|
<p>Here is the file <b>/et_media/inc/class.so_et_media.inc.php</b>:</p>
|
|
<pre><?php
|
|
include_once(PHPGW_INCLUDE_ROOT . '/etemplate/inc/class.so_sql.inc.php');
|
|
|
|
/**
|
|
* General storage class for et_media
|
|
*/
|
|
class so_et_media extends so_sql
|
|
{
|
|
function so_et_media()
|
|
{
|
|
$this->so_sql('et_media','egw_et_media');
|
|
$this->empty_on_write = "''";
|
|
}
|
|
}</pre><p>
|
|
<br><br>
|
|
</p>
|
|
<p>The file <b>/et_media/inc/class.bo_et_media.inc.php</b>:</p>
|
|
<pre><?php
|
|
/**
|
|
* Business Object for et_media
|
|
*/
|
|
class bo_et_media
|
|
{
|
|
var $types = array(
|
|
'' => 'Select one ...',
|
|
'cd' => 'Compact Disc',
|
|
'dvd' => 'DVD',
|
|
'book' => 'Book',
|
|
'video' => 'Video Tape'
|
|
);
|
|
|
|
function bo_et_media()
|
|
{
|
|
$this->so =& CreateObject('et_media.so_et_media');
|
|
}
|
|
|
|
function save($content)
|
|
{
|
|
$this->so->save($content);
|
|
}
|
|
|
|
function read($content)
|
|
{
|
|
$this->so->search($content);
|
|
}
|
|
}</pre><p>
|
|
<br><br>
|
|
</p>
|
|
<p>And finally the start of the
|
|
<b>/et_media/inc/class.ui_et_media.inc.php</b>:</p>
|
|
<pre><?php
|
|
/**************************************************************************\
|
|
* eGroupWare - eTemplates - Tutoria Example - a simple MediaDB *
|
|
* http://www.eGroupWare.org *
|
|
* Written by Ralf Becker <RalfBecker AT outdoor-training DOT de> *
|
|
* -------------------------------------------- *
|
|
* This program is free software; you can redistribute it and/or modify it *
|
|
* under the terms of the GNU General Public License as published by the *
|
|
* Free Software Foundation; either version 2 of the License, or (at your *
|
|
* option) any later version. *
|
|
\**************************************************************************/
|
|
|
|
/* $ Id: class.et_media.inc.php,v 1.2 2002/10/19 11:11:03 ralfbecker Exp $ */
|
|
|
|
class ui_et_media
|
|
{
|
|
var $public_functions = array(
|
|
"edit" => True,
|
|
"writeLangFile" => True
|
|
);</pre><p>
|
|
The $public_functions array defines which public functions can be
|
|
accessed by the user.</p>
|
|
<p>The constructor initialises the template engine and the Business
|
|
Object:</p>
|
|
<pre> function ui_et_media()
|
|
{
|
|
$this->tmpl =& CreateObject('etemplate.etemplate', 'et_media.edit');
|
|
$this->bo =& CreateObject('et_media.bo_et_media');
|
|
$this->html =& $GLOBALS['egw']->html;
|
|
|
|
if(!@is_object($GLOBALS['egw']->js))
|
|
{
|
|
$GLOBALS['egw']->js =& CreateObject('phpgwapi.javascript');
|
|
}
|
|
|
|
}</pre><p>
|
|
<br><br>
|
|
</p>
|
|
<p>Finally, the edit function is the one which does all the work from
|
|
a user perspective.</p>
|
|
<pre>function edit($content='')
|
|
{
|
|
if (is_array($content)) // we are called as a call back
|
|
{
|
|
$r_id = $content['id'];
|
|
if ($r_id>0) // if we have an id -> read the entry
|
|
{
|
|
$content = $this->bo->read($content['id']);
|
|
}
|
|
|
|
if (isset($content['save']))
|
|
{
|
|
unset($content['save']);
|
|
$msg .= (!$this->bo->save($content))?lang('Entry Saved'):lang('Error: while saving');
|
|
}
|
|
elseif (isset($content['read']))
|
|
{
|
|
unset($content['id']);
|
|
unset($content['read']);
|
|
$found = $this->bo->so->search($content, False, 'name, author');
|
|
|
|
if (!$found)
|
|
{
|
|
$msg .= lang('Nothing matched the search criteria');
|
|
}
|
|
else
|
|
{
|
|
$content = $found[0];
|
|
}
|
|
}
|
|
}
|
|
else
|
|
{
|
|
$content = array();
|
|
}
|
|
|
|
//now we fill the content array for the next call to etemplate.exec
|
|
|
|
$content = $content + array (
|
|
'msg' => $msg
|
|
);
|
|
|
|
$sel_options = array(
|
|
'type' => $this->bo->types
|
|
);
|
|
|
|
$no_button = array(
|
|
);
|
|
$preserv = array(
|
|
'id' => $this->data['id']
|
|
);
|
|
|
|
$this->tmpl->exec(
|
|
'et_media.ui_et_media.edit', // setting this function as the callback
|
|
$content,$sel_options, $no_button,$preserv
|
|
);
|
|
}
|
|
}</pre><p>
|
|
The edit function is called from our index.php file or as callback
|
|
for this form / dialog. In that case $content is an array with the
|
|
content the user put into the fields of the dialog.</p>
|
|
<p>Let first have a look what happend if we called the first time (or
|
|
what we do to show the dialog again with the changed data):</p>
|
|
<ol>
|
|
<li><p style="margin-bottom: 0in;">the $content array is set up with
|
|
our internal data-array (which is empty on the first call) and the
|
|
message
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">$sel_options has the options for
|
|
our selectbox: the options are an array where the keys are the
|
|
values returned by the selectbox and the values are what the
|
|
selectbox shows to the user. As we can have more than one selectbox
|
|
in a dialog, the key in $sel_options need to be the same as the name
|
|
of the selectbox.
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">$readonlys: if a fieldname is set
|
|
in $readonlys to True, its content is showed readonly (for regular
|
|
fields like type Text) or left out for buttons (we use this later to
|
|
show the delete-button only when an entry is loaded)
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">the array $preserv is preserved,
|
|
which means its stored in the app's session-data and is delivered
|
|
back like the content of the fields to the callback-function. We use
|
|
it here to store the id of the entry. This is similar to use a
|
|
hidden input-field in a form, but it does not need to be serialized
|
|
by the app and is NOT transmitted to the user and back.
|
|
</p>
|
|
</li><li><p>at last we call etemplate::exec to show the template with the
|
|
content from $content and set the function itself as callback for
|
|
the dialog / form.
|
|
</p>
|
|
</li></ol>
|
|
<p>Now let's have a look what happens if the user submits the form
|
|
and our callback is called:
|
|
</p>
|
|
<ol>
|
|
<li><p style="margin-bottom: 0in;">the callback (this function) is
|
|
not the submit-address of the form, the form get's always submitted
|
|
to the function <b>process_exec</b> of the etemplate class. This
|
|
function changes for some field-types the content (eg. a date-field
|
|
consists of 3 single fields, process_exec takes care that it is
|
|
delivered back as timestamp, as we set it in content before). It can
|
|
even submit the form back to the user if for a address-selection a
|
|
search for a pattern has to be performed and the matches are shown
|
|
to the user. In this case the callback is NOT called. The same is
|
|
true if an int field contains letters or is not within the minimum
|
|
or maximum set. <i>Not all of the is allready working, it will
|
|
follow in the next days/weeks.</i><br>For the specialist
|
|
process_exec uses $_POST and ignores $_GET set as query in the url.
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">the so_sql function data_merge,
|
|
copies all values from $content, which are columns in the db-table,
|
|
in our internal data array. Values which are not real data, like
|
|
buttons pressed are not copied (!).
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">if $content['save'] is set, the
|
|
[Save] button has been pressed ('save' is the name NOT the label of
|
|
the save button), in that case we use so_sql's save function to save
|
|
the content of our internal data-array to the db.
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">the same check is used for the
|
|
[Read]: we uses the content of all fields to search db for matching
|
|
entries. The user can use wildcards to perform a search on all
|
|
field. The wildcards are '*' and '?', so_sql translates them into
|
|
sql-wildcards.
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">if the search return False we just
|
|
set our message var.
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">if something is found we use
|
|
so_sql's init-function to set the data of the first match. Lateron
|
|
we will show a list if more than one entry is found.
|
|
</p>
|
|
</li><li><p>after that the content array is filled again as discriped
|
|
above.
|
|
</p>
|
|
</li></ol>
|
|
<p>Now we are able to store entries in the db and retrive them by
|
|
searching the database for patterns in the different fields. You can
|
|
try your new application now. You can create new records and save
|
|
them. By just entering the name or author, the database will find the
|
|
corresponding match and populate the form for you.</p>
|
|
<p><br>We are only lacking some way to show if we get more than one
|
|
match on a search, that's what we are going to implement next:</p>
|
|
<h2>7. adding a list-dialog for the search-function</h2>
|
|
<p>First we need to create an other eTemplate to show the list:
|
|
<b>'et_media.show'</b> as follows. This is made of a label of name
|
|
“msg” (to display messages), an HorizontalRule widget, and a
|
|
Template widget: we will use a “sub template” called
|
|
et_media.show.rows to display the rows of the search function. I have
|
|
set the option of the template widget to “entry” as this is the
|
|
name we will use to access to the data in the sub-template.
|
|
</p>
|
|
<p style=""><img src="step5.jpg" name="Graphic5" align="left" border="0" height="561" width="843"><br clear="left"><br><br>
|
|
</p>
|
|
<p style="">The 'et_media.show.rows' template is
|
|
created as a 3x2 table. On the header row, two labels “Name” and
|
|
“Author” and one empty cell.</p>
|
|
<p><span style="">On the second row, two labels of
|
|
name ${row}[name]</span> and ${row}[author]. In the last cell a
|
|
submitButton of label “Edit” and of name “edit[$row_cont[id]]”
|
|
</p>
|
|
<p><img src="step6.jpg" name="Graphic6" align="left" border="0" height="515" width="847"><br clear="left"><br><br>
|
|
</p>
|
|
<p>The class of the header row is “nmh” and the class of the
|
|
content row is “nmr”. eTemplate will automatically vary the
|
|
colors of the “nmr” class to provide a nice visual effect.</p>
|
|
<p>Here is a view of the et_media.show template once the two
|
|
templates have been created:</p>
|
|
<p><img src="step7.jpg" name="Graphic10" align="left" border="0" height="419" width="950"><br clear="left"><br><br>
|
|
</p>
|
|
<p>We need some code / a function in the class to call the template
|
|
and fill the content:</p>
|
|
<pre> function show($found)
|
|
{
|
|
if (!is_array($found) || !count($found))
|
|
{
|
|
$this->edit();
|
|
return;
|
|
}
|
|
reset($found); // create array with all matches, indexes starting with 1
|
|
for ($row=1; list($key,$data) = each($found); ++$row)
|
|
{
|
|
$entry[$row] = $data;
|
|
}
|
|
$content = array(
|
|
'msg' => lang('%d matches on search criteria',count($found)),
|
|
'entry' => $entry // et_media.show.rows uses this, as we put 'entry' in the Options-field
|
|
);
|
|
$this->tmpl->read('et_media.show'); // read the show-template
|
|
|
|
$this->tmpl->exec('et_media.ui_et_media.edit',$content); // exec it with the edit-function as callback
|
|
}</pre><p>
|
|
This function is called by edit with the matches of a search:</p>
|
|
<ol>
|
|
<li><p style="margin-bottom: 0in;">We build an array with all the
|
|
matches, the index in that array is the row-number starting with 1
|
|
(!) ($entry = array('empty') + $found; would do the same).<br>The
|
|
names in the data-row (last row) of 'et_media.show.rows' are like
|
|
'${row}[name]'. Variable expansion is performed on each name and
|
|
expands that for the first row to '1[name]' which addresses the name
|
|
in the first match.
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">$content contains again 'msg'
|
|
which we set to the number of entris found and the above array with
|
|
the data of all rows under the key 'entry', as we put that in
|
|
Options for the field loading the sub-template 'et_media.show.rows'.
|
|
It not necessary to put something in Options-field / use a sub-array
|
|
for a sub-template, but it can be very helpful to organize a complex
|
|
content-array. (As an exercice you can remove 'entry' from the
|
|
Options-field and change the function arrcordingly).
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">we now explizitly read the
|
|
template 'et_media.show' (the constructor reed 'et_media.edit') and
|
|
execute it again with the edit function as callback (because of
|
|
that, show does NOT need to be listed in public_functions)
|
|
</p>
|
|
</li><li><p>as 'et_media.show.rows' contains only one data-row, but
|
|
fieldnames with variables to expand, that row is autorepeated for as
|
|
many data we put into the content array (or the sub-array if we used
|
|
the Options-field).
|
|
</p>
|
|
</li></ol>
|
|
<p>To call the show function, we need to make some changes to the
|
|
edit-function too:</p>
|
|
<pre> elseif (isset($content['read']))
|
|
{
|
|
unset($content['id']); // not set by user, so dont use for seach
|
|
$found = $this->search($content,False,'name,author'); // searches by using the no-empty fields
|
|
|
|
if (!$found) // search returned empty
|
|
{
|
|
$msg .= lang('Nothing matched search criteria !!!');
|
|
}
|
|
elseif (count($found) == 1) // only one match --> show it in the editor
|
|
{
|
|
$this->init($found[0]);
|
|
}
|
|
else // multiple matches --> use the show function/template
|
|
{
|
|
$this->show($found);
|
|
return;
|
|
}
|
|
}
|
|
elseif (isset($content['entry']['edit'])) // the callback from for the show function/template
|
|
{ // the id is set via the button name of '$row_cont[id]'
|
|
list($id) = each($content['entry']['edit']); // note its not only ['edit'] !!!
|
|
if ($id > 0)
|
|
{
|
|
$content = $this->bo->so->read(array('id' => $id));
|
|
}
|
|
}</pre>
|
|
<ol>
|
|
<li><p style="margin-bottom: 0in;">the first part should be
|
|
self-explaining, we call show with $found if it contain more than
|
|
one entry.
|
|
</p>
|
|
</li><li><p>The show function uses edit as callback, the [Edit] buttons
|
|
in each row has 'edit[$row_cont[id]]' as name. If an [Edit] button
|
|
is pressed $content['entry']['edit'] is set to the id of the entry
|
|
of that row. We use that id to read the whole entry.
|
|
</p>
|
|
</li></ol>
|
|
<p>This is what the new “show” template looks like:</p>
|
|
<p><img src="step8.jpg" name="Graphic11" align="left" border="0" height="349" width="950"><br clear="left"><br><br>
|
|
</p>
|
|
<p>While makeing this changes we can add a [Cancel] and [Delete]
|
|
button too:</p>
|
|
<pre> elseif (isset($content['cancel']))
|
|
{
|
|
$content = array(); // clear the contents
|
|
}
|
|
elseif (isset($content['delete']))
|
|
{
|
|
$this->bo->so->delete($r_id);
|
|
$content = array(); // clear the content
|
|
}
|
|
|
|
|
|
$no_button = array( // no delete button if id == 0 --> entry not saved
|
|
'delete' => !$this->content['id'];
|
|
);</pre>
|
|
<ol>
|
|
<li><p style="margin-bottom: 0in;">on cancel we just clear the
|
|
internal data-array with so_sql's init function.
|
|
</p>
|
|
</li><li><p style="margin-bottom: 0in;">on delete we have to call so_sql's
|
|
delete before (it deletes the db-row coresponding with our internal
|
|
data-array)
|
|
</p>
|
|
</li><li><p>the last block checks if the id field is set (it can only be
|
|
set by a read or save) and disables the [Delete] button if not
|
|
($this->db_key_cols[$this->autoinc_id] == 'id').
|
|
</p>
|
|
</li></ol>
|
|
<p>Of course we have to add this buttons to the template
|
|
'et_media.edit'. I trust you can add 2 Submitbuttons with the names
|
|
'cancel' and 'delete', a Label and a nice helpmessages by now without
|
|
looking at a screenshot ;-).</p>
|
|
<h2>8. creating the english lang-file</h2>
|
|
<p>To get rid of the stars '*' behind each Label and to be able to
|
|
translate the app in other languages we need to create a
|
|
lang-file<br>There are 2 possibilties to create it automaticaly:</p>
|
|
<ol>
|
|
<li><p style="margin-bottom: 0in;">Use the [Write Langfile] button in
|
|
the eTemplate editor (put the app-name 'et_media' in the name-field
|
|
first)<br>That will omitt our own messages in the class!!!
|
|
</p>
|
|
</li><li><p>We use a function in our class to call
|
|
etemplate::writeLangFile('et_media','en',$extra) and can so supply
|
|
some extra strings.<br>If we add this function to the
|
|
public_functions-array in our class, we can just call this function
|
|
via the
|
|
browser:<br>http://ourDomain/eGroupWare/index.php?menuaction=et_media.et_media.writeLangFile
|
|
(the errormsg can be savely ignored)<br>This is the function (don't
|
|
forget to add it like the edit-function to public_functions):
|
|
</p>
|
|
</li></ol>
|
|
<p>Anyway we have to use the TranslationTools to find and write the
|
|
lang()-messages of our code!</p>
|
|
<pre> /*!
|
|
@function writeLangFile
|
|
@abstract writes langfile with all templates registered here
|
|
@discussion can be called via [write Langfile] in eTemplate editor
|
|
*/
|
|
function writeLangFile()
|
|
{
|
|
return $this->tmpl->writeLangFile('et_media','en',$this->types);
|
|
}</pre><h2>
|
|
9. dumping the eTemplate to a file for distribution</h2>
|
|
<p>To be able to put the eTemplates in CVS and to ship them with your
|
|
app, you need to dump them in a file first.
|
|
</p>
|
|
<p>This is done in the eTemplate editor by putting the app-name or an
|
|
template-name in the Name field and clicking on the button
|
|
[Dump4Setup]. This creates the file
|
|
<b>et_media/setup/etemplates.inc.php</b>. The etemplate-class loads
|
|
this file whenever it finds a new version automaticaly.</p>
|
|
<h2>10. further information</h2>
|
|
<ol>
|
|
<li><p style="margin-bottom: 0in;">the <a href="reference.html">reference-documentation</a>
|
|
of the eTemplates</p></li>
|
|
<li><p style="margin-bottom: 0in;">for all functions and parameters
|
|
of the <b>etemplate</b>-class(es) look in the
|
|
<a href="http://www.egroupware.org/egwdoc/li_etemplate.html" target="_blank">phpDocumentor docu of etemplate</a>
|
|
created from comments (yes there are comments) in the sources:
|
|
</p>
|
|
<ul>
|
|
<li><p style="margin-bottom: 0in;"><a href="http://www.egroupware.org/egwdoc/etemplate/api/etemplate.html" target="_blank">class.uietemplate.inc.php</a>
|
|
for the exec function</p></li>
|
|
<li><p style="margin-bottom: 0in;"><a href="http://www.egroupware.org/egwdoc/etemplate/api/boetemplate.html" target="_blank">class.boetemplate.inc.php</a>
|
|
for the variable replacement in names and about the autorepeat rows and columns</p></li>
|
|
<li><p style="margin-bottom: 0in;"><a href="http://www.egroupware.org/egwdoc/etemplate/api/boetemplate.html" target="_blank">class.soetemplate.inc.php</a>
|
|
for writeLangFile and all functions to read, store and dump an eTemplate</p></li>
|
|
</ul></li>
|
|
<li><p style="margin-bottom: 0in;">for all functions and parameters
|
|
of the <b>so_sql</b>-class look in the comments of the file
|
|
<a href="http://www.egroupware.org/egwdoc/etemplate/api/so_sql.html" target="_blank">class.so_sql.inc.php</a></p>
|
|
</li><li><p>for setup, the necessary files of an app or the format of
|
|
tables_current.inc.php look at the exelent <a href="../../setup/doc/setup3.html">docu
|
|
of setup3</a> in the doc-dir of the setup app.
|
|
</p>
|
|
</li></ol>
|
|
<h2><i>That's it</i> - please <a href="#" onclick="document.location='mai'+'lto:RalfBecker'+unescape('%40')+'outdoor-training'+unescape('%2E')+'de'; return false;">contact
|
|
me</a> if you have further questions or comments about the tutorial</h2>
|
|
</body></html> |