phpgwapi/doc/index.lyx

#LyX 1.1 created this file. For more info see http://www.lyx.org/
\lyxformat 218
\textclass article
\begin_preamble

\usepackage{fullpage, graphicx, url}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0ex}
\title{ phpGroupWare Application Development}
\end_preamble
\language english
\inputencoding default
\fontscheme default
\graphics default
\paperfontsize 10
\spacing single
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip smallskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title

phpGroupWare Application Development
\layout Author

Dan Kuykendall <dan@kuykendall.org>
\layout Date

v0.9 29 September 2000
\layout Quote


\emph on
This document explains phpGroupWare's infrastructure and API, along with
 what is required to integrate applications into it.
\layout Standard


\begin_inset LatexCommand \tableofcontents{}

\end_inset


\layout Section

Introduction
\layout Standard

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.

\layout Subsection

Overview of application writing
\layout Standard

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.

\layout Subsection

What does the phpGroupWare API provide?
\layout Standard

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.

\layout Standard

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.

\layout Section

Guidelines
\layout Subsection

Requirements
\layout Standard

These guidelines must be followed for any application that wants considered
 for inclusion into phpGroupWare deluxe:
\layout Itemize

It must run on PHP3 and PHP4.

\layout Itemize

SQL statements must be compatible with both MySQL and PostgreSQL.

\layout Itemize

It must use our default header.inc.php include.

\layout Itemize

It must use our $phpgw_link($url) for all links (this is for session support).

\layout Itemize

It must use
\begin_inset Quotes eld
\end_inset

post
\begin_inset Quotes erd
\end_inset

 for forms.

\layout Itemize

It must respect phpGW group rights and phpGW user permissions.

\layout Itemize

It must use our directory structure, template support and lang (multi-language)
 support.

\layout Itemize

Where possible it should run on both Unix and NT platforms.
\layout Itemize

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.

\layout Subsection

Writing/porting your application
\layout Subsubsection*

Include files
\layout Standard

Each PHP page you write will need to include the header.inc.php along with
 a few variables.
\newline
 This is done by putting this at the top of each PHP page.

\latex latex

\backslash
begin{verbatim}
\newline

\newline
  <?php
\newline
  $phpgw_info["flags"]["currentapp"] = "appname";
\newline
  include("../header.inc.php");
\newline
  ?>
\newline

\newline

\backslash
end{verbatim}
\latex default
Of course change application name to fit.
\newline
 This include will provide the following things:
\layout Itemize

The phpgwAPI - The phpGroupWare API will be loaded.

\layout Itemize

