<EM> This document explains phpGroupWare's infastructure and API, along with what is required to integrate applications into it.</EM>
<HR>
<H2><ANAME="s1">1. Introduction</A></H2>
<P>phpGroupWare is a web based groupware application framework (API), for writing applications. Integrated applications such as
email, calendar, todo list, address book, and file manager are included.
<H2>1.1 Overview of application writing</H2>
<P>We have attempted to make writing application for phpGroupWare as painless as possible.
We hope any pain and suffering is cause by making your application work, but not dealing with phpGroupWare itself.
<H2>1.2 What does the phpGroupWare API provide?</H2>
<P>The phpGroupWare API handles session management, user/group management, has support for multiple databases, using the PHPLIB database abstraction method, we support templates using the PHPLIB Templates class, a file system interface, and even a network i/o interface.<BR>
On top of these standard functions, phpgroupWare provides several functions to give you the information you need about the users environment, and to properly plug into phpgroupWare.
<H2><ANAME="s2">2. Guidelines</A></H2>
<H2>2.1 Requirements</H2>
<P>These guidelines must be followed for any application that wants considered for inclusion into phpGroupWare deluxe.
<P>It must run on PHP3 and PHP4. <BR>
SQL statements must be compatible with both MySQL and PostgreSQL.<BR>
It must use our default header.inc.php include.<BR>
It must use our <CODE>$phpgw_link($url)</CODE> for all links (this is for session support).<BR>
It must respect phpGW group rights and phpGW user permissions.<BR>
It must use our directory structure, template support and lang (multi-language) support.<BR>
Where possible it should run on both Unix and NT platforms.
<P>For applications that do not meet these requirements, they can be avalible to users via the phpGroupWare Apps project, or whatever means the developers decide.<BR>
If you need help converting your application to templates and our lang support, we will try to connect you with someone to help.
<H2>2.2 Writing/porting your application</H2>
<H3>Include files</H3>
<P>Each PHP page you write will need to include the header.inc.php along with a few variables.<BR>
This is done by putting this at the top of each PHP page.
<LI> The phpgwAPI - The phpGroupWare API will be loaded.</LI>
<LI> The phpGW navbar will be loaded (by default, but can be disabled until a later point.</LI>
<LI> appname/inc/functions.inc.php - This file is loaded just after the phpgwAPI and before any html code is generated. This file should include all your application specific functions.. You are welcome to include any additional files you need from within this file.</LI>
<LI> appname/inc/header.inc.php - This file is loaded just after the system header/navbar, and allows developers to use it for whatever they need to load.</LI>
<LI> appname/inc/footer.inc.php - This file is loaded just before the system footer, allowing developers to close connections and whetever else they need.</LI>
<LI> The phpGW footer will be loaded, which closes several connections.</LI>
<LI> appname/inc/functions.inc.php - This file should include all your application specific functions.</LI>
<LI> appname/inc/header.inc.php - This file is loaded just after the system header/navbar, and allows developers to use it for whatever they need to load.</LI>
<LI> appname/inc/footer.inc.php - This file is loaded just before the system footer, allowing developers to close connections and whetever else they need.</LI>
<P>You will need to create the following directories for your code <BR>
(replace 'appname' with your application name)<BR>
<PRE>
`-- appname
`-- images
| `-- navbar.gif
`-- inc
| |-- functions.inc.php
| |-- header.inc.php
| `-- footer.inc.php
`-- templates
`-- default
</PRE>
<H2>3.4 Making phpGroupWare aware of your application</H2>
<P>To make the application aware of your application, add your application details to the applications table. This can be done via the GUI administration screen, or via a sql script.
<PRE>
insert into applications (app_name, app_title, app_enabled) values ('appname', 'The App name', 1);
</PRE>
<H2><ANAME="s4">4. Infastructure</A></H2>
<H2>4.1 Overview</H2>
<P>phpGroupWare attempts to provide developers with a sound directory structure to work from.<BR>
The directory layout may seem complex at first, but after some use, you will see that it is designed to accommidate a large number of applications and functions.
Store important information session information that your application needs.<BR>
<CODE>$phpgw->appsession</CODE> will return the value of your session data is you leave the paramater enmpty [i.e. <CODE>$phpgw->appsession("")</CODE>], otherwise it will store whatever data you send to it.<BR>
You can also store a comma delimited string and use <CODE>explode()</CODE> to turn it back into an array when you recieve the value back.<BR>
The list of words in the left column should always be written in english. The
second column is used to return those words in that includes language. <CODE>$m1, $m2,
$m3, and $m4</CODE> are used to pass extra data to be place in the middle of a sentence.<BR>
For example:
<PRE>
You have 29 new messages!
</PRE>
The default should return a bold faced * and the word that wasn't found. This allows users to notice that something is missing in the files and make changes if
necessary.
<H2><ANAME="s8">8. Using Templates</A></H2>
<H2>8.1 Overview</H2>
<P>phpGroupWare is built using a templates based design. This means the display pages, stored in tpl files, can be translated to other languages, made to look completely different.
<H2>8.2 How to use templates</H2>
<P>Some instructions on using templates<BR>
For Further info read the PHPLIBs documentation for their template class.
<H2><ANAME="s9">9. About this document</A></H2>
<H2>9.1 New versions </H2>
<P>The newest version of this document can be found on our website
<AHREF="http://www.phpgroupware.org">http://www.phpgroupware.org</A> as SGML source, as HTML and as TEXT.
<H2>9.2 Comments </H2>
<P>Comments on this HOWTO should be directed to the phpGroupWare developers mailing list
