From 33a0f786bdd794c09878f37359850134fd3bbe63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hans-J=C3=BCrgen=20Tappe?= Date: Sun, 7 Nov 2010 13:25:00 +0000 Subject: [PATCH] - Add hint on how to revert changes / reset an eTemplate change as discussed on the developer's list. - Fix typos - Add a reference from the reference.html to the now existing etemplate documentation. --- etemplate/doc/etemplate.html | 165 +++++++++++++++++++---------------- etemplate/doc/reference.html | 4 +- 2 files changed, 94 insertions(+), 75 deletions(-) diff --git a/etemplate/doc/etemplate.html b/etemplate/doc/etemplate.html index 5d5e9c4c35..c4d8859098 100644 --- a/etemplate/doc/etemplate.html +++ b/etemplate/doc/etemplate.html @@ -16,7 +16,7 @@

eTemplate - Templates and Dialog-Editor for eGroupWare

by Ralf Becker RalfBecker AT outdoor-training DOT de

-

Updated by Raphael Alla >raphael AT olineopensolutions +

Updated by Raphael Alla raphael AT olineopensolutions DOT com

A developers tutorial how to write an application with the new eTemplates.
It is also an introduction how to write a eGW- and setup(3)-compatible app.

@@ -28,13 +28,13 @@ It is also an introduction how to write a eGW- and setup(3)-compatible app.

  • consist out of rows and cols with input-fields of several types
  • there is a dialog-editor (one part of the etemplate-app) to create the eTemplate
  • eTemplates can be (and are usually) nested, eg. a template-field can contain an other eTemplate
    • -
  • each field / cell of the template can have a label which is automaticaly run through lang() (the +
  • each field / cell of the template can have a label which is automatically run through lang() (the content of the field can be run through lang() too)
    • -
  • the dialog editor can write all labels in a lang-file (mergeing it with the existing ones)
    • +
  • the dialog editor can write all labels in a lang-file (merging it with the existing ones)
  • eTemplates have a name of the form app.function[.subtemplate] which is used to call them up
  • they can have further keys, on loading the class picks the most appropriate one for a user:
      -
    1. group: the id of a group if the template is just for that group (that allows admin to show differnt +
    2. group: the id of a group if the template is just for that group (that allows admin to show different views to each group)
    3. lang: the 2 or 5 letter language code (or empty for a non-language specific template)
    4. template set: they belong too (if the template-set key is empty it is an default-template)
      5. @@ -43,9 +43,9 @@ It is also an introduction how to write a eGW- and setup(3)-compatible app.

    5. they are stored in an array and in serialized form in the db-table 'egw_etemplate'
    6. the dialog editor can dump all templates of an app for distribution (so they can be in the CVS too)
      7. -

    7. they encapsulate differnt UI (User Interface) types from the app: at the moment only a HTML one is ready, +

    8. they encapsulate different UI (User Interface) types from the app: at the moment only a HTML one is ready, but a GTK one (using php-gtk, running - as native app under linux and win32) and XUL is under development.
      Here is a first screenshot of the DB-Tools as native + as native app under Linux and win32) and XUL is under development.
      Here is a first screenshot of the DB-Tools as native Linux Application:

      9. @@ -58,20 +58,20 @@ classes from the eTemplate app: db-tools and class.so_sql.inc.php.

      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.

      -

      As a preaquistion you need to get / checkout the etemplate app, +

      As a pre-acquistion 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).

      1. Creating a new eGW app directory

      Each app need a name, eg. 'et_media'. We now need to create the -following directory structur above the eGroupWare dir: +following directory structure above the eGroupWare dir:

      -
      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
+
      et_media                           that has to be identical to our app-name
+        + setup                         files necessary for the setup program, 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
+        + 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
      
-2. creating et_media/setup/setup.inc.php
      
