egroupware/phpgwapi/doc/index.html
2004-02-23 00:47:01 +00:00

1083 lines
34 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>eGroupWare Application Development</title>
<style type="text/css">
<!--
h1 {
text-shadow: 3px 3px 5px;
}
h1:before {
content: counter(chapter) ". ";
counter-increment: chapter; /* Add 1 to chapter */
counter-reset: section; /* Set section to 0 */
}
h2:before {
content: counter(chapter) "." counter(section) " ";
counter-increment: section;
}
ol { counter-reset: item }
lo { display: block }
li:before { content: counters(item, "."); counter-increment: item }
body, p, td {font-family: Verdana, Arial, Helvetica, sans-serif;}
blockquote {text-align: center; font-style: italic;}
//-->
</style>
</head>
<body>
<h1>eGroupWare Application Development</h1>
<blockquote>
This document explains eGroupWare's infrastructure and API,
along with what is required to integrate applications into
it.
</blockquote>
<h1>Contents</h1>
<ol>
<li><a href="#tth_sEc1">Introduction</a></li>
<li style="list-style: none">
<ol>
<li><a href="#tth_sEc1.1">Overview of application
writing</a></li>
<li><a href="#tth_sEc1.2">What does the eGroupWare API
provide?</a></li>
</ol>
</li>
<li><a href="#tth_sEc2">Guidelines</a></li>
<li style="list-style: none">
<ol>
<li><a href="#tth_sEc2.1">Requirements</a></li>
<li><a href="#tth_sEc2.2">Writing/porting your
application</a></li>
</ol>
</li>
<li><a href="#tth_sEc3">Installing your application</a></li>
<li style="list-style: none">
<ol>
<li><a href="#tth_sEc3.1">Overview</a></li>
<li><a href="#tth_sEc3.2">Automatic features</a></li>
<li><a href="#tth_sEc3.3">Adding files, directories and
icons.</a></li>
<li><a href="#tth_sEc3.4">Making eGroupWare aware of your
application</a></li>
<li><a href="#tth_sEc3.5">Hooking into Administration
page</a></li>
<li><a href="#tth_sEc3.6">Hooking into Preferences
page</a></li>
</ol>
</li>
<li><a href="#tth_sEc4">Infrastructure</a></li>
<li style="list-style: none">
<ol>
<li><a href="#tth_sEc4.1">Overview</a></li>
<li><a href="#tth_sEc4.2">Directory tree</a></li>
<li><a href="#tth_sEc4.3">Translations</a></li>
</ol>
</li>
<li><a href="#tth_sEc5">The API</a></li>
<li style="list-style: none">
<ol>
<li><a href="#tth_sEc5.1">Introduction</a></li>
<li><a href="#tth_sEc5.2">Basic functions</a></li>
<li><a href="#tth_sEc5.3">Application Functions</a></li>
<li><a href="#tth_sEc5.4">File functions</a></li>
<li><a href="#tth_sEc5.5">Email/NNTP Functions</a></li>
</ol>
</li>
<li><a href="#tth_sEc6">Configuration Variables</a></li>
<li style="list-style: none">
<ol>
<li><a href="#tth_sEc6.1">Introduction</a></li>
<li><a href="#tth_sEc6.2">User information</a></li>
<li><a href="#tth_sEc6.3">Group information</a></li>
<li><a href="#tth_sEc6.4">Server information</a></li>
<li><a href="#tth_sEc6.5">Database information</a></li>
<li><a href="#tth_sEc6.6">Mail information</a></li>
<li><a href="#tth_sEc6.7">NNTP information</a></li>
<li><a href="#tth_sEc6.8">Application
information</a></li>
</ol>
</li>
<li><a href="#tth_sEc7">Using Language Support</a></li>
<li style="list-style: none">
<ol>
<li><a href="#tth_sEc7.1">Overview</a></li>
<li><a href="#tth_sEc7.2">How to use lang
support</a></li>
<li><a href="#tth_sEc7.3">Common return codes</a></li>
</ol>
</li>
<li><a href="#tth_sEc8">Using Templates</a></li>
<li style="list-style: none">
<ol>
<li><a href="#tth_sEc8.1">Overview</a></li>
<li><a href="#tth_sEc8.2">How to use PHPLIB
templates</a></li>
<li><a href="#tth_sEc8.3">How to use eTemplate
templates</a></li>
</ol>
</li>
<li><a href="#tth_sEc9">About this document</a></li>
<li style="list-style: none">
<ol>
<li><a href="#tth_sEc9.1">New versions</a></li>
<li><a href="#tth_sEc9.2">Comments</a></li>
<li><a href="#tth_sEc9.3">History</a></li>
<li><a href="#tth_sEc9.4">Copyrights and
Trademarks</a></li>
<li><a href="#tth_sEc9.5">Acknowledgments and
Thanks</a></li>
</ol>
</li>
</ol>
<h2><a name="tth_sEc1">1</a>&nbsp;&nbsp;Introduction</h2>
<p>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.</p>
<h3><a name="tth_sEc1.1">1.1</a>&nbsp;&nbsp;Overview of
application writing</h3>
<p>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.</p>
<h3><a name="tth_sEc1.2">1.2</a>&nbsp;&nbsp;What does the
eGroupWare API provide?</h3>
<p>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.</p>
<p>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.</p>
<h2><a name="tth_sEc2">2</a>&nbsp;&nbsp;Guidelines</h2>
<h3><a name="tth_sEc2.1">2.1</a>&nbsp;&nbsp;Requirements</h3>
<p>These guidelines must be followed for any application that
wants considered for inclusion into eGroupWare deluxe:</p>
<ul>
<li>It must run on PHP4.1.0</li>
<li>SQL statements must be compatible with both MySQL,
PostgreSQL, M$ SQL Server and SAP-DB</li>
<li>It must use our default header.inc.php include.</li>
<li>It must use our $GLOBALS['phpgw']-&gt;link($url) for all
links (this is for session support).</li>
<li>It must use "POST" for form submit methods.</li>
<li>It must respect eGW group rights and eGW user
permissions.</li>
<li>It must use our directory structure, template support and
lang (multi-language) support.</li>
<li>Where possible it should run on both Unix and NT
platforms.</li>
<li>For applications that do not meet these requirements,
they can be available to users via the eGroupWare "3rd Party
Apps" listing on our website. If you need help converting
your application to templates and our lang support, we will
try to connect you with someone to help.</li>
</ul>
<h3><a name="tth_sEc2.2">2.2</a>&nbsp;&nbsp;Writing/porting
your application</h3>
<h4>Include files</h4>
<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.</p>
<pre>
&lt;?php
$GLOBALS['phpgw_info']['flags']['currentapp'] = 'appname';
include('../header.inc.php');
?&gt;
</pre>
Of course change application name to fit.<br>
This include will provide the following things:
<ul>
<li>The phpgwAPI - The eGroupWare API will be loaded.</li>
<li>The eGW 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.<br>
<b>Note:</b> Depricated and not used for OOP
(/index.php?menuaction=app.obj.method) calls.</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.<br>
<b>Note:</b> Depricated and not used for OOP
(/index.php?menuaction=app.obj.method) calls.</li>
<li>appname/inc/footer.inc.php - This file is loaded just
before the system footer, allowing developers to close
connections and whatever else they need.<br>
<b>Note:</b> Depricated and not used for OOP
(/index.php?menuaction=app.obj.method) calls.</li>
<li>The eGW footer will be loaded, which closes several
connections.</li>
</ul>
<h2><a name="tth_sEc3">3</a>&nbsp;&nbsp;Installing your
application</h2>
<h3><a name="tth_sEc3.1">3.1</a>&nbsp;&nbsp;Overview</h3>
<p>It is fairly simple to add and delete applications to/from
eGroupWare.</p>
<h3><a name="tth_sEc3.2">3.2</a>&nbsp;&nbsp;Automatic
features</h3>
<p>To make things easy for developers we go ahead and load the
following files.</p>
<ul>
<li>appname/inc/functions.inc.php - This file should include
all your application specific functions.<br>
<b>Note:</b> Depricated and not used for OOP
(/index.php?menuaction=app.obj.method) calls.</li>
<li>appname/inc/header.inc.php - This file is loaded by
$phpgw-&gt;common-&gt;header just after the system
header/navbar, and allows developers to use it for whatever
they need to load.<br>
<b>Note:</b> Depricated and not used for OOP
(/index.php?menuaction=app.obj.method) calls.</li>
<li>appname/inc/footer.inc.php - This file is loaded by
$phpgw-&gt;common-&gt;footer just before the system footer,
allowing developers to close connections and whatever else
they need.<br>
<b>Note:</b> Depricated and not used for OOP
(/index.php?menuaction=app.obj.method) calls.</li>
</ul>
<h3><a name="tth_sEc3.3">3.3</a>&nbsp;&nbsp;Adding files,
directories and icons.</h3>
<p>You will need to create the following directories for your
code<br>
(replace 'appname' with your application name)<br>
</p>
<pre>
--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
</pre>
<h3><a name="tth_sEc3.4">3.4</a>&nbsp;&nbsp;Making eGroupWare
aware of your application</h3>
<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. 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.</p>
<pre>
INSERT INTO phpgw_applications (app_name, app_title, app_enabled)
VALUES('appname', 'The App name', 1);
</pre>
<h3><a name="tth_sEc3.5">3.5</a>&nbsp;&nbsp;Hooking into
Administration page</h3>
<p>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.</p>
<p>Simple Example:</p>
<pre>
&lt;?php
// Old linear script style
$file['Site Configuration'] = $GLOBALS['phpgw']-&gt;link('myapp/myAdminPage.php');
// OR - OOP Style
$file['Site Configuration'] = $GLOBALS['phpgw']-&gt;link('/index.php',
array(menuaction =&gt; 'myapp.uiobj.admin_method');
display_section('myapp',$file);
?&amp;#gt;
</pre>
Look at headlines/inc/hook_admin.inc.php and
admin/inc/hook_admin.inc.php for more examples. Things to note:
<ul>
<li>Links are relative to the admin/index.php file, not your
application's base directory. (so use "appname" in your
link() calls)</li>
<li>The file is brought in with include() so be careful to
not pollute the name-space too much</li>
</ul>
The standard $GLOBALS['phpgw'] and $GLOBALS['phpgw_info']
variables are in-scope, as is $appname which corresponds to the
application name in the path.
<h3><a name="tth_sEc3.6">3.6</a>&nbsp;&nbsp;Hooking into
Preferences page</h3>
<p>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.</p>
<h2><a name="tth_sEc4">4</a>&nbsp;&nbsp;Infrastructure</h2>
<h3><a name="tth_sEc4.1">4.1</a>&nbsp;&nbsp;Overview</h3>
<p>eGroupWare 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 accommodate a large
number of applications and functions.</p>
<h3><a name="tth_sEc4.2">4.2</a>&nbsp;&nbsp;Directory tree</h3>
<pre>
--eGroupWare
|
+--admin
|
+--docs (installation docs)
|
+--files (<b>Note:</b> 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
</pre>
<h3><a name="tth_sEc4.3">4.3</a>&nbsp;&nbsp;Translations</h3>
<p>The translations are now being done thru the database, and
may be configurable to use other mechanisms in future
releases.</p>
<p>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
<tt>phpgw_&lt;langcode&gt;.lang</tt>. The files are stored in
the <tt>app/setup</tt> directory. The format of the files is as
follows:</p>
<pre>
english phrase in lower case appname ** Translated phrase in desired case.
</pre>
<b>Notes:</b>
<ul>
<li>replace ** with the desired language code, as used in the
filename</li>
<li>tabs are used to deliniate "columns"</li>
</ul>
<h2><a name="tth_sEc5">5</a>&nbsp;&nbsp;The API</h2>
<h3><a name="tth_sEc5.1">5.1</a>&nbsp;&nbsp;Introduction</h3>
<p>eGroupWare attempts to provide developers with a useful API
to handle common tasks.</p>
<p>To do this we have created a multi-dimensional class
$GLOBALS['phpgw']-&gt;.</p>
<p>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.</p>
<p>Example: $phpgw-&gt;send-&gt;msg() is in the
inc/phpgwapi/class.send.inc.php file.</p>
<h3><a name="tth_sEc5.2">5.2</a>&nbsp;&nbsp;Basic
functions</h3>
<h4>$GLOBALS['phpgw']-&gt;link</h4>
<p>$GLOBALS['phpgw']-&gt;link($url, $args)<br>
Add support for session management. ALL links must use this,
that includes href's form actions and header location's.</p>
<p>If you are just doing a form action back to the same page,
you can use it without any parameters.</p>
<p>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:</p>
<pre>
&lt;form name=copy method=post action="&lt;?php echo $GLOBALS['phpgw']-&gt;link();?&gt;"&gt;
/* If session management is done via passing url parameters */
/* The the result would be */
/* &lt;form name=copy method=post action="somepage.php?sessionid=87687693276?kp3=kjh98u80"&gt; */
</pre>
<h3><a name="tth_sEc5.3">5.3</a>&nbsp;&nbsp;Application
Functions</h3>
<h4>$GLOBALS['phpgw']-&gt;common-&gt;phpgw_header</h4>
<p>$GLOBALS['phpgw']-&gt;phpgw_header()<br>
Print out the start of the HTML page, including the navigation
bar and includes appname/inc/header.php, if using deprecated
linear scripts style.</p>
<h4>$GLOBALS['phpgw']-&gt;common-&gt;phpgw_footer</h4>
<p>$GLOBALS['phpgw']-&gt;phpgw_footer()<br>
Prints the system footer, and includes
appname/inc/footer.php</p>
<h4>$GLOBALS['phpgw']-&gt;common-&gt;appsession</h4>
<p>$GLOBALS['phpgw']-&gt;common-&gt;appsession($data)<br>
Store important information session information that your
application needs.<br>
$GLOBALS['phpgw']-&gt;appsession will return the value of your
session data is you leave the parameter empty [i.e.
$GLOBALS['phpgw']-&gt;appsession()], otherwise it will store
whatever data you send to it.<br>
You can also store a comma delimited string and use explode()
to turn it back into an array when you receive the value
back.</p>
<p>Example:</p>
<pre>
$GLOBALS['phpgw']-&gt;common-&gt;appsession("/path/to/something");
echo "Dir: " . $GLOBALS['phpgw']-&gt;common-&gt;appsession();
</pre>
<h3><a name="tth_sEc5.4">5.4</a>&nbsp;&nbsp;File functions</h3>
<p>See <a href="vfs/vfs.html">Virtual File System (VFS)
Developers Guide</a> for more info.</p>
<h3><a name="tth_sEc5.5">5.5</a>&nbsp;&nbsp;Email/NNTP
Functions</h3>
<h4>$phpgw-&gt;send-&gt;msg</h4>
<p>$phpgw-&gt;msg-&gt;send($service, $to, $subject, $body,
$msgtype, $cc, $bcc)<br>
Send a message via email or NNTP and returns any error
codes.<br>
Example:</p>
<pre>
$to = 'someuser@domain.com';
$subject = 'Hello buddy';
$body = "Give me a call\n Been wondering what your up to.";
$errors = $GLOBALS['phpgw']-&gt;msg-&gt;send('email', $to, $subject, $body);
</pre>
<h2><a name="tth_sEc6">6</a>&nbsp;&nbsp;Configuration
Variables</h2>
<h3><a name="tth_sEc6.1">6.1</a>&nbsp;&nbsp;Introduction</h3>
<p>eGroupWare attempts to provide developers with as much
information about the user, group, server, and application
configuration as possible.</p>
<p>To do this we provide a multi-dimensional array called
"$GLOBALS['phpgw_info']", which includes all the information
about your environment.</p>
<p>Due to the multi-dimensional array approach. getting these
values is easy.</p>
<p>Here are some examples:</p>
<pre>
&lt;?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'
?&gt;
&lt;?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'
?&gt;
</pre>
<h3><a name="tth_sEc6.2">6.2</a>&nbsp;&nbsp;User
information</h3>
<tt><font size="-1">$GLOBALS['phpgw_info']['user']['userid'] =
The user ID.<br>
$GLOBALS['phpgw_info']['user']['sessionid'] = The session
ID<br>
$GLOBALS['phpgw_info']['user']['theme'] = Selected theme<br>
$GLOBALS['phpgw_info']['user']['private_dir'] = Users private
dir. Use eGroupWare core functions for access to the files.<br>
$GLOBALS['phpgw_info']['user']['firstname'] = Users first
name<br>
$GLOBALS['phpgw_info']['user']['lastname'] = Users last
name<br>
$GLOBALS['phpgw_info']['user']['fullname'] = Users Full
Name<br>
$GLOBALS['phpgw_info']['user']['groups'] = Groups the user is
a member of<br>
$GLOBALS['phpgw_info']['user']['app_perms'] = If the user has
access to the current application<br>
$GLOBALS['phpgw_info']['user']['lastlogin'] = Last time the
user logged in.<br>
$GLOBALS['phpgw_info']['user']['lastloginfrom'] = Where they
logged in from the last time.<br>
$GLOBALS['phpgw_info']['user']['lastpasswd_change'] = Last time
they changed their password.<br>
$GLOBALS['phpgw_info']['user']['passwd'] = Hashed password.<br>
$GLOBALS['phpgw_info']['user']['status'] = If the user is
enabled.<br>
$GLOBALS['phpgw_info']['user']['logintime'] = Time they logged
into their current session.<br>
$GLOBALS['phpgw_info']['user']['session_dla'] = Last time they
did anything in their current session<br>
$GLOBALS['phpgw_info']['user']['session_ip'] = Current IP
address<br>
</font></tt>
<h3><tt><a name="tth_sEc6.3">6.3</a>&nbsp;&nbsp;Group
information</tt></h3>
<tt><font size=
"-1">$GLOBALS['phpgw_info']['group']['group_names'] = List of
groups.</font></tt>
<h3><a name="tth_sEc6.4">6.4</a>&nbsp;&nbsp;Server
information</h3>
<tt><font size="-1">$phpgw_info[``server''][``server_root''] =
Main installation directory
$phpgw_info[``server''][``include_root''] = Location of the
'inc' directory. $phpgw_info[``server''][``temp_dir''] =
Directory that can be used for temporarily storing files
$phpgw_info[``server''][``files_dir''] = Directory er and group
files are stored
$phpgw_info[``server''][``common_include_dir''] = Location of
the core/shared include files.
$phpgw_info[``server''][``template_dir''] = Active template
files directory. This is defaulted by the server, and
changeable by the user.
$phpgw_info[``server''][``dir_separator''] = Allows
compatibility with WindowsNT directory format
$phpgw_info[``server''][``encrpytkey''] = Key used for
encryption functions $phpgw_info[``server''][``site_title''] =
Site Title will show in the title bar of each webpage.
$phpgw_info[``server''][``webserver_url''] = URL to eGroupWare
installation. $phpgw_info[``server''][``hostname''] = Name of
the server eGroupWare is installed upon.
$phpgw_info[``server''][``charset''] = default charset,
default:iso-8859-1 $phpgw_info[``server''][``version''] =
eGroupWare version.</font></tt>
<h3><tt><font size="-1"><a name=
"tth_sEc6.5">6.5</a>&nbsp;&nbsp;Database
information</font></tt></h3>
<p>It is unlikely you will need these, because
$GLOBALS['phpgw']-&gt;db will already be loaded as a database
for you to use.</p>
<tt><font size="-1">$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.</font></tt>
<h3><a name="tth_sEc6.6">6.6</a>&nbsp;&nbsp;Mail
information</h3>
<p>It is unlikely you will need these, because most email needs
are services thru core eGroupWare functions.</p>
<p><tt><font size="-1">$phpgw_info[``server''][``mail_server'']
= Address of the IMAP server. Usually this is set to
localhost.</font></tt></p>
<p><tt><font size=
"-1">$phpgw_info[``server''][``mail_server_type''] = IMAP or
POP3</font></tt></p>
<p><tt><font size=
"-1">$phpgw_info[``server''][``imap_server_type''] = Cyrus or
Uwash</font></tt></p>
<p><tt><font size="-1">$phpgw_info[``server''][``imap_port''] =
This is usually 143, and should only be changed if there is a
good reason.</font></tt></p>
<p><tt><font size="-1">$phpgw_info[``server''][``mail_suffix] =
This is the domain name, used to add to email
address</font></tt></p>
<p><tt><font size=
"-1">$phpgw_info[``server''][``mail_login_type''] = This adds
support for VMailMgr. Generally this should be set to
'standard'.</font></tt></p>
<p><tt><font size="-1">$phpgw_info[``server''][``smtp_server'']
= Address of the SMTP server. Usually this is set to
localhost.</font></tt></p>
<p><tt><font size="-1">$phpgw_info[``server''][``smtp_port''] =
This is usually 25, and should only be changed if there is a
good reason</font></tt></p>
<h3><a name="tth_sEc6.7">6.7</a>&nbsp;&nbsp;NNTP
information</h3>
<p><tt><font size="-1">$phpgw_info[``server''][``nntp_server'']
= Address of the NNTP server.</font></tt></p>
<p><tt><font size="-1">$phpgw_info[``server''][``nntp_port''] =
This is usually XX, and should only be changed if there is a
good reason.</font></tt></p>
<p><tt><font size="-1">$phpgw_info[``server''][``nntp_sender'']
= Unknown</font></tt></p>
<p><tt><font size=
"-1">$phpgw_info[``server''][``nntp_organization''] =
Unknown</font></tt></p>
<p><tt><font size="-1">$phpgw_info[``server''][``nntp_admin'']
= Unknown</font></tt></p>
<h3><a name="tth_sEc6.8">6.8</a>&nbsp;&nbsp;Application
information</h3>
<p>Each application has the following information
available.</p>
<p><tt><font size=
"-1">$phpgw_info[``apps''][``appname''][``title''] = The title
of the application.</font></tt></p>
<p><tt><font size=
"-1">$phpgw_info[``apps''][``appname''][``enabled''] = If the
application is enabled. True or False.</font></tt></p>
<p><tt><font size=
"-1">$phpgw_info[``server''][``app_include_dir''] = Location of
the current application include files.</font></tt></p>
<p><tt><font size=
"-1">$phpgw_info[``server''][``app_template_dir''] = Location
of the current application tpl files.</font></tt></p>
<p><tt><font size=
"-1">$phpgw_info[``server''][``app_lang_dir''] = Location of
the current lang directory.</font></tt></p>
<p><tt><font size="-1">$phpgw_info[``server''][``app_auth''] =
If the server and current user have access to current
application</font></tt></p>
<p><tt><font size="-1">$phpgw_info[``server''][``app_current'']
= name of the current application.</font></tt></p>
<h2><a name="tth_sEc7">7</a>&nbsp;&nbsp;Using Language
Support</h2>
<h3><a name="tth_sEc7.1">7.1</a>&nbsp;&nbsp;Overview</h3>
<p>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.</p>
<h3><a name="tth_sEc7.2">7.2</a>&nbsp;&nbsp;How to use lang
support</h3>
<p>The lang() function is your application's interface to
eGroupWare's internationalization support.</p>
<p>While developing your application, just wrap all your text
output with calls to lang(), as in the following code:</p>
<pre>
$x = 42;
echo lang("The counter is %1",$x)."&lt;br&gt;";
</pre>
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, <b>not</b> 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.
<p>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.</p>
<p>Without a specific translation in the lang table, the above
code will print:</p>
<pre>
The counter is 42*&lt;br&gt;
</pre>
If the current user speaks Italian, they string returned may
instead be:
<pre>
il contatore &egrave; 42&lt;br&amp;#gt;
</pre>
<h4>The lang function</h4>
<pre>
lang($key, $m1="", $m2="", $m3="", $m4="", $m5="",
$m6="", $m7="", $m8="", $m9="", $m10="")
</pre>
<dl compact="compact">
<dd>
[$key&nbsp;]&nbsp;
<p>is the string to translate and may contain replacement
directives of the form %n.<br>
</p>
</dd>
<dd>
[$m1&nbsp;]&nbsp;
<p>is the first replacement value or may be an array of
replacement values (in which case $m2 and above are
ignored).</p>
</dd>
<dd>
[$m2&nbsp;-&nbsp;$m10&nbsp;]&nbsp;
<p>the 2nd through 10th replacement values if $m1 is not an
array.</p>
</dd>
</dl>
The database is searched for rows with a lang.message_id that
matches $key. If a translation is not found, the original $key
is used. The translation engine then replaces all tokens of the
form %N with the Nth parameter (either $m1[N] or $mN).
<h4>Adding translation data</h4>
<p>The <b>TranslationTools</b> (former developer_tools) allow easily create new translations of eGW applications.<br />
A developer also can use them to create the english lang-file by searching for new phrases in his sources.</p>
<h4>The lang table</h4>
<p>The translation class uses the lang table for all
translations. We are concerned with 4 of the columns to create
a translation:</p>
<dl compact="compact">
<dd>
[message_id&nbsp;]&nbsp;
<p>The key to identify the message (the $key passed to the
lang() function). This is written in English.</p>
</dd>
<dd>
[app_name&nbsp;]&nbsp;
<p>The application the translation applies to, or common if
it is common across multiple applications.</p>
</dd>
<dd>
[lang&nbsp;]&nbsp;
<p>The code for the language the translation is in.</p>
</dd>
<dd>
[content&nbsp;]&nbsp;
<p>The translated string.</p>
</dd>
</dl>
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.
<h3><a name="tth_sEc7.3">7.3</a>&nbsp;&nbsp;Common return
codes</h3>
<p>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.</p>
<p>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.</p>
<p>For example, calling</p>
<pre>
echo check_code(13);
</pre>
Would print
<pre>
Your message has been sent
</pre>
translated into the current language.
<h2><a name="tth_sEc8">8</a>&nbsp;&nbsp;Using Templates</h2>
<h3><a name="tth_sEc8.1">8.1</a>&nbsp;&nbsp;Overview</h3>
<p>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.</p>
<h3><a name="tth_sEc8.2">8.2</a>&nbsp;&nbsp;How to use PHPLIB
templates</h3>
<p>For Further info read the PHPLIBs documentation for their
template class. <a href=
"http://phplib.sanisoft.com"><tt>http://phplib.sanisoft.com</tt></a></p>
<h3><a name="tth_sEc8.3">8.3</a>&nbsp;&nbsp;How to use
eTemplate templates</h3>
<p><b>eTemplate</b> is a new widget-based template system,
which is used eg. for the InfoLog application.<br />
There's a <a href="../../etemplate/doc/etemplate.html">Tutorial</a>
and a <a href="../../etemplate/doc/referenz.html">Referenz
documentation</a> availible.</p>
<h2><a name="tth_sEc9">9</a>&nbsp;&nbsp;About this
document</h2>
<h3><a name="tth_sEc9.1">9.1</a>&nbsp;&nbsp;New versions</h3>
<p>The newest version of this document can be found on our
website <a href=
"http://www.eGroupWare.org/egroupware/phpgwapi/doc/"><tt>http://www.eGroupWare.org</tt></a>.</p>
<h3><a name="tth_sEc9.2">9.2</a>&nbsp;&nbsp;Comments</h3>
<p>Comments on this HOWTO should be directed to the <a href=
"mailto:eGroupWare-developers%20-AT-%20lists.sourceforge.net">eGroupWare
developers mailing list</a> (subscription at <a href=
"http://www.sourceforge.net/egroupware/">www.sourceforge.net/egroupware/</a>).</p>
<h3><a name="tth_sEc9.3">9.3</a>&nbsp;&nbsp;History</h3>
<p>This document was written by Dan Kuykendall.</p>
<p>2000-09-25 documentation on lang(), codes, administration
and preferences extension added by Steve Brown.</p>
<p>2001-01-08 fixed directory structure, minor layout changes,
imported to lyx source - Darryl VanDorp</p>
<p>2001-01-08 fixed directory structure, minor layout changes,
imported to lyx source - Darryl VanDorp</p>
<p>2004-02-22 imported skwashd's changes and adapted for
eGroupWare - Ralf Becker</p>
<h3><a name="tth_sEc9.4">9.4</a>&nbsp;&nbsp;Copyrights and
Trademarks</h3>
<p>Copyright &copy; 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.</p>
<p>A copy of the license is available at <a href=
"http://www.gnu.org/copyleft/gpl.html"><tt>http://www.gnu.org/copyleft/gpl.html</tt></a></p>
<h3><a name="tth_sEc9.5">9.5</a>&nbsp;&nbsp;Acknowledgments and
Thanks</h3>
<p>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.<br>
<br>
</p>
<hr>
<p>$Id: index.html,v 1.5 2004/02/23 00:24:21 ralfbecker Exp
$</p>
</body>
</html>