Code Corner 1 Getting Started - Nilpferdschaf/Egroupware-Doku GitHub Wiki

Writing Apps for EGroupware: Getting started

About EGroupware

EGroupware is an online open source group collaboration tool whose features include email, calendar appointments, project tracking systems and many more. But all that does not matter if you require a specific feature unique to your organisation. In this case Egroupware provides programming interfaces that make it easy to write your own custom plugins.

In this section of the tutorial you will build a minimal application, the classic Hello world. The hardest part will be to get Egroupware to recognize your application. To follow this tutorial, EGroupware should already be installed. If it is not, take a look at the EGroupware Github page and come back once you are done.

Writing the application

To start off, you need to add some files to the EGroupware installation directory. EGroupware will look for these files and if it finds them, make the application available for installation.

The application structure looks like this:

$egw_installation/
|---helloworld/  
|   |---index.php
|
|---inc/  
|
|---setup/
|   |---setup.inc.php
|
|---templates/
|   |---default/
|   |   |---images/

Everything you do from now on will happen within the folder helloworld/. This will also be the name of your application. Within this folder is index.php. EGroupware returns this file every time the application is accessed and it will therefore mark the entry point to all other code your write. If you know Java or C, you can think of this file as the main() function. It should set everything up, but ultimately call some other code. That is what inc/ is for: It contains the entire rest of the codebase.

The setup/ folder contains everything EGW needs to know to install the application. For now, the only content will be setup.inc.php.

Next up, templates/ will contain UI templates and images used within the application. We will not use this until later, so it is empty for now except for some basic structure.

You will now fill index.php with the Hello World code. As there is so little to it, there is no need to use inc/ yet. This will change in the future, of course.

index.php:

<html>
    <head>
        <title>Hello World</title>
    </head>
    <body>
        <h1>Hello World!</h1>
    </body>
</html>

Now head over to your EGroupware installation at http://$your_domain/egroupware. You will notice the app is not there yet. Before you can access it, it needs to be registered and installed within EGW and made available to your account. For the first step, you just need to edit setup.inc.php to contain some basic meta-information:

setup.inc.php:

<?php
$setup_info ['helloworld'] = array(
    'name'              => 'helloworld',
    'title'             => 'Hello World',
    'version'           => '0.001',
    'description'       => 'Hello World in EGroupware',
    'author'            => 'Your name',
    'maintainer'        => 'Your organisations name',
    'maintainer_email'  => 'Your organisations email',
    'app_order'         => 100,
    'enable'            => 1,
    'autoinstall'       => true,
    'license'           => 'Your License'
);

$setup_info ['helloworld'] ['depends'] = array(
    array(
        'appname'       => 'phpgwapi',
        'versions'      => array(
            '14.1'
        )
    ),
    array(
        'appname'       => 'etemplate',
        'versions'      => Array(
            '14.1'
        )
    )
);

Registering, Installation and Access Control

To install the application, you should now go to http://$your_domain/egroupware/setup, log in and click on Manage Applications. You should be able to find the name of the app within the list that is displayed to you. Once you have, tick the installation checkmark next to it and then press Save at the bottom of the page. If everything goes alright, the app is now installed.

The EGroupware setup page Installing an App

There is one more step, which is giving you the rights to actually launch the application. To do so, go back to http://$your_domain/egroupware/ and log in again, this time using an account with admin rights. Select the admin-tab on the left, right click on your account, choose Access Control, click on Add, tick Hello World, press OK and then Close.
Refresh the page and you should see helloworld in the sidebar. Click on it.

Choose Access Control on the admin page Give yourself access to the app The Hello World app