[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Phpgroupware-cvs] phpgwapi/doc/index.html, 1.4
|
From: |
nomail |
|
Subject: |
[Phpgroupware-cvs] phpgwapi/doc/index.html, 1.4 |
|
Date: |
Thu, 30 Dec 2004 07:47:26 +0100 |
Update of /phpgwapi/doc
Added Files:
Branch:
index.html
date: 2004/12/30 06:47:26; author: skwashd; state: Exp; lines: +997 -1342
Log Message:
new HEAD
=====================================================================
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
<html xmlns="http://www.w3.org/1999/xhtml";>
<head>
<link rel="stylesheet" type="text/css" href="./styles/screen.css"
media="screen" />
<link rel="stylesheet" type="text/css" href="./styles/print.css"
media="print" />
<link rel="stylesheet" type="text/css" href="./styles/dev-guide.css"
media="all" />
<title>phpGroupWare - Developers Guide</title>
</head>
<body>
<div>
<div id="printheader">
<img src="./pics/logo.png" alt="phpGW logo" />Developers Guide
</div>
<div id="top">
<img src="./pics/logo.png" alt="phpGroupWare" />
<div id="sitename">
<a href="./">Contributor Documentation</a>
</div>
</div>
<div id="content">
<h1>phpGroupWare Application Development</h1>
<h3>phpGroupWare Documentation Team - phpgroupware-docteam at
gnu.org</h3>
<h4>v0.9.16.001 5 September 2004</h4>
<blockquote>
This document explains phpGroupWare'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>
<ol>
<li><a href="#tth_sEc1.1">Overview of application writing</a></li>
<li><a href="#tth_sEc1.2">What does the phpGroupWare API
provide?</a></li>
</ol>
</li>
<li>
<a href="#tth_sEc2">Guidelines</a>
<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>
<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 phpGroupWare 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>
<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>
<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>
<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>
<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>
<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 XSLT templates</a></li>
</ol>
</li>
<li>
<a href="#tth_sEc9">About this document</a>
<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" id="tth_sEc1" class="heading">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.</p>
<h3><a name="tth_sEc1.1" id="tth_sEc1.1">1.1</a> Overview of application
writing</h3>
<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.</p>
<h3><a name="tth_sEc1.2" id="tth_sEc1.2">1.2</a> What does the
phpGroupWare API provide?</h3>
<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.</p>
<p>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.</p>
<h2><a name="tth_sEc2" id="tth_sEc2" class="heading">2 Guidelines</a></h2>
<h3><a name="tth_sEc2.1" id="tth_sEc2.1">2.1</a> Requirements</h3>
<p>These guidelines must be followed for any application that wants
considered for inclusion into the phpGroupWare distribution:</p>
<ul>
<li>It must run on PHP 4.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']->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 phpGW group rights and phpGW 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 phpGroupWare "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" id="tth_sEc2.2">2.2</a> 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>
<?php
$GLOBALS['phpgw_info']['flags']['currentapp'] = 'appname';
include('../header.inc.php');
?>
</pre>
<p>Of course change application name to fit.<br />
This include will provide the following things:</p>
<ul>
<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.<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 phpGW footer will be loaded, which closes several
connections.</li>
</ul>
<h2><a name="tth_sEc3" id="tth_sEc3" class="heading">3 Installing your
application</a></h2>
<h3><a name="tth_sEc3.1" id="tth_sEc3.1">3.1</a> Overview</h3>
<p>It is fairly simple to add and delete applications to/from
phpGroupWare.</p>
<h3><a name="tth_sEc3.2" id="tth_sEc3.2">3.2</a> 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->common->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->common->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" id="tth_sEc3.3">3.3</a> 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" id="tth_sEc3.4">3.4</a> Making phpGroupWare
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 phpGroupWare
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" id="tth_sEc3.5">3.5</a> 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><?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);
?>;</pre>
<p>Look at headlines/inc/hook_admin.inc.php and
admin/inc/hook_admin.inc.php for more examples.</p>
<p>Things to note:</p>
<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" id="tth_sEc3.6">3.6</a> 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" id="tth_sEc4" class="heading">4<
Infrastructure</a></h2>
<h3><a name="tth_sEc4.1" id="tth_sEc4.1">4.1</a> Overview</h3>
<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 accommodate a large number of
applications and functions.</p>
<h3><a name="tth_sEc4.2" id="tth_sEc4.2">4.2</a> Directory tree</h3>
<pre>
--phpgroupware
|
+--admin
|
+--docs (installation docs)
|
+--files (<b>Note:</b> must be out of webserver document root!)
| |
| +--groups
| |
| +--homes
| |
| +--users
|
+--phpgwapi
| |
| +--cron (phpgroupware'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" id="tth_sEc4.3">4.3</a> Translations</h3>
<p>See <a href="#tth_sEc7">section 7</a>, where this is explained in
detail.</p>
<h2><a name="tth_sEc5" id="tth_sEc5" class="heading">5 The API</a></h2>
<h3><a name="tth_sEc5.1" id="tth_sEc5.1">5.1</a> Introduction</h3>
<p>phpGroupWare 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']->.</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->send->msg() is in the
inc/phpgwapi/class.send.inc.php file.</p>
<h3><a name="tth_sEc5.2" id="tth_sEc5.2">5.2</a> Basic functions</h3>
<h4>$GLOBALS['phpgw']->link</h4>
<p>$GLOBALS['phpgw']->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>
<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"> */
</pre>
<h3><a name="tth_sEc5.3" id="tth_sEc5.3">5.3</a> Application
Functions</h3>
<h4>$GLOBALS['phpgw']->common->phpgw_header</h4>
<p>$GLOBALS['phpgw']->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']->common->phpgw_footer</h4>
<p>$GLOBALS['phpgw']->phpgw_footer()<br />
Prints the system footer, and includes appname/inc/footer.php</p>
<h4>$GLOBALS['phpgw']->common->appsession</h4>
<p>$GLOBALS['phpgw']->common->appsession($data)<br />
Store important information session information that your application
needs.<br />
$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.<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']->common->appsession("/path/to/something");
echo "Dir: " . $GLOBALS['phpgw']->common->appsession();
</pre>
<h3><a name="tth_sEc5.4" id="tth_sEc5.4">5.4</a> 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" id="tth_sEc5.5">5.5</a> Email/NNTP
Functions</h3>
<h4>$phpgw->send->msg</h4>
<p>$phpgw->msg->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 = 'address@hidden';
$subject = 'Hello buddy';
$body = "Give me a call\n Been wondering what your up to.";
$errors = $GLOBALS['phpgw']->msg->send('email', $to, $subject,
$body);</pre>
<h2><a name="tth_sEc6" id="tth_sEc6" class="heading">6 Configuration
Variables</a></h2>
<h3><a name="tth_sEc6.1" id="tth_sEc6.1">6.1</a> Introduction</h3>
<p>phpGroupWare 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><?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'
?></pre>
<pre><?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'
?></pre>
<h3><a name="tth_sEc6.2" id="tth_sEc6.2">6.2</a> User information</h3>
<pre>$GLOBALS['phpgw_info']['user']['userid'] = The user ID.
$GLOBALS['phpgw_info']['user']['sessionid'] = The session ID
$GLOBALS['phpgw_info']['user']['theme'] = Selected theme
$GLOBALS['phpgw_info']['user']['private_dir'] = Users private dir.
Use phpGroupWare core functions for access to the files.
$GLOBALS['phpgw_info']['user']['firstname'] = Users first name
$GLOBALS['phpgw_info']['user']['lastname'] = Users last name
$GLOBALS['phpgw_info']['user']['fullname'] = Users Full Name
$GLOBALS['phpgw_info']['user']['groups'] = Groups the user is a member of
$GLOBALS['phpgw_info']['user']['app_perms'] = If the user has access to the
current application
$GLOBALS['phpgw_info']['user']['lastlogin'] = Last time the user logged in.
$GLOBALS['phpgw_info']['user']['lastloginfrom'] = Where they logged in from the
last time.
$GLOBALS['phpgw_info']['user']['lastpasswd_change'] = Last time they changed
their password.
$GLOBALS['phpgw_info']['user']['passwd'] = Hashed password.
$GLOBALS['phpgw_info']['user']['status'] = If the user is enabled.
$GLOBALS['phpgw_info']['user']['logintime'] = Time they logged into their
current session.
$GLOBALS['phpgw_info']['user']['session_dla'] = Last time they did anything in
their current session
$GLOBALS['phpgw_info']['user']['session_ip'] = Current IP address
</pre>
<h3><a name="tth_sEc6.3" id="tth_sEc6.3">6.3</a> Group information</h3>
<pre>$GLOBALS['phpgw_info']['group']['group_names'] = List of
groups.</pre>
<h3><a name="tth_sEc6.4" id="tth_sEc6.4">6.4</a> Server information</h3>
<pre>
$GLOBALS['phpgw_info']['server']['server_root'] = Main installation directory
$GLOBALS['phpgw_info']['server']['include_root'] = Location of the 'inc'
directory.
$GLOBALS['phpgw_info']['server']['temp_dir'] = Directory that can be used for
temporarily storing files
$GLOBALS['phpgw_info']['server']['files_dir'] = Directory user and group files
are stored
$GLOBALS['phpgw_info']['server'']['common_include_dir'] = Location of the
core/shared include files.
$GLOBALS['phpgw_info']['server']['template_dir'] = Active template files
directory.
This is defaulted by the server, and changeable by the user.
$GLOBALS['phpgw_info']['server']['dir_separator'] = Allows compatibility with
WindowsNT directory format
- same as php constant SEP
$GLOBALS['phpgw_info']['server']['encrpytkey'] = Key used for encryption
functions
$GLOBALS['phpgw_info']['server']['site_title'] = Site Title will show in the
title bar of each webpage.
$GLOBALS['phpgw_info']['server']['webserver_url'] = URL to phpGroupWare
installation.
$GLOBALS['phpgw_info']['server']['hostname'] = Name of the server phpGroupWare
is installed upon.
$GLOBALS['phpgw_info']['server']['charset'] = user's charset, default:iso-8859-1
$GLOBALS['phpgw_info']['server']['version'] = phpGroupWare version.
</pre>
<h3><a name="tth_sEc6.5" id="tth_sEc6.5">6.5</a> Database
information</h3>
<p>It is unlikely you will need these, because $GLOBALS['phpgw']->db
will already be loaded as a database for you to use.</p>
<pre>
$GLOBALS['phpgw_info']['server']['db_host'] = Address of the database server.
Usually this is set to localhost - but don't assume.
$GLOBALS['phpgw_info']['server']['db_name'] = Database name.
$GLOBALS['phpgw_info']['server']['db_user'] = User name.
$GLOBALS['phpgw_info']['server']['db_pass'] = Password
$GLOBALS['phpgw_info']['server']['db_type'] = Type of database.
Currently M$ SQL Server, MySQL and PostgreSQL are supported.
</pre>
<h3><a name="tth_sEc6.6" id="tth_sEc6.6">6.6</a> Mail information</h3>
<p>It is unlikely you will need these, because most email needs are
services thru core phpGroupWare functions.</p>
<pre>
$GLOBALS['phpgw_info']['server']['mail_server'] = Address of the IMAP server.
Usually this is set to localhost.
$GLOBALS['phpgw_info']['server']['mail_server_type'] = IMAP or POP3
$GLOBALS['phpgw_info']['server']['imap_server_type'] = Courier/Cyrus, Uwash or
UW-Maildir
$GLOBALS['phpgw_info']['server']['imap_port'] = This is usually 143.
Should only be changed if there is a good reason.
$GLOBALS['phpgw_info']['server']['mail_suffix'] = This is the domain name, used
to add to email address
$GLOBALS['phpgw_info']['server']['mail_login_type'] = This adds support for
VMailMgr.
Generally this should be set to 'standard'.
$GLOBALS['phpgw_info']['server']['smtp_server'] = Address of the SMTP server.
Usually this is set to localhost.
$GLOBALS['phpgw_info']['server']['smtp_port'] = This is usually 25.
Should only be changed if there is a good reason
</pre>
<h3><a name="tth_sEc6.7" id="tth_sEc6.7">6.7</a> NNTP information</h3>
<pre>
$GLOBALS['phpgw_info']['server']['nntp_server'] = Address of the NNTP server.
$GLOBALS['phpgw_info']['server']['nntp_port'] = This is usually 119.
Should only be changed if there is a good reason.
$GLOBALS['phpgw_info']['server']['nntp_sender'] = Unknown
$GLOBALS['phpgw_info']['server']['nntp_organization'] = Unknown
$GLOBALS['phpgw_info']['server']['nntp_admin'] = Unknown
</pre>
<h3><a name="tth_sEc6.8" id="tth_sEc6.8">6.8</a> Application
information</h3>
<p>Each application has the following information available.</p>
<pre>
$GLOBALS['phpgw_info']['apps'][$appname]['title'] = The title of the
application.
$GLOBALS['phpgw_info']['apps'][$appname]['enabled'] = If the application is
enabled. True or False.
$GLOBALS['phpgw_info']['server']['app_include_dir'] = Location of the current
application include files.
$GLOBALS['phpgw_info']['server']['app_template_dir'] = Location of the current
application tpl files.
$GLOBALS['phpgw_info']['server']['app_lang_dir'] = Location of the current lang
directory.
$GLOBALS['phpgw_info']['server']['app_auth'] = <b>DEPRECATED?</b>
If the server and current user have access to current application
$GLOBALS['phpgw_info']['server']['app_current'] = name of the current
application.
</pre>
<h2><a name="tth_sEc7" id="tth_sEc7" class="heading">7 Using Language
Support</a></h2>
<h3><a name="tth_sEc7.1" id="tth_sEc7.1">7.1</a> Overview</h3>
<p>phpGroupWare 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 phpGroupWare database, and
can be modified by the phpGroupWare administrator.</p>
<h3><a name="tth_sEc7.2" id="tth_sEc7.2">7.2</a> How to use lang
support</h3>
<p>The lang() function is your application's interface to phpGroupWare'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).'<br />';</pre>
<p>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>
<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*<br /></pre>
<p>If the current user speaks Italian, the string returned will be:</p>
<pre>il contatore è 42<br /></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]
<p>is the string to translate and may contain replacement directives
of the form %n. This string should be lower case.</p>
</dd>
<dd>
[$m1]
<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 - $m10]
<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>An application called <b>Translation Tools</b> has been developed to
make this
easier. Please use this application or edit the lang files manually.
The table
information is here as a reference, but direct database insertions should
not
be used.</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]
<p>The key to identify the message (the $key passed to the lang()
function). This is written in English.</p>
</dd>
<dd>
[app_name]
<p>The application the translation applies to, or common if it is
common across multiple applications.</p>
</dd>
<dd>
[lang]
<p>The code for the language the translation is in.</p>
</dd>
<dd>
[content]
<p>The translated string.</p>
</dd>
</dl>
<h4>phpgw_??.lang</h4>
<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_<langcode>.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>
<p>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.</p>
<h3><a name="tth_sEc7.3" id="tth_sEc7.3">7.3</a> Common return codes</h3>
<p>If you browse through the phpGroupWare 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>
<p>Would print</p>
<pre>Your message has been sent</pre>
<p>translated into the current language.</p>
<h2><a name="tth_sEc8" id="tth_sEc8" class="heading">8 Using
Templates</a></h2>
<h3><a name="tth_sEc8.1" id="tth_sEc8.1">8.1</a> Overview</h3>
<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.</p>
<p>phpGroupWare is changing template engines for the 0.9.18 release. All
versions of phpGroupWare upto 0.9.16 use the PHPLIB template engine. As
of the 0.9.18 release phpGroupWare will use a "home grown" XSLT based
template engine.</p>
<h3><a name="tth_sEc8.2" id="tth_sEc8.2">8.2</a> 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" id="tth_sEc8.3">8.3</a> How to use XSLT
templates</h3>
<p>Whoops, there is no documentation available on this - hassle the
docteam to produce something.</p>
<h2><a name="tth_sEc9" id="tth_sEc9" class="heading">9 About this
document</a></h2>
<h3><a name="tth_sEc9.1" id="tth_sEc9.1">9.1</a> New versions</h3>
<p>The newest version of this document can be found on our website
<a href=
"http://docs.phpgroupware.org/contrib";>http://docs.phpgroupware.org</a>
as HTML and plain text.</p>
<h3><a name="tth_sEc9.2" id="tth_sEc9.2">9.2</a> Comments</h3>
<p>Comments on this HOWTO should be directed to the phpGroupWare
developers mailing list phpgroupware-docteam at gnu.org</p>
<p>To subscribe, go to <a href=
"http://support.phpgroupware.org/lists";>http://support.phpgroupware.org/lists</a></p>
<h3><a name="tth_sEc9.3" id="tth_sEc9.3">9.3</a> History</h3>
<ul>
<li>This document was written by Dan Kuykendall.</li>
<li><em>2000-09-25</em><br />
documentation on lang(), codes, administration and preferences
extension added by Steve Brown.</li>
<li><em>2001-01-08</em><br />
fixed directory structure, minor layout changes, imported to lyx source
- Darryl VanDorp</li>
<li><em>2003-12-01</em><br />
Started clean up - skwashd</li>
<li><em>2004-08-04</em><br />
More cleaning up - skwashd</li>
</ul>
<h3><a name="tth_sEc9.4" id="tth_sEc9.4">9.4</a> Copyrights and
Trademarks</h3>
<p>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.</p>
<p>A copy of the license is available at <a href=
"http://www.gnu.org/copyleft/fdl.html";>http://www.gnu.org/copyleft/fdl.html</a></p>
<h3><a name="tth_sEc9.5" id="tth_sEc9.5">9.5</a> Acknowledgments and
Thanks</h3>
<p>Thanks to Joesph Engo for starting phpGroupWare (at the time called
webdistro). Thanks to all the developers and users who contribute to
making phpGroupWare such a success.</p>
</div>
<div id="footer">
The most recent version of this document can be found at <a href=
"http://docs.phpgroupware.org/contrib/";>docs.phpgroupware.org</a><br />
Copyright © 2000-2004 <a href="http://www.fsf.org"; target=
"_blank">Free Software Foundation Inc</a>, distributed under the terms of
the <a href="http://www.gnu.org/copyleft/fdl.html"; target="_blank">GNU
Free Documentation License</a><br />
<b>Source:</b> $Source: /cvsroot/phpgwapi/phpgwapi/doc/index.html,v $<br
/>
<b>Version:</b> $Revision: 1.4 $<br />
<b>Last Modified:</b> $Date: 2004/12/30 06:47:26 $ by $Author: skwashd $
</div>
</div>
</body>
</html>