+2. Creating et_media/setup/setup.inc.php

    • That files contains the necessary information for setup to install the app.

    @@ -92,7 +92,7 @@ the app. 'appname' => 'etemplate', 'versions' => Array('1.2','1.3','1.4') );

    -3. setting up the db-table with the db_tools and setup

    +3. Setting up the db-table with the db_tools and setup

    To enable setup to create a db-table for us and to supply the so_sql-class with the necessary information, we need to define the type and size of the fields / columns in our db-table.

    @@ -106,23 +106,23 @@ file for us:
  • start the etemplate app and click on the button up, right which says db-Tools
  • select Application: eT-Media
  • type 'egw_et_media' in the field in front of the [Add Table] button and click on the button
    • -
  • now use [Add Column] to create thenecessary fields as shown on the screenshot
    • +
  • now use [Add Column] to create the necessary fields as shown on the screenshot
  • 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)
  • log out and log into setup and start manage applications
    • -
  • eT-Media is shown as not installed and only install is offerd, check it and submit
    • +
  • eT-Media is shown as not installed and only install is offered, check it and submit

  • you can now log out from setup, the db-table is now created

  • 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)

    • -

    4. creating an eTemplates for the edit-dialog

    +

    4. Creating an eTemplates for the edit-dialog

    Now we need a nice edit dialog and use the eTemplate editor to set it up:

    1. start the etemplate app and type 'et_media.edit' in the name field. Save the template in order to create it
      2. -
    2. an empty template is displayed. An eTemplate can be thought off as a “grid”. The first cell may be +
    3. 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:

    4. Double @@ -136,20 +136,20 @@ it up:

        -
      1. 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 +
      2. 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:

      3. -

        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 +

        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.

        + we have two widgets of type "Submitbutton" of names "read" + and "save" and of corresponding label.


      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 +file by clicking on "Export XML". Once again the server must have write permissions on the directory.

      5. Setting up the index page

      The index page is only used if someone clicks on the navbar icon @@ -164,30 +164,30 @@ the file /et_media/index.php with the following content:

      include('../header.inc.php'); $GLOBALS['egw']->redirect_link('/index.php', 'menuaction=et_media.ui_et_media.edit'); -

      6. The code for our application

      -

      An eGroupWare application is organised around 3 application +

      6. The code for our Application

      +

      An eGroupWare application is organized around 3 application layers:

      • - the storage layer, managed by a “Storage Object” (so). + the storage layer, managed by a "Storage Object" (so). This object is responsible for handling all access to the storage engine. We use the "stock" so_sql class for this, so we need no extra so-object for the moment.
      • - the business layer, managed by a “Business Ojbect” (bo). + the business layer, managed by a "Business Object" (bo). This object is responsible for all the business logic. The business object can extend the storage object, to avoid passing the so-methods as stubs to the ui layer.
      • - the user interface layer, managed by a “User Interface” + 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. The ui object can extend the bo-object.
      -

      For this, we create 2 files in the “inc” directory, called +

      For this, we create 2 files in the "inc" directory, called class.bo_et_media.inc.php and class.ui_et_media.inc.php. In this simple application, the bo layer will be fairly minimal, this said it is a good idea to create the application using the @@ -214,7 +214,7 @@ include_once(EGW_INCLUDE_ROOT . '/etemplate/inc/class.so_sql.inc.php'); class bo_et_media extends so_sql { /** - * Availible media types + * Available media types * * @var array */ @@ -226,7 +226,7 @@ class bo_et_media extends so_sql 'video' => 'Video Tape' ); /** - * Constructor initialising so_sql + * Constructor initializing so_sql * * @return so_et_media */ @@ -273,7 +273,7 @@ class ui_et_media extends bo_et_media { $this->bo_et_media(); // calling the constructor of the extended bo object - $this->tmpl =& CreateObject('etemplate.etemplate','et_media.edit'); + $this->tmpl =& CreateObject('etemplate.etemplate','et_media.edit'); } /** @@ -300,7 +300,7 @@ class ui_et_media extends bo_et_media } } - // now we filling the content array for the next call to etemplate.exec + // now we fill in the content array for the next call to etemplate.exec $content = $this->data + array( 'msg' => $msg @@ -317,7 +317,7 @@ class ui_et_media extends bo_et_media 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.

      -

      Let first have a look what happend if we called the first time (or +

      Let first have a look what happened if we called the first time (or what we do to show the dialog again with the changed data):

      1. the $content array is set up with our internal data-array (which is empty on the first call) and the message
        2. @@ -326,7 +326,7 @@ what we do to show the dialog again with the changed data):

        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. -
      2. $readonlys: if a fieldname is set in $readonlys to True, its content is showed readonly +
      3. $readonlys: if a field name 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)
      4. the array $preserv is preserved, which means its stored in the app's session-data and is delivered @@ -352,7 +352,7 @@ and our callback is called: 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. Not all of the is allready working, it will + or maximum set. Not all of the is already working, it will follow in the next days/weeks.
        For the specialist process_exec uses $_POST and ignores $_GET set as query in the url.
      5. the so_sql function data_merge, copies all values from $content, which are columns in the db-table, @@ -365,39 +365,39 @@ and our callback is called: entries. The user can use wildcards to perform a search on all field. The wildcards are '*' and '?', so_sql translates them into sql-wildcards.
      6. if the search return False we just set our message var.
        7. -
      7. if something is found we use so_sql's init-function to set the data of the first match. Lateron +
      8. if something is found we use so_sql's init-function to set the data of the first match. Later on we will show a list if more than one entry is found.
        9. -

      9. after that the content array is filled again as discriped above.

        10. +

      10. after that the content array is filled again as described above.

      -

      Now we are able to store entries in the db and retrive them by +

      Now we are able to store entries in the db and retrieve 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.


      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:

      -

      7. adding a list-dialog for the search-function

      +

      7. Adding a list-dialog for the search-function

      First we need to create an other eTemplate to show the list: 'et_media.show' 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 +"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 +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.




      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.

      +created as a 3x2 table. On the header row, two labels "Name" and +"Author" and one empty cell.

      ond row, two labels of name ${row}[name] and ${row}[author]. In the last cell a -submitButton of label “Edit” and of name “edit[$row_cont[id]]” +submitButton of label "Edit" and of name "edit[$row_cont[id]]"




      -

      The class of the header row is “th” and the class of the -content row is “row”. eTemplate will automatically vary the -colors of the “row” class to provide a nice visual effect.

      +

      The class of the header row is "th" and the class of the +content row is "row". eTemplate will automatically vary the +colors of the "row" class to provide a nice visual effect.

      Here is a view of the et_media.show template once the two templates have been created:




      @@ -436,17 +436,17 @@ This function is called by edit with the matches of a search:

      '${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.
      5. -
    5. $content contains again 'msg' which we set to the number of entris found and the above array with +
    6. $content contains again 'msg' which we set to the number of entries 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).
      7. -
    7. we now explizitly read the template 'et_media.show' (the constructor reed 'et_media.edit') and + content-array. (As an exercise you can remove 'entry' from the + Options-field and change the function accordingly).
      8. +
    8. we now explicitly 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)
      9. -
    9. as 'et_media.show.rows' contains only one data-row, but fieldnames with variables to expand, that row is autorepeated for as +
    10. as 'et_media.show.rows' contains only one data-row, but field names with variables to expand, that row is auto-repeated for as many data we put into the content array (or the sub-array if we used the Options-field).

    To call the show function, we need to make some changes to the @@ -454,7 +454,7 @@ edit-function too:

     			elseif (isset($content['read']))
 			{
-				unset($content['id']);					// not set by user, so dont use for seach
+				unset($content['id']);					// not set by user, so don't use for search
 				unset($content['read']);
 				$found = $this->search($content,False,'name,author');	// searches by using the no-empty fields
 
@@ -489,10 +489,10 @@ edit-function too:
    
 		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.
 
-
    This is what the new “show” template looks like:
    
+
    This is what the new "show" template looks like:
    
 



    
 
    
-
    While makeing this changes we can add a [Cancel] and [Delete]
+
    While making these changes we can add a [Cancel] and [Delete]
 button too:
    
 
     			elseif (isset($content['cancel']))
@@ -511,39 +511,57 @@ button too:
    
 
    
 
      
 	
    1. on cancel we just clear the internal data-array with so_sql's init function.
      2. 
-	
    2. on delete we have to call so_sql's delete before (it deletes the db-row coresponding 
+	
    3. on delete we have to call so_sql's delete before (it deletes the db-row corresponding 
 		with our internal data-array)
      4. 
 	
    4. 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').
      5. 
 
    
 
    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
