This document explains eGroupWare's infrastructure and API, +along with what is required to integrate applications into it. ++ +
+
+eGroupWare 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. + +
+
+We have attempted to make writing application for eGroupWare as +painless as possible. We hope any pain and suffering is cause by making +your application work, but not dealing with eGroupWare itself. + +
+
+The eGroupWare 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. + +
+On top of these standard functions, eGroupWare provides several +functions to give you the information you need about the users environment, +and to properly plug into eGroupWare. + +
+
+
+These guidelines must be followed for any application that wants considered +for inclusion into eGroupWare deluxe: + +
+ +
+
+
+
+
+
+
+
+
+
+
+ +
+Each PHP page you write will need to include the header.inc.php along
+with a few variables.
+This is done by putting this at the top of each PHP page.
+
+
+<?php
+$GLOBALS['phpgw_info']['flags']['currentapp'] = 'appname';
+include('../header.inc.php');
+?>
+
+
+Of course change application name to fit.+ +
+
+
+
+
+It is fairly simple to add and delete applications to/from eGroupWare. + +
+
+To make things easy for developers we go ahead and load the following +files. +
+ ++
+You will need to create the following directories for your code
+(replace 'appname' with your application name)
+
+
+--appname + + +--inc + + | |--functions.inc.php + + | |--header.inc.php + + | |--hook_preferences.inc.php + + | |--hook_admin.inc.php + + | +--footer.inc.php + + +--js + + | |--base + + | +--js_package_name + + +--setup + + | |--default_records.inc.php + + | |--setup.inc.php + + | +--tables_current.inc.php + + +--templates + + +--default ++ +
+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. The script below should only be used during initial +development. You should use the eGroupWare setup system for install and updating +the final version of your application. +
+INSERT INTO phpgw_applications (app_name, app_title, app_enabled)
+ VALUES('appname', 'The App name', 1);
+
+
++
+When a user goes to the Administration page, it starts appname/inc/hook_admin.inc.php +for each application that is enabled, in alphabetical order of application +title. If the file exists, it is include()d in the hopes it will display +a selection of links to configure that application. + +
+Simple Example: +
+<?php
+// Old linear script style
+$file['Site Configuration'] = $GLOBALS['phpgw']->link('myapp/myAdminPage.php');
+// OR - OOP Style
+$file['Site Configuration'] = $GLOBALS['phpgw']->link('/index.php',
+ array(menuaction => 'myapp.uiobj.admin_method');
+display_section('myapp',$file);
+?&#gt;
+
+Look at headlines/inc/hook_admin.inc.php and admin/inc/hook_admin.inc.php for more
+examples.
+
+Things to note:
++
+The mechanism to hook into the preferences page is identical to the +one used to hook into the administration page, however it looks for +appname/inc/hook_preferences.inc.php instead of appname/inc/hook_admin.inc.php. +The same functions and variables are defined. + +
+
+
+eGroupWare attempts to provide developers with a sound directory
+structure to work from.
+The directory layout may seem complex at first, but after some use,
+you will see that it is designed to accommodate a large number of
+applications and functions.
+
+
+
+--eGroupWare + | + +--admin + | + +--docs (installation docs) + | + +--files (Note: must be out of webserver document root!) + | | + | +--groups + | | + | +--homes + | | + | +--users + | + +--phpgwapi + | | + | +--cron (eGroupWare's optional daemons) + | | + | +--doc (developers docs) + | | + | +--inc + | | | + | | +--class.phpgw.inc.php + | | | + | | +--phpgw_info.inc.php + | | | + | | +--class.common.inc.php + | | | + | | +--etc.. + | | + | +--js (javascript) + | | | + | | +--base + | | | + | | +--js_package_name + | | + | +--manual + | | + | +--setup + | | | + | | +--baseline.inc.php + | | | + | | +--default_records.inc.php + | | | + | | +--tables_current.inc.php + | | | + | | +--tables_update.inc.php + | | + | +--templates + | | | + | | +--default + | | | | + | | | +--images + | | | + | | +--verilak + | | | + | | +--images + | | + | +--themes + | | + | +--default.theme + | + +--preferences + | + +--setup ++
+The translations are now being done thru the database, and may be +configurable to use other mechanisms in future releases. + +
+You can use the developer_tools translations application for creating +the "lang files", which will be installed through the setup application. +Alternatively you can edit the files manually. The file naming convention for +the lang files is phpgw_<langcode>.lang. The files are stored +in the app/setup directory. The format of the files is as follows: +
+english phrase in lower case appname ** Translated phrase in desired case. ++Notes: +
+
+eGroupWare attempts to provide developers with a useful API to handle +common tasks. + +
+To do this we have created a multi-dimensional class $GLOBALS['phpgw']->. + +
+This allows for terrific code organization, and help developers easily +identify the file that the function is in. All the files that are +part of this class are in the inc/core directory and are named to +match the sub-class. + +
+Example: $phpgw->send->msg() is in the inc/phpgwapi/class.send.inc.php +file. + +
+
+ +
+$GLOBALS['phpgw']->link($url, $args)
+Add support for session management. ALL links must use this, that
+includes href's form actions and header location's.
+
+
+If you are just doing a form action back to the same page, you can +use it without any parameters. + +
+This function is right at the core of the class because it is used +so often, we wanted to save developers a few keystrokes. Example: + +
+<form name=copy method=post action="<?php echo $GLOBALS['phpgw']->link();?>"> +/* If session management is done via passing url parameters */ +/* The the result would be */ +/* <form name=copy method=post action="somepage.php?sessionid=87687693276?kp3=kjh98u80"> */ ++ +
+
+ +
+$GLOBALS['phpgw']->phpgw_header()
+Print out the start of the HTML page, including the navigation bar
+and includes appname/inc/header.php, if using deprecated linear scripts style.
+
+
+ +
+$GLOBALS['phpgw']->phpgw_footer()
+Prints the system footer, and includes appname/inc/footer.php
+
+
+ +
+$GLOBALS['phpgw']->common->appsession($data)
+Store important information session information that your application
+needs.
+$GLOBALS['phpgw']->appsession will return the value of your session data is
+you leave the parameter empty [i.e. $GLOBALS['phpgw']->appsession()],
+otherwise it will store whatever data you send to it.
+You can also store a comma delimited string and use explode() to
+turn it back into an array when you receive the value back.
+
+
+Example: +
+$GLOBALS['phpgw']->common->appsession("/path/to/something");
+echo "Dir: " . $GLOBALS['phpgw']->common->appsession();
+
+
++
See Virtual File System (VFS) Developers Guide +for more info.
+ ++ +
+$phpgw->msg->send($service, $to, $subject, $body, $msgtype,
+$cc, $bcc)
+Send a message via email or NNTP and returns any error codes.
+Example:
+
+
+$to = 'someuser@domain.com';
+$subject = 'Hello buddy';
+$body = "Give me a call\n Been wondering what your up to.";
+$errors = $GLOBALS['phpgw']->msg->send('email', $to, $subject, $body);
+
+
+
+
++
+
+eGroupWare attempts to provide developers with as much information +about the user, group, server, and application configuration as possible. + +
+To do this we provide a multi-dimensional array called "$GLOBALS['phpgw_info']", +which includes all the information about your environment. + +
+Due to the multi-dimensional array approach. getting these values +is easy. + +
+Here are some examples: +
+ +<?php +// To do a hello username +echo "Hello " . $GLOBALS['phpgw_info']['user']['fullname']; +//If username first name is John and last name is Doe, prints: 'Hello John Doe' +?> +<?php +// To find out the location of the imap server +echo 'IMAP Server is named: ' . $GLOBALS['phpgw_info']['server']['imap_server']; +//If imap is running on localhost, prints: 'IMAP Server is named: localhost' +?> + + + ++ +
+
+It is unlikely you will need these, because $GLOBALS['phpgw']->db will +already be loaded as a database for you to use. +
+ + +$phpgw_info[``server''][``db_host''] = Address of the database server. Usually this is set to localhost. +$phpgw_info[``server''][``db_name''] = Database name. +$phpgw_info[``server''][``db_user''] = User name. +$phpgw_info[``server''][``db_pass''] = Password +$phpgw_info[``server''][``db_type''] = Type of database. Currently MySQL and PostgreSQL are supported. + + ++It is unlikely you will need these, because most email needs are services +thru core eGroupWare functions. + +
+$phpgw_info[``server''][``mail_server'']
+= Address of the IMAP server. Usually this is set to localhost.
+
+
+
+
+
+
+
+
+
+$phpgw_info[``server''][``nntp_server'']
+= Address of the NNTP server.
+
+
+
+
+
+
+Each application has the following information available. + +
+$phpgw_info[``apps''][``appname''][``title'']
+= The title of the application.
+
+
+
+
+
+
+
+
+
+eGroupWare is built using a multi-language support scheme. This +means the pages can be translated to other languages very easily. +Translations of text strings are stored in the eGroupWare database, +and can be modified by the eGroupWare administrator. + +
+
+The lang() function is your application's interface to eGroupWare's +internationalization support. + +
+While developing your application, just wrap all your text output +with calls to lang(), as in the following code: + +
+$x = 42;
+echo lang("The counter is %1",$x)."<br>";
+
+
+This will attempt to translate ``The counter is %1'',
+and return a translated version based on the current application and
+language in use. Note how the position that $x will end up is controlled
+by the format string, not by building up the string in your
+code. This allows your application to be translated to languages where
+the actual number is not placed at the end of the string.
+
++When a translation is not found, the original text will be returned +with a * after the string. This makes it easy to develop your application, +then go back and add missing translations (identified by the *) +later. + +
+Without a specific translation in the lang table, the above code will +print: +
+The counter is 42*<br> ++ +If the current user speaks Italian, they string returned +may instead be: + +
+il contatore è 42<br&#gt; ++ +
+ +
+ +lang($key, $m1="", $m2="", $m3="", $m4="", $m5="", + $m6="", $m7="", $m8="", $m9="", $m10="") + ++ +
+ +
+is the string to translate and may contain replacement directives
+of the form %n.
+is the first replacement value or may be an array of replacement values +(in which case $m2 and above are ignored).
+the 2nd through 10th replacement values if $m1 is not an array.
+ +
+An application called Transy is being developed to make this +easier, until then you can create the translation data manually. + +
+ +
+The translation class uses the lang table for all translations. We +are concerned with 4 of the columns to create a translation: + +
+ +
+The key to identify the message (the $key passed to the lang() function). +This is written in English.
+The application the translation applies to, or common if it is common +across multiple applications.
+The code for the language the translation is in.
+The translated string.
+ +
+Currently all applications, and the core eGroupWare source tree +have a lang.sql file. This is the place to add translation data. Just +add lines of the form: +
+ +REPLACE INTO lang (message_id, app_name, lang, content) +VALUES( 'account has been deleted','common','en','Account has been deleted'); + + +translating the content to reflect the message_id string +in the lang language. If the string is specific to your application, +put your application name in for app_name otherwise use the name +common. The message_id should be in lower case for a small increase +in speed. + +
+
+If you browse through the eGroupWare sources, you may notice a pattern +to the return codes used in the higher-level functions. The codes +used are partially documented in the doc/developers/CODES file. + +
+Codes are used as a simple way to communicate common error and progress +conditions back to the user. They are mapped to a text string through +the check_code() function, which passes the strings through lang() +before returning. + +
+For example, calling +
+ +echo check_code(13); + + +Would print +
+ +Your message has been sent + + +translated into the current language. + +
+eGroupWare 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.
+ ++For Further info read the PHPLIBs documentation for their template +class. http://phplib.sanisoft.com +
+ ++eTemplate is a new widget-based template system, which is used eg. for the InfoLog application. +There's a Tutorial and a +Referenz documentation availible. +
++
+
+The newest version of this document can be found on our website http://www.eGroupWare.org. + +
+
+Comments on this HOWTO should be directed to the eGroupWare +developers mailing list (subscription at www.sourceforge.net/egroupware/). + +
+
+This document was written by Dan Kuykendall. + +
+2000-09-25 documentation on lang(), codes, administration and preferences +extension added by Steve Brown. + +
+2001-01-08 fixed directory structure, minor layout changes, imported +to lyx source - Darryl VanDorp + +
+2001-01-08 fixed directory structure, minor layout changes, imported +to lyx source - Darryl VanDorp + +
+2004-02-22 imported skwashd's changes and adapted for eGroupWare - Ralf Becker + +
+
+Copyright © Free Software Foundarion. Permission is granted to copy, +distribute and/or modify this document under the terms of the GNU Free +Documentation License, Version 1.1 or any later version published by the +Free Software Foundation. + +
+A copy of the license is available at http://www.gnu.org/copyleft/gpl.html + +
+
+Thanks to Joesph Engo for starting eGroupWare (at the time called
+webdistro). Thanks to all the developers and users who contribute
+to making eGroupWare such a success.
+
+
$Id$
+