mirror of
https://github.com/EGroupware/egroupware.git
synced 2024-10-06 18:12:22 +02:00
1343 lines
36 KiB
HTML
1343 lines
36 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
|
||
"http://www.w3.org/TR/REC-html40/loose.dtd">
|
||
<html>
|
||
<meta name="GENERATOR" content="TtH 2.86">
|
||
|
||
|
||
|
||
|
||
|
||
<title> phpGroupWare Application Development</title>
|
||
|
||
<h1 align="center"> phpGroupWare Application Development </h1>
|
||
|
||
<p>
|
||
|
||
<title> phpGroupWare Application Development</title>
|
||
|
||
<h1 align="center">phpGroupWare Application Development </h1>
|
||
|
||
<p>
|
||
|
||
<h3 align="center">Dan Kuykendall <dan@kuykendall.org> </h3>
|
||
|
||
<p>
|
||
|
||
<h3 align="center">v0.9 29 September 2000 </h3>
|
||
|
||
<p>
|
||
|
||
<blockquote><em>This document explains phpGroupWare's infrastructure and API,
|
||
along with what is required to integrate applications into it.</em>
|
||
</blockquote>
|
||
|
||
<h1>Contents </h1>
|
||
<a href="#tth_sEc1"
|
||
>1 Introduction</a><br />
|
||
<a href="#tth_sEc1.1"
|
||
>1.1 Overview of application writing</a><br />
|
||
<a href="#tth_sEc1.2"
|
||
>1.2 What does the phpGroupWare API provide?</a><br />
|
||
<a href="#tth_sEc2"
|
||
>2 Guidelines</a><br />
|
||
<a href="#tth_sEc2.1"
|
||
>2.1 Requirements</a><br />
|
||
<a href="#tth_sEc2.2"
|
||
>2.2 Writing/porting your application</a><br />
|
||
<a href="#tth_sEc3"
|
||
>3 Installing your application</a><br />
|
||
<a href="#tth_sEc3.1"
|
||
>3.1 Overview</a><br />
|
||
<a href="#tth_sEc3.2"
|
||
>3.2 Automatic features</a><br />
|
||
<a href="#tth_sEc3.3"
|
||
>3.3 Adding files, directories and icons.</a><br />
|
||
<a href="#tth_sEc3.4"
|
||
>3.4 Making phpGroupWare aware of your application</a><br />
|
||
<a href="#tth_sEc3.5"
|
||
>3.5 Hooking into Administration page</a><br />
|
||
<a href="#tth_sEc3.6"
|
||
>3.6 Hooking into Preferences page</a><br />
|
||
<a href="#tth_sEc4"
|
||
>4 Infrastructure</a><br />
|
||
<a href="#tth_sEc4.1"
|
||
>4.1 Overview</a><br />
|
||
<a href="#tth_sEc4.2"
|
||
>4.2 Directory tree</a><br />
|
||
<a href="#tth_sEc4.3"
|
||
>4.3 Translations</a><br />
|
||
<a href="#tth_sEc5"
|
||
>5 The API</a><br />
|
||
<a href="#tth_sEc5.1"
|
||
>5.1 Introduction</a><br />
|
||
<a href="#tth_sEc5.2"
|
||
>5.2 Basic functions</a><br />
|
||
<a href="#tth_sEc5.3"
|
||
>5.3 Application Functions</a><br />
|
||
<a href="#tth_sEc5.4"
|
||
>5.4 File functions</a><br />
|
||
<a href="#tth_sEc5.5"
|
||
>5.5 Email/NNTP Functions</a><br />
|
||
<a href="#tth_sEc6"
|
||
>6 Configuration Variables</a><br />
|
||
<a href="#tth_sEc6.1"
|
||
>6.1 Introduction</a><br />
|
||
<a href="#tth_sEc6.2"
|
||
>6.2 User information</a><br />
|
||
<a href="#tth_sEc6.3"
|
||
>6.3 Group information</a><br />
|
||
<a href="#tth_sEc6.4"
|
||
>6.4 Server information</a><br />
|
||
<a href="#tth_sEc6.5"
|
||
>6.5 Database information</a><br />
|
||
<a href="#tth_sEc6.6"
|
||
>6.6 Mail information</a><br />
|
||
<a href="#tth_sEc6.7"
|
||
>6.7 NNTP information</a><br />
|
||
<a href="#tth_sEc6.8"
|
||
>6.8 Application information</a><br />
|
||
<a href="#tth_sEc7"
|
||
>7 Using Language Support</a><br />
|
||
<a href="#tth_sEc7.1"
|
||
>7.1 Overview</a><br />
|
||
<a href="#tth_sEc7.2"
|
||
>7.2 How to use lang support</a><br />
|
||
<a href="#tth_sEc7.3"
|
||
>7.3 Common return codes</a><br />
|
||
<a href="#tth_sEc8"
|
||
>8 Using Templates</a><br />
|
||
<a href="#tth_sEc8.1"
|
||
>8.1 Overview</a><br />
|
||
<a href="#tth_sEc8.2"
|
||
>8.2 How to use templates</a><br />
|
||
<a href="#tth_sEc9"
|
||
>9 About this document</a><br />
|
||
<a href="#tth_sEc9.1"
|
||
>9.1 New versions </a><br />
|
||
<a href="#tth_sEc9.2"
|
||
>9.2 Comments </a><br />
|
||
<a href="#tth_sEc9.3"
|
||
>9.3 History </a><br />
|
||
<a href="#tth_sEc9.4"
|
||
>9.4 Copyrights and Trademarks </a><br />
|
||
<a href="#tth_sEc9.5"
|
||
>9.5 Acknowledgments and Thanks </a><br />
|
||
|
||
|
||
<p>
|
||
<h2><a name="tth_sEc1">
|
||
1</a> Introduction</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">
|
||
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">
|
||
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>
|
||
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">
|
||
2</a> Guidelines</h2>
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc2.1">
|
||
2.1</a> Requirements</h3>
|
||
|
||
<p>
|
||
These guidelines must be followed for any application that wants considered
|
||
for inclusion into phpGroupWare deluxe:
|
||
|
||
<p>
|
||
|
||
<ul><p>
|
||
<li> It must run on PHP3 and PHP4.</li>
|
||
<p>
|
||
<li> SQL statements must be compatible with both MySQL and PostgreSQL.</li>
|
||
<p>
|
||
<li> It must use our default header.inc.php include.</li>
|
||
<p>
|
||
<li> It must use our $phpgw_link($url) for all links (this is for session
|
||
support).</li>
|
||
<p>
|
||
<li> It must use ``post'' for forms.</li>
|
||
<p>
|
||
<li> It must respect phpGW group rights and phpGW user permissions.</li>
|
||
<p>
|
||
<li> It must use our directory structure, template support and lang (multi-language)
|
||
support.</li>
|
||
<p>
|
||
<li> Where possible it should run on both Unix and NT platforms.</li>
|
||
<p>
|
||
<li> For applications that do not meet these requirements, they can be
|
||
available to users via the phpGroupWare Apps project, or whatever
|
||
means the developers decide. 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>
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc2.2">
|
||
2.2</a> Writing/porting your application</h3>
|
||
|
||
<p>
|
||
|
||
<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.
|
||
<pre>
|
||
|
||
<?php
|
||
$phpgw_info["flags"]["currentapp"] = "appname";
|
||
include("../header.inc.php");
|
||
?>
|
||
|
||
|
||
</pre>Of course change application name to fit.<br />
|
||
This include will provide the following things:
|
||
|
||
<p>
|
||
|
||
<ul><p>
|
||
<li> The phpgwAPI - The phpGroupWare API will be loaded.</li>
|
||
<p>
|
||
<li> The phpGW navbar will be loaded (by default, but can be disabled until
|
||
a later point.</li>
|
||
<p>
|
||
<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>
|
||
<p>
|
||
<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>
|
||
<p>
|
||
<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.</li>
|
||
<p>
|
||
<li> The phpGW footer will be loaded, which closes several connections.</li>
|
||
</ul>
|
||
|
||
<p>
|
||
<h2><a name="tth_sEc3">
|
||
3</a> Installing your application</h2>
|
||
|
||
<p>
|
||
<h3><a name="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">
|
||
3.2</a> Automatic features</h3>
|
||
|
||
<p>
|
||
To make things easy for developers we go ahead and load the following
|
||
files.
|
||
|
||
<p>
|
||
|
||
<ul><p>
|
||
<li> appname/inc/functions.inc.php - This file should include all your
|
||
application specific functions.</li>
|
||
<p>
|
||
<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.</li>
|
||
<p>
|
||
<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.</li>
|
||
</ul>
|
||
|
||
<p>
|
||
<h3><a name="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>
|
||
<tt>`--appname</tt>
|
||
|
||
<p>
|
||
<tt> |--inc</tt>
|
||
|
||
<p>
|
||
<tt> | |--functions.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | |--header.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | |--hook_preferences.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | |--hook_admin.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | `--footer.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> `--templates</tt>
|
||
|
||
<p>
|
||
<tt> | `--default</tt>
|
||
|
||
<p>
|
||
|
||
<dl compact="compact"><dt><b></b></dt>
|
||
<dd>
|
||
|
||
<p>
|
||
</dl> <h3><a name="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.
|
||
<pre>
|
||
|
||
insert into applications (app_name, app_title, app_enabled) values ('appname', 'The App name', 1);
|
||
|
||
|
||
</pre>
|
||
|
||
<p>
|
||
<h3><a name="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>
|
||
Simple Example:
|
||
<pre>
|
||
|
||
<?php
|
||
$img = "/" . $appname . "/images/navbar.gif";
|
||
section_start("My Application",$img);
|
||
echo "<a HREF=\"" . $phpgw->link("myAdminPage.php") . "\">";
|
||
echo lang("Change myApp settings") . "</a>";
|
||
section_end();
|
||
?>
|
||
|
||
|
||
</pre>Look at headlines/inc/hook_admin.inc.php and admin/inc/hook_admin.inc.php
|
||
for more examples.
|
||
|
||
<p>
|
||
Things to note:
|
||
|
||
<p>
|
||
|
||
<ul><p>
|
||
<li> Links are relative to the admin/index.php file, not your application's
|
||
base directory. (so use $appname in your link() calls)</li>
|
||
<p>
|
||
<li> The file is brought in with include() so be careful to not pollute
|
||
the name-space too much</li>
|
||
</ul>
|
||
The standard $phpgw and $phpgw_info variables are in-scope, as
|
||
is $appname which corresponds to the application name in the path.
|
||
|
||
<p>
|
||
There are 2 functions to coordinate the display of each application's
|
||
links, section_start() and section_end()
|
||
|
||
<p>
|
||
|
||
<h4>section_start</h4>
|
||
|
||
<p>
|
||
section_start($title,$icon_url) starts the section for your application.
|
||
$title is passed through lang() for you. $icon_url should be page-relative
|
||
to admin/index.php or an absolute URL.
|
||
|
||
<p>
|
||
|
||
<h4>section_end</h4>
|
||
|
||
<p>
|
||
section_end() closes the section that was started with section_start().
|
||
|
||
<p>
|
||
<h3><a name="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">
|
||
4</a> Infrastructure</h2>
|
||
|
||
<p>
|
||
<h3><a name="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">
|
||
4.2</a> Directory tree</h3>
|
||
|
||
<p>
|
||
<tt>.--appname</tt>
|
||
|
||
<p>
|
||
<tt>| |--inc</tt>
|
||
|
||
<p>
|
||
<tt>| | |--functions.inc.php</tt>
|
||
|
||
<p>
|
||
<tt>| | |--header.inc.php</tt>
|
||
|
||
<p>
|
||
<tt>| | |--hook_preferences.ini.php</tt>
|
||
|
||
<p>
|
||
<tt>| | |--hook_home.inc.php</tt>
|
||
|
||
<p>
|
||
<tt>| | `--footer.inc.php</tt>
|
||
|
||
<p>
|
||
<tt>| |--manual</tt>
|
||
|
||
<p>
|
||
<tt>| |--setup</tt>
|
||
|
||
<p>
|
||
<tt>| | |--baseline.inc.php</tt>
|
||
|
||
<p>
|
||
<tt>| | |--droptables.inc.php</tt>
|
||
|
||
<p>
|
||
<tt>| | |--newtables.inc.php</tt>
|
||
|
||
<p>
|
||
<tt>| | |--upgradetables.inc.php</tt>
|
||
|
||
<p>
|
||
<tt>| | |--config.inc.php</tt>
|
||
|
||
<p>
|
||
<tt>| | `--register.inc.php</tt>
|
||
|
||
<p>
|
||
<tt>| `--templates</tt>
|
||
|
||
<p>
|
||
<tt>| | `--default</tt>
|
||
|
||
<p>
|
||
<tt>| | `--images</tt>
|
||
|
||
<p>
|
||
<tt>| | `--navbar.gif</tt>
|
||
|
||
<p>
|
||
<tt>| |--preferences.php</tt>
|
||
|
||
<p>
|
||
<tt>|--docs (installation docs)</tt>
|
||
|
||
<p>
|
||
<tt>|--files</tt>
|
||
|
||
<p>
|
||
<tt>| |--groups</tt>
|
||
|
||
<p>
|
||
<tt>| `--users</tt>
|
||
|
||
<p>
|
||
<tt>`--phpgwapi</tt>
|
||
|
||
<p>
|
||
<tt> |--cron (phpgroupware's optional daemons)</tt>
|
||
|
||
<p>
|
||
<tt> |--doc (developers docs)</tt>
|
||
|
||
<p>
|
||
<tt> |--inc</tt>
|
||
|
||
<p>
|
||
<tt> | |--phpgw.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | |--phpgw_info.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | |--phpgw_common.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | `--etc..</tt>
|
||
|
||
<p>
|
||
<tt> |--manual </tt>
|
||
|
||
<p>
|
||
<tt> |--setup</tt>
|
||
|
||
<p>
|
||
<tt> | |--baseline.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | |--droptables.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | |--newtables.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | |--upgradetables.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | |--config.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> | `--register.inc.php</tt>
|
||
|
||
<p>
|
||
<tt> |--templates</tt>
|
||
|
||
<p>
|
||
<tt> | |--default</tt>
|
||
|
||
<p>
|
||
<tt> | | `--images</tt>
|
||
|
||
<p>
|
||
<tt> | | |--home.gif</tt>
|
||
|
||
<p>
|
||
<tt> | | `--preferences.gif</tt>
|
||
|
||
<p>
|
||
<tt> | `--verilak</tt>
|
||
|
||
<p>
|
||
<tt> | `--images</tt>
|
||
|
||
<p>
|
||
<tt> |--home.gif</tt>
|
||
|
||
<p>
|
||
<tt> `--preferences.gif</tt>
|
||
|
||
<p>
|
||
<tt> `--themes</tt>
|
||
|
||
<p>
|
||
<tt> `--default.theme</tt>
|
||
|
||
<p>
|
||
|
||
<dl compact="compact"><dt><b></b></dt>
|
||
<dd>
|
||
|
||
<p>
|
||
</dl> <h3><a name="tth_sEc4.3">
|
||
4.3</a> Translations</h3>
|
||
|
||
<p>
|
||
The translations are now being done thru the database, and will be
|
||
configurable to use other mechanisms.
|
||
|
||
<p>
|
||
We are completing a program called Transy, which will provide developers/translators
|
||
a nice GUI for building and updating translations.
|
||
|
||
<p>
|
||
In the mean time you will need to create a SQL script yourself and
|
||
name it lang.sql. You can copy the one in doc/lang.sql and use it
|
||
as a template.
|
||
|
||
<p>
|
||
<h2><a name="tth_sEc5">
|
||
5</a> The API</h2>
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc5.1">
|
||
5.1</a> Introduction</h3>
|
||
|
||
<p>
|
||
phpGroupWare attempts to provide developers with a useful API to handle
|
||
common tasks.
|
||
|
||
<p>
|
||
To do this we have created a multi-dimensional class $phpgw->.
|
||
|
||
<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>
|
||
Example: $phpgw->send->msg() is in the inc/phpgwapi/phpgw_send.inc.php
|
||
file.
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc5.2">
|
||
5.2</a> Basic functions</h3>
|
||
|
||
<p>
|
||
|
||
<h4>$phpgw->link</h4>
|
||
|
||
<p>
|
||
$phpgw->link($url)<br />
|
||
Add support for session management. ALL links must use this, that
|
||
includes href's form actions and header location's.
|
||
|
||
<p>
|
||
If you are just doing a form action back to the same page, you can
|
||
use it without any parameters.
|
||
|
||
<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:
|
||
|
||
<pre>
|
||
|
||
<form name=copy method=post action="<?php echo $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>
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc5.3">
|
||
5.3</a> Application Functions</h3>
|
||
|
||
<p>
|
||
|
||
<h4>$phpgw->common->phpgw_header</h4>
|
||
|
||
<p>
|
||
$phpgw->phpgw_header()<br />
|
||
Print out the start of the HTML page, including the navigation bar
|
||
and includes appname/inc/header.php
|
||
|
||
<p>
|
||
|
||
<h4>$phpgw->common->phpgw_footer</h4>
|
||
|
||
<p>
|
||
$phpgw->phpgw_footer()<br />
|
||
Prints the system footer, and includes appname/inc/footer.php
|
||
|
||
<p>
|
||
|
||
<h4>$phpgw->common->appsession</h4>
|
||
|
||
<p>
|
||
$phpgw->common->appsession($data)<br />
|
||
Store important information session information that your application
|
||
needs.<br />
|
||
$phpgw->appsession will return the value of your session data is
|
||
you leave the parameter empty [i.e. $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>
|
||
Example:
|
||
<pre>
|
||
|
||
$phpgw->common->appsession("/path/to/something");
|
||
echo "Dir: " . $phpgw->common->appsession();
|
||
|
||
|
||
</pre>
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc5.4">
|
||
5.4</a> File functions</h3>
|
||
|
||
<p>
|
||
|
||
<h4>$phpgw->vfs->read_file</h4>
|
||
|
||
<p>
|
||
$phpgw->vfs->read_file($file)<br />
|
||
Returns the data from $file.<br />
|
||
You must send the complete path to the file.<br />
|
||
Example:
|
||
<pre>
|
||
|
||
$data = $phpgw->vfs->read_file("/some/dir/to/file.txt");
|
||
|
||
|
||
</pre>
|
||
|
||
<p>
|
||
|
||
<h4>$phpgw->vfs->write_file</h4>
|
||
|
||
<p>
|
||
$phpgw->vfs->write_file($file, $contents)<br />
|
||
Write data to $file.<br />
|
||
You must send the complete path to the file.<br />
|
||
Example:
|
||
<pre>
|
||
|
||
$data = $phpgw->vfs->write_file("/some/dir/to/file.txt");
|
||
|
||
|
||
</pre>
|
||
|
||
<p>
|
||
|
||
<h4>$phpgw->vfs->read_userfile</h4>
|
||
|
||
<p>
|
||
$phpgw->vfs->read_userfile($file)<br />
|
||
Returns the data from $file, which resides in the users private
|
||
dir.<br />
|
||
Example:
|
||
<pre>
|
||
|
||
$data = $phpgw->vfs->read_userfile("file.txt");
|
||
|
||
|
||
</pre>
|
||
|
||
<p>
|
||
|
||
<h4>$phpgw->vfs->write_userfile</h4>
|
||
|
||
<p>
|
||
$phpgw->write_userfile($file, $contents)<br />
|
||
Writes data to $file, which resides in the users private dir.<br />
|
||
Example:
|
||
<pre>
|
||
|
||
$data = $phpgw->vfs->write_userfile("file.txt");
|
||
|
||
|
||
</pre>
|
||
|
||
<p>
|
||
|
||
<h4>$phpgw->vfs->list_userfiles</h4>
|
||
|
||
<p>
|
||
$phpgw->vfs->list_userfiles()<br />
|
||
Returns an array which has the list of files in the users private
|
||
dir.<br />
|
||
Example:
|
||
<pre>
|
||
|
||
$filelist = array();
|
||
$filelist = $phpgw->vfs->list_userfiles();
|
||
|
||
|
||
</pre>
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc5.5">
|
||
5.5</a> Email/NNTP Functions</h3>
|
||
|
||
<p>
|
||
|
||
<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:
|
||
<pre>
|
||
|
||
$to = "someuser@domain.com";
|
||
$subject = "Hello buddy";
|
||
$body = "Give me a call\n Been wondering what your up to.";
|
||
$errors = $phpgw->msg->send("email", $to, $subject, $body);
|
||
|
||
|
||
</pre>
|
||
|
||
<p>
|
||
<h2><a name="tth_sEc6">
|
||
6</a> Configuration Variables</h2>
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc6.1">
|
||
6.1</a> Introduction</h3>
|
||
|
||
<p>
|
||
phpGroupWare attempt to provide developers with as much information
|
||
about the user, group, server, and application configuration as possible.
|
||
|
||
<p>
|
||
To do this we provide a multi-dimensional array called '$phpgw_info[]',
|
||
which includes all the information about your environment.
|
||
|
||
<p>
|
||
Due to the multi-dimensional array approach. getting these values
|
||
is easy.
|
||
|
||
<p>
|
||
Here are some examples:
|
||
<pre>
|
||
|
||
<?php
|
||
// To do a hello username
|
||
echo "Hello " . $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: " . $phpgw_info["server"]["imap_server"];
|
||
//If imap is running on localhost, prints: 'IMAP Server is named: localhost'
|
||
?>
|
||
|
||
|
||
|
||
</pre>
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc6.2">
|
||
6.2</a> User information</h3>
|
||
|
||
<p>
|
||
<tt><font size="-1">$phpgw_info[``user''][``userid'']
|
||
= The user ID. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``sessionid'']
|
||
= The session ID </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``theme'']
|
||
= Selected theme </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``private_dir'']
|
||
= Users private dir. Use phpGroupWare core functions for access to
|
||
the files. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``firstname'']
|
||
= Users first name </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``lastname'']
|
||
= Users last name </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``fullname'']
|
||
= Users Full Name </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``groups'']
|
||
= Groups the user is a member of </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``app_perms'']
|
||
= If the user has access to the current application </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``lastlogin'']
|
||
= Last time the user logged in. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``lastloginfrom'']
|
||
= Where they logged in from the last time. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``lastpasswd_change'']
|
||
= Last time they changed their password. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``passwd'']
|
||
= Hashed password. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``status'']
|
||
= If the user is enabled. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``logintime'']
|
||
= Time they logged into their current session. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``session_dla'']
|
||
= Last time they did anything in their current session </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``user''][``session_ip'']
|
||
= Current IP address</font></tt><font size="-1">
|
||
<p>
|
||
</font> <h3><a name="tth_sEc6.3">
|
||
6.3</a> Group information</h3>
|
||
|
||
<p>
|
||
<tt><font size="-1">$phpgw_info[``group''][``group_names'']
|
||
= List of groups.</font></tt><font size="-1">
|
||
<p>
|
||
</font> <h3><a name="tth_sEc6.4">
|
||
6.4</a> Server information</h3>
|
||
|
||
<p>
|
||
<tt><font size="-1">$phpgw_info[``server''][``server_root'']
|
||
= Main installation directory </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``include_root'']
|
||
= Location of the 'inc' directory. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``temp_dir'']
|
||
= Directory that can be used for temporarily storing files </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``files_dir'']
|
||
= Directory er and group files are stored </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``common_include_dir'']
|
||
= Location of the core/shared include files. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``template_dir'']
|
||
= Active template files directory. This is defaulted by the server,
|
||
and changeable by the user. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``dir_separator'']
|
||
= Allows compatibility with WindowsNT directory format, </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``encrpytkey'']
|
||
= Key used for encryption functions </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``site_title'']
|
||
= Site Title will show in the title bar of each webpage. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``webserver_url'']
|
||
= URL to phpGroupWare installation. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``hostname'']
|
||
= Name of the server phpGroupWare is installed upon. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``charset'']
|
||
= default charset, default:iso-8859-1 </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``version'']
|
||
= phpGroupWare version.</font></tt><font size="-1">
|
||
<p>
|
||
</font> <h3><a name="tth_sEc6.5">
|
||
6.5</a> Database information</h3>
|
||
|
||
<p>
|
||
It is unlikely you will need these, because $phpgw_info_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. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``db_name'']
|
||
= Database name. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``db_user'']
|
||
= User name. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``db_pass'']
|
||
= Password </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``db_type'']
|
||
= Type of database. Currently MySQL and PostgreSQL are supported.</font></tt><font size="-1">
|
||
<p>
|
||
</font> <h3><a name="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>
|
||
<tt><font size="-1">$phpgw_info[``server''][``mail_server'']
|
||
= Address of the IMAP server. Usually this is set to localhost. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``mail_server_type'']
|
||
= IMAP or POP3 </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``imap_server_type'']
|
||
= Cyrus or Uwash </font></tt><font size="-1">
|
||
<p>
|
||
</font><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><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``mail_suffix]
|
||
= This is the domain name, used to add to email address </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``mail_login_type'']
|
||
= This adds support for VMailMgr. Generally this should be set to
|
||
'standard'. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``smtp_server'']
|
||
= Address of the SMTP server. Usually this is set to localhost. </font></tt><font size="-1">
|
||
<p>
|
||
</font><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><font size="-1">
|
||
<p>
|
||
</font> <h3><a name="tth_sEc6.7">
|
||
6.7</a> NNTP information</h3>
|
||
|
||
<p>
|
||
<tt><font size="-1">$phpgw_info[``server''][``nntp_server'']
|
||
= Address of the NNTP server. </font></tt><font size="-1">
|
||
<p>
|
||
</font><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><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``nntp_sender'']
|
||
= Unknown </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``nntp_organization'']
|
||
= Unknown </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``nntp_admin'']
|
||
= Unknown</font></tt><font size="-1">
|
||
<p>
|
||
</font> <h3><a name="tth_sEc6.8">
|
||
6.8</a> Application information</h3>
|
||
|
||
<p>
|
||
Each application has the following information available.
|
||
|
||
<p>
|
||
<tt><font size="-1">$phpgw_info[``apps''][``appname''][``title'']
|
||
= The title of the application. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``apps''][``appname''][``enabled'']
|
||
= If the application is enabled. True or False. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``app_include_dir'']
|
||
= Location of the current application include files. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``app_template_dir'']
|
||
= Location of the current application tpl files. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``app_lang_dir'']
|
||
= Location of the current lang directory. </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``app_auth'']
|
||
= If the server and current user have access to current application </font></tt><font size="-1">
|
||
<p>
|
||
</font><tt><font size="-1">$phpgw_info[``server''][``app_current'']
|
||
= name of the current application.</font></tt><font size="-1">
|
||
<p>
|
||
</font> <h2><a name="tth_sEc7">
|
||
7</a> Using Language Support</h2>
|
||
|
||
<p>
|
||
<h3><a name="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">
|
||
7.2</a> How to use lang support</h3>
|
||
|
||
<p>
|
||
The lang() function is your application's interface to phpGroupWare's
|
||
internationalization support.
|
||
|
||
<p>
|
||
While developing your application, just wrap all your text output
|
||
with calls to lang(), as in the following code:
|
||
<pre>
|
||
|
||
$x = 42;
|
||
echo lang("The counter is %1",$x)."<br>";
|
||
|
||
|
||
</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>
|
||
Without a specific translation in the lang table, the above code will
|
||
print:
|
||
<pre>
|
||
|
||
The counter is 42*<br>
|
||
|
||
|
||
</pre> If the current user speaks Italian, they string returned
|
||
may instead be:
|
||
<pre>
|
||
|
||
il contatore <20> 42<br>
|
||
|
||
|
||
</pre>
|
||
|
||
<p>
|
||
|
||
<h4>The lang function</h4>
|
||
|
||
<p>
|
||
|
||
<pre>
|
||
|
||
lang($key, $m1="", $m2="", $m3="", $m4="", $m5="",
|
||
$m6="", $m7="", $m8="", $m9="", $m10="")
|
||
|
||
|
||
</pre>
|
||
|
||
<p>
|
||
|
||
<dl compact="compact">
|
||
<dd> [$key ]
|
||
|
||
<p>
|
||
is the string to translate and may contain replacement directives
|
||
of the form %n.<br /></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).</dd>
|
||
|
||
<dd> [$m2 - $m10 ]
|
||
|
||
<p>
|
||
the 2nd through 10th replacement values if $m1 is not an array.</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).
|
||
|
||
<p>
|
||
|
||
<h4>Adding translation data</h4>
|
||
|
||
<p>
|
||
An application called <b>Transy</b> is being developed to make this
|
||
easier, until then you can create the translation data manually.
|
||
|
||
<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.</dd>
|
||
|
||
<dd> [app_name ]
|
||
|
||
<p>
|
||
The application the translation applies to, or common if it is common
|
||
across multiple applications.</dd>
|
||
|
||
<dd> [lang ]
|
||
|
||
<p>
|
||
The code for the language the translation is in.</dd>
|
||
|
||
<dd> [content ]
|
||
|
||
<p>
|
||
The translated string.</dd>
|
||
</dl>
|
||
|
||
<p>
|
||
|
||
<h4>lang.sql</h4>
|
||
|
||
<p>
|
||
Currently all applications, and the core phpGroupWare source tree
|
||
have a lang.sql file. This is the place to add translation data. Just
|
||
add lines of the form:
|
||
<pre>
|
||
|
||
REPLACE INTO lang (message_id, app_name, lang, content)
|
||
VALUES( 'account has been deleted','common','en','Account has been deleted');
|
||
|
||
|
||
</pre>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">
|
||
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>
|
||
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>
|
||
For example, calling
|
||
<pre>
|
||
|
||
echo check_code(13);
|
||
|
||
|
||
</pre>Would print
|
||
<pre>
|
||
|
||
Your message has been sent
|
||
|
||
|
||
</pre> translated into the current language.
|
||
|
||
<p>
|
||
<h2><a name="tth_sEc8">
|
||
8</a> Using Templates</h2>
|
||
|
||
<p>
|
||
<h3><a name="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>
|
||
<h3><a name="tth_sEc8.2">
|
||
8.2</a> How to use templates</h3>
|
||
|
||
<p>
|
||
Some instructions on using templates:
|
||
|
||
<p>
|
||
For Further info read the PHPLIBs documentation for their template
|
||
class. <a href="http://phplib.netuse.de"><tt>http://phplib.netuse.de</tt></a>
|
||
|
||
<p>
|
||
<h2><a name="tth_sEc9">
|
||
9</a> About this document</h2>
|
||
|
||
<p>
|
||
<h3><a name="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://www.phpgroupware.org"><tt>http://www.phpgroupware.org</tt></a>
|
||
as lyx source, HTML, and text.
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc9.2">
|
||
9.2</a> Comments </h3>
|
||
|
||
<p>
|
||
Comments on this HOWTO should be directed to the phpGroupWare developers
|
||
mailing list phpgroupware-developers@lists.sourceforge.net
|
||
|
||
<p>
|
||
To subscribe, go to <a href="http://sourceforge.net/mail/?group"><tt>http://sourceforge.net/mail/?group</tt></a>_id=7305
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc9.3">
|
||
9.3</a> History </h3>
|
||
|
||
<p>
|
||
This document was written by Dan Kuykendall.
|
||
|
||
<p>
|
||
2000-09-25 documentation on lang(), codes, administration and preferences
|
||
extension added by Steve Brown.
|
||
|
||
<p>
|
||
2001-01-08 fixed directory structure, minor layout changes, imported
|
||
to lyx source - Darryl VanDorp
|
||
|
||
<p>
|
||
<h3><a name="tth_sEc9.4">
|
||
9.4</a> Copyrights and Trademarks </h3>
|
||
|
||
<p>
|
||
Copyright (c) Dan Kuykendall. 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>
|
||
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> 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.
|
||
|
||
<br /><br /><hr /><small>File translated from
|
||
T<sub><font size="-1">E</font></sub>X
|
||
by <a href="http://hutchinson.belmont.ma.us/tth/">
|
||
T<sub><font size="-1">T</font></sub>H</a>,
|
||
version 2.86.<br />On 9 Jan 2001, 21:41.</small>
|
||
</html>
|