+'et_media.edit'. I trust you can add 2 submit buttons with the names
+'cancel' and 'delete', a Label and a nice help messages by now without
 looking at a screenshot ;-).
    
-
    8. creating the english lang-file
    
+
    The eTemplate is saved in the eGroupware database. If changes done to the
+eTemplate should be reverted, a eTemplate setup file is
+required, see section Dumping the eTemplate to a File for Distribution.
+Note that reverting only works if
+a valid version has previously been dumped to a distribution file or if a new
+revision identifier of the template has been used to save the changes.
    
+
    8. Creating the English lang-file
    
 
    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
    There are 2 possibilties to create it automaticaly:
    
+lang-file
    There are 2 possibilities to create it automatically:
    
 
      
 	
    1. Use the [Write Langfile] button in the eTemplate editor (put the app-name 'et_media' in the name-field
 		first)
      That will NOT write the messages in the classes!!!
      2. 
 	
    2. We can use the TranslationTools to scans our sources for lang('...') calls ([search new phrases] button).
      3. 
 	
    3. Other phrases like the media types can be added manually via [Add] button in the Translation Tools.
      4. 
 
    
-
    9. dumping the eTemplate to a file for distribution
    
+
    9. Dumping the eTemplate to a File for Distribution
    
 
    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. 
 
    
 
    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