The phpGW navbar will be loaded (by default, but can be disabled until a
 later point.

\layout Itemize

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.

\layout Itemize

appname/inc/header.inc.php - This file is loaded just after the system header/navb
ar, and allows developers to use it for whatever they need to load.

\layout Itemize

appname/inc/footer.inc.php - This file is loaded just before the system footer,
 allowing developers to close connections and whatever else they need.

\layout Itemize

The phpGW footer will be loaded, which closes several connections.
\layout Section

Installing your application
\layout Subsection

Overview
\layout Standard

It is fairly simple to add and delete applications to/from phpGroupWare.

\layout Subsection

Automatic features
\layout Standard

To make things easy for developers we go ahead and load the following files.

\layout Itemize

appname/inc/functions.inc.php - This file should include all your application
 specific functions.

\layout Itemize

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.

\layout Itemize

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.
\layout Subsection

Adding files, directories and icons.
\layout Standard

You will need to create the following directories for your code
\newline
 (replace 'appname' with your application name)
\newline

\layout Standard
\noindent

\family typewriter
`--appname
\layout Standard
\noindent

\family typewriter
\SpecialChar ~
\SpecialChar ~
|--inc
\layout Standard
\noindent

\family typewriter
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |--functions.inc.php
\layout Standard
\noindent

\family typewriter
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
 \SpecialChar ~
|--header.inc.php
\layout Standard
\noindent

\family typewriter
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
 \SpecialChar ~
|--hook_preferences.inc.php
\layout Standard
\noindent

\family typewriter
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
 \SpecialChar ~
|--hook_admin.inc.php
\layout Standard
\noindent

\family typewriter
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
 \SpecialChar ~
`--footer.inc.php
\layout Standard
\noindent

\family typewriter
\SpecialChar ~
\SpecialChar ~
`--templates
\layout Standard
\noindent

\family typewriter
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 `--default
\layout LyX-Code
\noindent \bibitem {dummy}

\layout LyX-Code
\bibitem {dummy}

\layout LyX-Code
\bibitem {dummy}

\layout LyX-Code
\bibitem {dummy}

\layout LyX-Code
\bibitem {dummy}

\layout Subsection

Making phpGroupWare aware of your application
\layout Standard

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.

\latex latex

\backslash
begin{verbatim}
\newline

\newline
  insert into applications (app_name, app_title, app_enabled) values ('appname',
 'The App name', 1);
\newline

\newline

\backslash
end{verbatim}
\layout Subsection

Hooking into Administration page
\layout Standard

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.
\layout Standard

Simple Example:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
<?php
\newline
  $img = "/" .
 $appname .
 "/images/navbar.gif";
\newline
  section_start("My Application",$img);
\newline
  echo "<a HREF=
\backslash
"" .
 $phpgw->link("myAdminPage.php") .
 "
\backslash
">";
\newline
  echo lang("Change myApp settings") .
 "</a>";
\newline
  section_end();
\newline
?>
\newline

\newline

\backslash
end{verbatim}
\latex default
Look at headlines/inc/hook_admin.inc.php and admin/inc/hook_admin.inc.php for
 more examples.
\layout Standard

Things to note:
\layout Itemize

Links are relative to the admin/index.php file, not your application's base
 directory.
 (so use $appname in your link() calls)
\layout Itemize

The file is brought in with include() so be careful to not pollute the name-spac
e too much
\layout Standard

The standard $phpgw and $phpgw_info variables are in-scope, as is $appname
 which corresponds to the application name in the path.
\layout Standard

There are 2 functions to coordinate the display of each application's links,
 section_start() and section_end()
\layout Subsubsection*

section_start
\layout Standard

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.

\layout Subsubsection*

section_end
\layout Standard

section_end() closes the section that was started with section_start().

\layout Subsection

Hooking into Preferences page
\layout Standard

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/hoo
k_preferences.inc.php instead of appname/inc/hook_admin.inc.php.
 The same functions and variables are defined.

\layout Section

Infrastructure
\layout Subsection

Overview
\layout Standard

phpGroupWare attempts to provide developers with a sound directory structure
 to work from.
\newline
 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.

\layout Subsection

Directory tree
\layout Standard


\family typewriter
.--appname
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |--inc
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 |--functions.inc.php
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 |--header.inc.php
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 |--hook_preferences.ini.php
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 |--hook_home.inc.php
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 `--footer.inc.php
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |--manual
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |--setup
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 |--baseline.inc.php
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 |--droptables.inc.php
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 |--newtables.inc.php
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 |--upgradetables.inc.php
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 |--config.inc.php
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 `--register.inc.php
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 `--templates
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 `--default
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
 `--images
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
 `--navbar.gif
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |--preferences.php
\layout Standard


\family typewriter
|--docs (installation docs)
\layout Standard


\family typewriter
|--files
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 |--groups
\layout Standard


\family typewriter
|\SpecialChar ~
\SpecialChar ~
 `--users
\layout Standard


\family typewriter
`--phpgwapi
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|--cron (phpgroupware's optional daemons)
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|--doc (developers docs)
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|--inc
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |--phpgw.inc.php
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |--phpgw_info.inc.php
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |--phpgw_common.inc.php
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 `--etc..
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|--manual
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|--setup
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |--baseline.inc.php
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |--droptables.inc.php
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |--newtables.inc.php
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |--upgradetables.inc.php
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |--config.inc.php
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 `--register.inc.php
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|--templates
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |--default
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 `--images
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 |--home.gif
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 |\SpecialChar ~
\SpecialChar ~
 `--preferences.gif
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
 `--verilak
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
|\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
 `--images
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
 |--home.gif
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
 `--preferences.gif
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
`--themes
\layout Standard


\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
`--default.theme
\layout LyX-Code
\bibitem {dummy}

\layout Subsection

Translations
\layout Standard

The translations are now being done thru the database, and will be configurable
 to use other mechanisms.

\layout Standard

We are completing a program called Transy, which will provide developers/transla
tors a nice GUI for building and updating translations.

\layout Standard

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.

\layout Section

The API
\layout Subsection

Introduction
\layout Standard

phpGroupWare attempts to provide developers with a useful API to handle
 common tasks.

\layout Standard

To do this we have created a multi-dimensional class $phpgw->.

\layout Standard

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.

\layout Standard

Example: $phpgw->send->msg() is in the inc/phpgwapi/phpgw_send.inc.php file.

\layout Subsection

Basic functions
\layout Subsubsection*

$phpgw->link
\layout Standard

$phpgw->link($url)
\newline
 Add support for session management.
 ALL links must use this, that includes href's form actions and header location'
s.

\layout Standard

If you are just doing a form action back to the same page, you can use it
 without any parameters.

\layout Standard

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:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
<form name=copy method=post action="<?php echo $phpgw->link();?>">
\newline
/* If session management is done via passing url parameters */
\newline
/* The the result would be */
\newline
/* <form name=copy method=post action="somepage.php?sessionid=87687693276?kp3=kjh
98u80"> */
\newline

\newline

\backslash
end{verbatim}
\layout Subsection

Application Functions
\layout Subsubsection*

$phpgw->common->phpgw_header
\layout Standard

$phpgw->phpgw_header()
\newline
 Print out the start of the HTML page, including the navigation bar and
 includes appname/inc/header.php
\layout Subsubsection*

$phpgw->common->phpgw_footer
\layout Standard

$phpgw->phpgw_footer()
\newline
 Prints the system footer, and includes appname/inc/footer.php
\layout Subsubsection*

$phpgw->common->appsession
\layout Standard

$phpgw->common->appsession($data)
\newline
 Store important information session information that your application needs.
\newline
 $phpgw->appsession will return the value of your session data is you leave
 the parameter empty [i.e.
 $phpgw->appsession(
\begin_inset Quotes eld
\end_inset


\begin_inset Quotes erd
\end_inset

)], otherwise it will store whatever data you send to it.
\newline
 You can also store a comma delimited string and use explode() to turn it
 back into an array when you receive the value back.

\layout Standard

Example:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
  $phpgw->common->appsession("/path/to/something");
\newline
  echo "Dir: " .
 $phpgw->common->appsession();
\newline

\newline

\backslash
end{verbatim}
\layout Subsection

File functions
\layout Subsubsection*

$phpgw->vfs->read_file
\layout Standard

$phpgw->vfs->read_file($file)
\newline
 Returns the data from $file.
\newline
 You must send the complete path to the file.
\newline
 Example:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
$data = $phpgw->vfs->read_file("/some/dir/to/file.txt");
\newline

\newline

\backslash
end{verbatim}
\layout Subsubsection*

$phpgw->vfs->write_file
\layout Standard

$phpgw->vfs->write_file($file, $contents)
\newline
 Write data to $file.
\newline
 You must send the complete path to the file.
\newline
 Example:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
$data = $phpgw->vfs->write_file("/some/dir/to/file.txt");
\newline

\newline

\backslash
end{verbatim}
\layout Subsubsection*

$phpgw->vfs->read_userfile
\layout Standard

$phpgw->vfs->read_userfile($file)
\newline
 Returns the data from $file, which resides in the users private dir.
\newline
 Example:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
$data = $phpgw->vfs->read_userfile("file.txt");
\newline

\newline

\backslash
end{verbatim}
\layout Subsubsection*

$phpgw->vfs->write_userfile
\layout Standard

$phpgw->write_userfile($file, $contents)
\newline
 Writes data to $file, which resides in the users private dir.
\newline
 Example:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
$data = $phpgw->vfs->write_userfile("file.txt");
\newline

\newline

\backslash
end{verbatim}
\layout Subsubsection*

$phpgw->vfs->list_userfiles
\layout Standard

$phpgw->vfs->list_userfiles()
\newline
 Returns an array which has the list of files in the users private dir.
\newline
 Example:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
$filelist = array();
\newline
$filelist = $phpgw->vfs->list_userfiles();
\newline

\newline

\backslash
end{verbatim}
\layout Subsection

Email/NNTP Functions
\layout Subsubsection*

$phpgw->send->msg
\layout Standard

$phpgw->send->msg($service, $to, $subject, $body, $msgtype, $cc, $bcc)
\newline
 Send a message via email or NNTP and returns any error codes.
\newline
 Example:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
$to = "someuser@domain.com";
\newline
$subject = "Hello buddy";
\newline
$body = "Give me a call
\backslash
n Been wondering what your up to.";
\newline
$errors = $phpgw->send->msg("email", $to, $subject, $body);
\newline

\newline

\backslash
end{verbatim}
\layout Section

Configuration Variables
\layout Subsection

Introduction
\layout Standard

phpGroupWare attempt to provide developers with as much information about
 the user, group, server, and application configuration as possible.

\layout Standard

To do this we provide a multi-dimensional array called '$phpgw_info[]',
 which includes all the information about your environment.

\layout Standard

Due to the multi-dimensional array approach.
 getting these values is easy.

\layout Standard

Here are some examples:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
  <?php
\newline
  // To do a hello username
\newline
  echo "Hello " .
 $phpgw_info["user"]["fullname"];
\newline
  //If username first name is John and last name is Doe, prints: 'Hello
 John Doe'
\newline
  ?>
\newline
  <?php
\newline
  // To find out the location of the imap server
\newline
  echo "IMAP Server is named: " .
 $phpgw_info["server"]["imap_server"];
\newline
  //If imap is running on localhost, prints: 'IMAP Server is named: localhost'
\newline
  ?>
\newline

\newline

\newline

\backslash
end{verbatim}
\layout Subsection

User information
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

userid
\begin_inset Quotes erd
\end_inset

] = The user ID.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

sessionid
\begin_inset Quotes erd
\end_inset

] = The session ID
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

theme
\begin_inset Quotes erd
\end_inset

] = Selected theme
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

private_dir
\begin_inset Quotes erd
\end_inset

] = Users private dir.
 Use phpGroupWare core functions for access to the files.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

firstname
\begin_inset Quotes erd
\end_inset

] = Users first name
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

lastname
\begin_inset Quotes erd
\end_inset

] = Users last name
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

fullname
\begin_inset Quotes erd
\end_inset

] = Users Full Name
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

groups
\begin_inset Quotes erd
\end_inset

] = Groups the user is a member of
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

app_perms
\begin_inset Quotes erd
\end_inset

] = If the user has access to the current application
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

lastlogin
\begin_inset Quotes erd
\end_inset

] = Last time the user logged in.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

lastloginfrom
\begin_inset Quotes erd
\end_inset

] = Where they logged in from the last time.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

lastpasswd_change
\begin_inset Quotes erd
\end_inset

] = Last time they changed their password.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

passwd
\begin_inset Quotes erd
\end_inset

] = Hashed password.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

status
\begin_inset Quotes erd
\end_inset

] = If the user is enabled.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

logintime
\begin_inset Quotes erd
\end_inset

] = Time they logged into their current session.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

session_dla
\begin_inset Quotes erd
\end_inset

] = Last time they did anything in their current session
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

user
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

session_ip
\begin_inset Quotes erd
\end_inset

] = Current IP address
\layout Subsection

Group information
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

group
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

group_names
\begin_inset Quotes erd
\end_inset

] = List of groups.
\layout Subsection

Server information
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

server_root
\begin_inset Quotes erd
\end_inset

] = Main installation directory
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

include_root
\begin_inset Quotes erd
\end_inset

] = Location of the 'inc' directory.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

temp_dir
\begin_inset Quotes erd
\end_inset

] = Directory that can be used for temporarily storing files
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

files_dir
\begin_inset Quotes erd
\end_inset

] = Directory er and group files are stored
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

common_include_dir
\begin_inset Quotes erd
\end_inset

] = Location of the core/shared include files.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

template_dir
\begin_inset Quotes erd
\end_inset

] = Active template files directory.
 This is defaulted by the server, and changeable by the user.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

dir_separator
\begin_inset Quotes erd
\end_inset

] = Allows compatibility with WindowsNT directory format,
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

encrpytkey
\begin_inset Quotes erd
\end_inset

] = Key used for encryption functions
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

site_title
\begin_inset Quotes erd
\end_inset

] = Site Title will show in the title bar of each webpage.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

webserver_url
\begin_inset Quotes erd
\end_inset

] = URL to phpGroupWare installation.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

hostname
\begin_inset Quotes erd
\end_inset

] = Name of the server phpGroupWare is installed upon.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

charset
\begin_inset Quotes erd
\end_inset

] = default charset, default:iso-8859-1
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

version
\begin_inset Quotes erd
\end_inset

] = phpGroupWare version.
\layout Subsection

Database information
\layout Standard

It is unlikely you will need these, because $phpgw_info_db will already
 be loaded as a database for you to use.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

db_host
\begin_inset Quotes erd
\end_inset

] = Address of the database server.
 Usually this is set to localhost.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

db_name
\begin_inset Quotes erd
\end_inset

] = Database name.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

db_user
\begin_inset Quotes erd
\end_inset

] = User name.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

db_pass
\begin_inset Quotes erd
\end_inset

] = Password
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

db_type
\begin_inset Quotes erd
\end_inset

] = Type of database.
 Currently MySQL and PostgreSQL are supported.
\layout Subsection

Mail information
\layout Standard

It is unlikely you will need these, because most email needs are services
 thru core phpGroupWare functions.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

mail_server
\begin_inset Quotes erd
\end_inset

] = Address of the IMAP server.
 Usually this is set to localhost.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

mail_server_type
\begin_inset Quotes erd
\end_inset

] = IMAP or POP3
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

imap_server_type
\begin_inset Quotes erd
\end_inset

] = Cyrus or Uwash
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

imap_port
\begin_inset Quotes erd
\end_inset

] = This is usually 143, and should only be changed if there is a good reason.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

mail_suffix] = This is the domain name, used to add to email address
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

mail_login_type
\begin_inset Quotes erd
\end_inset

] = This adds support for VMailMgr.
 Generally this should be set to 'standard'.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

smtp_server
\begin_inset Quotes erd
\end_inset

] = Address of the SMTP server.
 Usually this is set to localhost.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

smtp_port
\begin_inset Quotes erd
\end_inset

] = This is usually 25, and should only be changed if there is a good reason
\layout Subsection

NNTP information
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

nntp_server
\begin_inset Quotes erd
\end_inset

] = Address of the NNTP server.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

nntp_port
\begin_inset Quotes erd
\end_inset

] = This is usually XX, and should only be changed if there is a good reason.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

nntp_sender
\begin_inset Quotes erd
\end_inset

] = Unknown
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

nntp_organization
\begin_inset Quotes erd
\end_inset

] = Unknown
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

nntp_admin
\begin_inset Quotes erd
\end_inset

] = Unknown
\layout Subsection

Application information
\layout Standard

Each application has the following information available.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

apps
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

appname
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

title
\begin_inset Quotes erd
\end_inset

] = The title of the application.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

apps
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

appname
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

enabled
\begin_inset Quotes erd
\end_inset

] = If the application is enabled.
 True or False.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

app_include_dir
\begin_inset Quotes erd
\end_inset

] = Location of the current application include files.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

app_template_dir
\begin_inset Quotes erd
\end_inset

] = Location of the current application tpl files.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

app_lang_dir
\begin_inset Quotes erd
\end_inset

] = Location of the current lang directory.

\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

app_auth
\begin_inset Quotes erd
\end_inset

] = If the server and current user have access to current application
\layout Standard


\family typewriter
\size small
$phpgw_info[
\begin_inset Quotes eld
\end_inset

server
\begin_inset Quotes erd
\end_inset

][
\begin_inset Quotes eld
\end_inset

app_current
\begin_inset Quotes erd
\end_inset

] = name of the current application.
\layout Section

Using Language Support
\layout Subsection

Overview
\layout Standard

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.

\layout Subsection

How to use lang support
\layout Standard

The lang() function is your application's interface to phpGroupWare's internatio
nalization support.
\layout Standard

While developing your application, just wrap all your text output with calls
 to lang(), as in the following code:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
  $x = 42;
\newline
  echo lang("The counter is %1",$x)."<br />";
\newline

\newline

\backslash
end{verbatim}
\latex default
This will attempt to translate
\begin_inset Quotes eld
\end_inset

The counter is %1
\begin_inset Quotes erd
\end_inset

, 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,

\series bold
not
\series default
 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.
\layout Standard

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.
\layout Standard

Without a specific translation in the lang table, the above code will print:

\latex latex

\backslash
begin{verbatim}
\newline

\newline
The counter is 42*<br />
\newline

\newline

\backslash
end{verbatim}
\latex default
 If the current user speaks Italian, they string returned may instead be:

\latex latex

\backslash
begin{verbatim}
\newline

\newline
il contatore � 42<br />
\newline

\newline

\backslash
end{verbatim}
\layout Subsubsection*

The lang function
\layout Standard


\latex latex

\backslash
begin{verbatim}
\newline

\newline
lang($key, $m1="", $m2="", $m3="", $m4="", $m5="",
\newline
          $m6="", $m7="", $m8="", $m9="", $m10="")
\newline

\newline

\backslash
end{verbatim}
\layout Description


\series bold
$key
\series default
\SpecialChar ~

\begin_deeper
\layout Standard

is the string to translate and may contain replacement directives of the
 form %n.
\newline

\end_deeper
\layout Description


\series bold
$m1
\series default
\SpecialChar ~

\begin_deeper
\layout Standard

is the first replacement value or may be an array of replacement values
 (in which case $m2 and above are ignored).
\end_deeper
\layout Description


\series bold
$m2\SpecialChar ~
-\SpecialChar ~
$m10
\series default
\SpecialChar ~

\begin_deeper
\layout Standard

the 2nd through 10th replacement values if $m1 is not an array.
\end_deeper
\layout Standard

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).

\layout Subsubsection*

Adding translation data
\layout Standard

An application called
\series bold
Transy
\series default
 is being developed to make this easier, until then you can create the translati
on data manually.

\layout Subsubsection*

The lang table
\layout Standard

The translation class uses the lang table for all translations.
 We are concerned with 4 of the columns to create a translation:
\layout Description


\series bold
message_id
\series default
\SpecialChar ~

\begin_deeper
\layout Standard

The key to identify the message (the $key passed to the lang() function).
 This is written in English.
\end_deeper
\layout Description


\series bold
app_name
\series default
\SpecialChar ~

\begin_deeper
\layout Standard

The application the translation applies to, or common if it is common across
 multiple applications.
\end_deeper
\layout Description


\series bold
lang
\series default
\SpecialChar ~

\begin_deeper
\layout Standard

The code for the language the translation is in.
\end_deeper
\layout Description


\series bold
content
\series default
\SpecialChar ~

\begin_deeper
\layout Standard

The translated string.
\end_deeper
\layout Subsubsection*

lang.sql
\layout Standard

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:
\latex latex

\backslash
begin{verbatim}
\newline

\newline
REPLACE INTO lang (message_id, app_name, lang, content)
\newline
VALUES( 'account has been deleted','common','en','Account has been deleted');
\newline

\newline

\backslash
end{verbatim}
\latex default
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.

\layout Subsection

Common return codes
\layout Standard

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.
\layout Standard

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.
\layout Standard

For example, calling
\latex latex

\backslash
begin{verbatim}
\newline

\newline
echo check_code(13);
\newline

\newline

\backslash
end{verbatim}
\latex default
Would print
\latex latex

\backslash
begin{verbatim}
\newline

\newline
Your message has been sent
\newline

\newline

\backslash
end{verbatim}
\latex default
 translated into the current language.
\layout Section

Using Templates
\layout Subsection

Overview
\layout Standard

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.

\layout Subsection

How to use templates
\layout Standard

Some instructions on using templates:
\layout Standard

For Further info read the PHPLIBs documentation for their template class.

\begin_inset LatexCommand \url{http://phplib.netuse.de}

\end_inset


\layout Section

About this document
\layout Subsection

New versions
\layout Standard

The newest version of this document can be found on our website
\latex latex

\backslash
url{http://www.phpgroupware.org}
\latex default
 as lyx source, HTML, and text.
\layout Subsection

Comments
\layout Standard

Comments on this HOWTO should be directed to the phpGroupWare developers
 mailing list phpgroupware-developers@lists.sourceforge.net
\layout Standard

To subscribe, go to
\latex latex

\backslash
url{http://sourceforge.net/mail/?group}
\latex default
_id=7305
\layout Subsection

History
\layout Standard

This document was written by Dan Kuykendall.
\layout Standard

2000-09-25 documentation on lang(), codes, administration and preferences
 extension added by Steve Brown.

\layout Standard

2001-01-08 fixed directory structure, minor layout changes, imported to
 lyx source - Darryl VanDorp
\layout Subsection

Copyrights and Trademarks
\layout Standard

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.

\layout Standard

A copy of the license is available at
\begin_inset LatexCommand \url{http://www.gnu.org/copyleft/gpl.html}

\end_inset


\layout Subsection

Acknowledgments and Thanks
\layout Standard

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.

\the_end