Developping a Hello World application for phpGroupware

Author : Jean-Francois Declercq  (jef@jfdeclercq.com)
Where to find this information : http://www.jfdeclercq.com/search?query=phpgroupware

1. Creating the basic directory structure
2. Wrinting the application
2.1 Writing the basic functionality
2.2 Writing the templates
2.3 Writing the main page
3. Installing the hello application
4. Conclusions
5. What's next ?

1. Creating the basic directory structure

In the phpgroupware home directory, you have to respect  a directory structure. We will create the following.
 
|--hello 
  |--inc 
  |   |--functions.inc.php
  |--templates 
  |   |--default
  |   |   |--hello_form.tpl
  |   |   |--hello_result.tpl
  |--index.php

Create the hello, inc, templates and default directory. We will write the files in the next section.

2. Writing the application

2.1 Writing the basic functionality

First, we will create function.inc.php that contains some functions that will be used  by the page. We will create a function hello() that formats a string. (Note that in the philosophy of phpGroupware we would  write a Hello class that would contain that functionality...)
 
<?php
  /**************************************************************************\
  * functions.inc.php  for  phpGroupWare - Hello World example
  * http://www.phpgroupware.org
  * This file has been written by J-F Declercq <jef@jfdeclercq.com>
  * http://www.jfdeclercq.com 
  * -------------------------------------------- 
  *  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. 
  \**************************************************************************/

  /***************************************************************************\
  * Function hello 
  * in - String : the text to hello() 
  * returns - the string with 'Hello' before and ' !' after 
  * note - Used by the hello phpgw app
  \***************************************************************************/
  function hello($string)
  {
    return "Hello ".$string." !";
  }
?>

2.2 Writing the templates

Write the templates for the page. The page will not contain HTML code. The templates allow to separate the presentation from the logic of the page. We will insert two templates on the page : the 'hello_result' template and the 'hello_form' template.
 
<!-- hello_form.tpl template -->
<p>Type Here your text to hello()</p> 
<form type="post" action="{hello_action}"> 
   <input type="text" name="input" value= "{hello_value}" >
   <input type="submit" value="OK"> 
</form>

This template looks like this :

Type Here your text to hello()

The hello_result.tpl template allows you to display the parameter  and the result of the hello() function.
<!-- hello_result.tpl -->
hello({hello_input})={hello_result}
<hr>
This template looks like this :
hello({hello_input})={hello_result}

You have to put these .tpl files  in the /templates/default/ directory.

2.3 Write the main page

Now we have to write hello/index.php : this is the main page of the hello world application. I hope the code is clear enough so you can understand without I have to explain. (read the comments...)
<?php
  /**************************************************************************\
  * index.php  for  phpGroupWare - Hello World example                       *
  * http://www.phpgroupware.org                                              *
  * This file written by J-F Declercq <jef@jfdeclercq.com>                   *
  * http://www.jfdeclercq.com                                                *
  * --------------------------------------------                             *
  *  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.                                              *
  \**************************************************************************/

  /***************************************************************************\
  * This page allows you to call the hello() function.
  * The default text passed to hello() is 'World' and 
  * hello('World')='Hello World !'.
  * The page uses a form to allow you to hello() other texts.
  * The form and the result of the function  have been put in two different 
  * templates (hello_result.tpl and hello_form.tpl).
  \***************************************************************************/
   //set the phpgw flags
   $phpgw_info['flags'] = array('currentapp' => 'hello',
     'enable_nextmatchs_class' => True,
     'enable_categories_class' => True);
   //include the header
   include('../header.inc.php');
   /** the default text to hello() is 'World'*/
   $default="World";
   if ($input == "") { $input=$default; } 
   //Compute hello()
   $result = hello($input);
   
   //Use templates
   $t = CreateObject('phpgwapi.Template',PHPGW_APP_TPL);
   //we will use two templates
   $t->set_file(array( 
    'result' => 'hello_result.tpl',
    'form' => 'hello_form.tpl')
   );
   
   //filling the first template
   $t->set_var('hello_input',htmlspecialchars($input));
   $t->set_var('hello_result',htmlspecialchars($result));   
   
   //filling the second template
   $t->set_var('hello_action','/hello/index.php');
   $t->set_var('hello_value',htmlspecialchars($input));
   
   //parse and write out the templates
   //changing the order of the two lines will change the layout of the page !!
   //this is the power of the templates
   $t->pparse('out','result');
   $t->pparse('out','form');
   
   
   //Insert the footer
   $phpgw->common->phpgw_footer(); 
?>

3. Installing the hello application

After having the correct files and folders (by creating or unzipping) in you phpGroupware base directory, you have to register the hello application within phpGroupware using this command
insert into phpgw_applications (app_name, app_title, app_enabled) values ('hello', 'Hello World for phpGroupware', 1);
After that, using the admin user, you must grant access to the application to some user and log in as this user.

4. Conclusions

Trough building this stupid hello world application we have been trough some but not all of the requirements of phpGroupware.

"These guidelines must be followed for any application that wants considered for inclusion into phpGroupWare deluxe"
It must run on PHP3 and PHP4. OK - I think it's ok (?) I'm not a king of php and I use PHP4.
SQL statements must be compatible with both MySQL and PostgreSQL.  OK - No SQL statement so far
It must use our default header.inc.php include.  OK - cfr index.php
It must use our $phpgw_link($url) for all links (this is for session support).  OK - cfr hello_form.tpl
It must use ``post'' for forms.  OK - cfr hello_form.tpl
It must respect phpGW group rights and phpGW user permissions.  KO - We didn't check that particular aspect. --> TODO
It must use our directory structure, template support and lang (multi-language) support.  KO - we didn't use the language aspects --> TODO
Where possible it should run on both Unix and NT platforms.  OK ? - Only tested on NT

hello isn't a phpGroupware deluxe application...  The next evolution of hello will be to add a group right and a multi-language feature. See what's next.

phpGroupWare offers very interesting features for people wanting to write 100% web-based applications :

5. What's next

So, other things I should cover in the next Hello World application :