-et_media/setup/etemplates.inc.php. The etemplate-class loads
-this file whenever it finds a new version automaticaly.
    
-
    10. further information
    
-
    Please note: all files of the et_media example can be found in the et_media sub-direcotry of
+et_media/setup/etemplates.inc.php. The eTemplate-class loads
+this file whenever it finds a new version automatically.
    
+
    To recover a changed eTemplate to the state saved in the distribution file, the following
+steps need to be performed:
    
+
      
+	
    • Remove the modified template (or the modified version of the template)
+		in the eTemplate application
      • 
+	
    • Touch the setup/etemplates.inc.php file in the application directory
+	(update it's timestamp).
      • 
+
    
+
    In case the modification was done in a sub-template, e.g. the
+definition of the rows in a list view, the correct (sub-) template name and
+version needs to be chosen for deletion. It is visible in the edit window of the
+elements modified.
    
+
    10. Further information
    
+
    Please note: All files of the et_media example can be found in the et_media sub-directory of
 etemplate's doc directory. Symlinking or coping to the eGroupWare install directory, allows to 
-immediatly install it via setup.
    
+immediately install it via setup.
    
 
      
 	
    1. the reference-documentation of the eTemplates
      2. 
 	
    2. for all functions and parameters of the etemplate-class(es) look in the 
@@ -561,10 +579,11 @@ immediatly install it via setup.
      
 	
    3. for all functions and parameters of the so_sql-class look in the comments of the file
 		class.so_sql.inc.php
      4. 
 	
    4. for setup, the necessary files of an app or the format of
-		tables_current.inc.php look at the exelent docu
+		tables_current.inc.php look at the excellent docu
 		of setup3 in the doc-dir of the setup app. 
      5. 
 
    
-
    That's it - please write to our developers list 
-or developer forum, 
+
    That's it - please write to our developers
+list or developer forum, 
 if you have further questions or comments about the tutorial or eTemplate.
    
-
\ No newline at end of file
+
diff --git a/etemplate/doc/reference.html b/etemplate/doc/reference.html
index 4800a1fd98..1c777b1497 100644
--- a/etemplate/doc/reference.html
+++ b/etemplate/doc/reference.html
@@ -1052,8 +1052,8 @@ This is done in most cases by the underlaying html-class and not direct in eTemp
 eTemplates to define the UI of the new widget and are stored in the eTemplate's inc-dir or the inc-dir of a
 eGroupWare application. The editor and the etemplate-class autoload the existing extensions.
    
 
-I will made more documentation about the interface availible soon. For now have a look for the source
-of the existing extensions.
+I have made more documentation about the interface available. For
+additional information, have a look for the source of the existing extensions.
 
 
    please contact me if you have further questions or comments about the eTemplates