#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 eGroupWare Application Development \layout Author Dan Kuykendall \layout Date v0.9 29 September 2000 \layout Quote \emph on This document explains eGroupWare'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 eGroupWare is a web based groupware application framework (API), for writing applications. Integrated applications such as email, calendar, todo list, address book, and file manager are included. eGroupWare is a fork of phpGroupWare, for which the original version of this document was written. \layout Subsection Overview of application writing \layout Standard We have attempted to make writing applications for eGroupWare as painless as possible. We hope any pain and suffering is caused by making your application work, but not dealing with eGroupWare itself. \layout Subsection What does the eGroupWare API provide? \layout Standard The eGroupWare API handles session management, user/group management, has support for multiple databases, using either PHPLIB or ADODB database abstracti on methods, 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, eGroupWare provides several functions to give you the information you need about the users environment, and to properly plug into eGroupWare. \layout Section Guidelines \layout Subsection Requirements \layout Standard These guidelines must be followed for any application that wants considered for inclusion into eGroupWare: \layout Itemize It must run on PHP4 and PHP5. \layout Itemize SQL statements must be compatible with both MySQL and PostgreSQL. When in doubt it is best to stick with SQL92. \layout Itemize It must use our default header.inc.php include. \layout Itemize It must use our $GLOBALS['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 made available to users however you 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 \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 eGroupWare 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 eGroupWare. \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 $GLOBALS['phpgw']->common->hea der 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 $GLOBALS['phpgw']->common->foo ter 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 eGroupWare aware of your application \layout Standard Please see the documentation in the setup/doc directory for information on integrating into eGroupWare. This is very important since the steps for database table setup and modificatio n discussed there must be followed. \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 link('myAdminPage.php') . '">'; \newline echo lang('Change myApp settings') . ''; \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 $GLOBALS['phpgw'] and $GLOBALS['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 eGroupWare 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 ~ |--tables_baseline.inc.php \layout Standard \family typewriter |\SpecialChar ~ \SpecialChar ~ |\SpecialChar ~ \SpecialChar ~ |--tables_current.inc.php \layout Standard \family typewriter |\SpecialChar ~ \SpecialChar ~ |\SpecialChar ~ \SpecialChar ~ |--tables_update.inc.php \layout Standard \family typewriter |\SpecialChar ~ \SpecialChar ~ |\SpecialChar ~ \SpecialChar ~ |--setup.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.png \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 (egroupware's optional daemons) \layout Standard \family typewriter \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ |--doc (developer docs) \layout Standard \family typewriter \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ |--inc \layout Standard \family typewriter \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ |\SpecialChar ~ \SpecialChar ~ |--class.phpgw.inc.php \layout Standard \family typewriter \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ |\SpecialChar ~ \SpecialChar ~ |--class.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 ~ |--tables_baseline.inc.php \layout Standard \family typewriter \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ |\SpecialChar ~ \SpecialChar ~ |--tables_current.inc.php \layout Standard \family typewriter \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ |\SpecialChar ~ \SpecialChar ~ |--tables_update.inc.php \layout Standard \family typewriter \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ |\SpecialChar ~ \SpecialChar ~ |--setup.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 The application, developer_tools, provides developers/translators a nice GUI for building and updating translations. \layout Section The API \layout Subsection Introduction \layout Standard eGroupWare attempts to provide developers with a useful API to handle common tasks. \layout Standard To do this we have created a multi-dimensional class $GLOBALS['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: $GLOBALS['phpgw']->send->msg() is in the inc/phpgwapi/phpgw_send.inc.php file. \layout Subsection Basic functions \layout Subsubsection* $GLOBALS['phpgw']->link \layout Standard $GLOBALS['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
\newline /* If session management is done via passing url parameters */ \newline /* The the result would be */ \newline /* */ \newline \newline \backslash end{verbatim} \layout Subsection Application Functions \layout Subsubsection* $GLOBALS['phpgw']->common->phpgw_header(); \layout Standard $GLOBALS['phpgw']->phpgw_header() \newline Print out the start of the HTML page, including the navigation bar and includes appname/inc/header.php \layout Subsubsection* $GLOBALS['phpgw']->common->phpgw_footer(); \layout Standard $GLOBALS['phpgw']->phpgw_footer() \newline Prints the system footer, and includes appname/inc/footer.php \layout Subsubsection* $GLOBALS['phpgw']->common->appsession(); \layout Standard $GLOBALS['phpgw']->common->appsession($data) \newline Store important information session information that your application needs. \newline $GLOBALS['phpgw']->appsession will return the value of your session data is you leave the parameter empty [i.e. $GLOBALS['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 $GLOBALS['phpgw']->common->appsession('/path/to/something'); \newline echo "Dir: " . $GLOBALS['phpgw']->common->appsession(); \newline \newline \backslash end{verbatim} \layout Subsection File functions \layout Subsubsection* Please also see the phpgwapi/doc/vfs directory for additional VFS class documentation \layout Subsubsection* $GLOBALS['phpgw']->vfs->read_file \layout Standard $GLOBALS['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 = $GLOBALS['phpgw']->vfs->read_file('/some/dir/to/file.txt'); \newline \newline \backslash end{verbatim} \layout Subsubsection* $GLOBALS['phpgw']->vfs->write_file \layout Standard $GLOBALS['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 = $GLOBALS['phpgw']->vfs->write_file("/some/dir/to/file.txt"); \newline \newline \backslash end{verbatim} \layout Subsubsection* $GLOBALS['phpgw']->vfs->read_userfile \layout Standard $GLOBALS['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 = $GLOBALS['phpgw']->vfs->read_userfile("file.txt"); \newline \newline \backslash end{verbatim} \layout Subsubsection* $GLOBALS['phpgw']->vfs->write_userfile \layout Standard $GLOBALS['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 = $GLOBALS['phpgw']->vfs->write_userfile("file.txt"); \newline \newline \backslash end{verbatim} \layout Subsubsection* $GLOBALS['phpgw']->vfs->list_userfiles \layout Standard $GLOBALS['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 = $GLOBALS['phpgw']->vfs->list_userfiles(); \newline \newline \backslash end{verbatim} \layout Subsection Email/NNTP Functions \layout Subsubsection* $GLOBALS['phpgw']->send->msg \layout Standard $GLOBALS['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 = $GLOBALS['phpgw']->send->msg("email", $to, $subject, $body); \newline \newline \backslash end{verbatim} \layout Section Configuration Variables \layout Subsection Introduction \layout Standard eGroupWare attempts 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 '$GLOBALS['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 \newline \newline \newline \newline \backslash end{verbatim} \layout Subsection User information \layout Standard \family typewriter \size small $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 eGroupWare core functions for access to the files. \layout Standard \family typewriter \size small $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 eGroupWare installation. \layout Standard \family typewriter \size small $GLOBALS['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 eGroupWare is installed upon. \layout Standard \family typewriter \size small $GLOBALS['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 $GLOBALS['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 ] = eGroupWare version. \layout Subsection Database information \layout Standard It is unlikely you will need these, because $GLOBALS['phpgw_info']_db will already be loaded as a database for you to use. \layout Standard \family typewriter \size small $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 eGroupWare functions. \layout Standard \family typewriter \size small $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 $GLOBALS['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 eGroupWare is built using a multi-language support scheme. This means the pages can be translated to other languages very easily. Translations of text strings are stored in the phpGroupWare database, and can be modified by the eGroupWare administrator. \layout Standard Please see the setup/doc directory for a document which contains more complete documentation of the language system. \layout Subsection How to use lang support \layout Standard The lang() function is your application's interface to eGroupWare's internationa lization 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)."
"; \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*
\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
\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 Subsection Common return codes \layout Standard If you browse through the eGroupWare sources, you may notice a pattern to the return codes used in the higher-level functions. The codes used are partially documented in the doc/developers/CODES file. \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 eGroupWare is built using a templates-based design. This means the display pages, stored in tpl files, can be translated to other languages, made to look completely different. \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.egroupware.org} \latex default as lyx source, HTML, and text. \layout Subsection Comments \layout Standard Comments on this HOWTO should be directed to the eGroupWare developers mailing list egroupware-developers@lists.sourceforge.net \layout Standard To subscribe, go to \latex latex \backslash url{http://lists.sourceforge.net/lists/egroupware-developers} \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 Standard 2003-12-29 adapted for eGroupWare and updated for setup and use of GLOBALS - Miles Lott \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 eGroupWare and phpGroupWare such a success. \the_end