extern/egroupware
1
0
Fork 1
mirror of https://github.com/EGroupware/egroupware.git synced 2024-10-06 18:22:49 +02:00
Code Issues Packages Projects Releases Wiki Activity
c8cc472302
egroupware/phpgwapi/doc/index.lyx
seek3r 2c011ba41c new docs in newer format
2001-01-10 09:59:20 +00:00

3081 lines
47 KiB
Plaintext
Raw Blame History

#LyX 1.1 created this file. For more info see http://www.lyx.org/
\lyxformat 2.17
\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 {}
\layout LyX-Code
\bibitem {}
\layout LyX-Code
\bibitem {}
\layout LyX-Code
\bibitem {}
\layout LyX-Code
\bibitem {}
\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 {}
\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->msg->send($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->msg->send("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 <20> 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
Reference in New Issue View Git Blame Copy Permalink