Code Corner 8 Other Helpful Tools - Nilpferdschaf/Egroupware-Doku GitHub Wiki

<< Prev.: Javascript

Other Helpful Tools

Eclipse

If you want to code your app inside a fully-fledged IDE on a client computer instead of directly on the server, you should take a look at Eclipse. It is free and open source and supports many useful plugins. There is even a version specifically designed for web development called Eclipse-PHP. The download together with installation instructions can be found here.

Connecting to a Server

To connect to your server, open Eclipse and choose Window > Perspective > Open Perspective > Remote System Explorer. Now right click into the left sidebar and choose New > Connection.... Choose the kind of connection you want, enter your server details and connect. Your server should now show up in the sidebar.

Creating a Remote Project

Your server is now visible in the sidebar, but Eclipse shows you the entire file system, starting at /. If you want to work on multiple projects at once, where each has its own directory, the current setup is unnecessarily messy. To single out a specific directory, navigate to it in the folder tree, then right click to select Create Remote Project.

Now switch to the PHP tab at the top of the window. You should see the newly created project in the sidebar, where you can start opening and editing files.

XDebug

XDebug allows you to set breakpoints and step through each line of php code that you have written, while the program is running on your server. You can even see the values of each variable and a stack trace, so you always know exactly what is going on. This is a tremendous help when trying to find bugs in large projects. It already comes preinstalled with Eclipse-PHP, but some additional setup is required. If you want to use this tool, follow the instructions described here.

File Downloads

Sometimes your users might want to export data from your app so they can use it in external programs. If you want to enable this, you will need the following lines of code

class.helloworld_bo.inc.php

function download_csv (
		$file_name, 
		$file_content, 
		$mime='',
		$length=0,
		$nocache=True,
		$forceDownload=true
	)
{
	html::content_header (
		$file_name, 
		$mime, 
		$length, 
		$nocache, 
		$forceDownload
	);

	echo $file_content;

	common::egw_exit ();
}

This works mostly like downloading files works usually, except now there are special EGW API functions that make sure your download does not interfere with everything else EGW is doing in the background. html::content_header() automatically generates download headers and common::egw_exit() stops the execution of the program.

Translation Tools

The translation tools can be used if you want to support multiple languages in your app. You can add them like any other plugin via the access control dialog in the admin app. Once you are done, it will show up in the sidebar.

Before you start using the translation tools, you should first create a subdirectory helloworld/lang/ and give your server writing rights to it. To do this, navigate to the helloworld/ directory and execute the following commands:

command:

mkdir lang
chown www-data lang

The first thing you will see when you click on it is a long list of all the installed apps. You want to add translations for helloworld, so click on the edit button after it.

Now you need to specify the source and target language. Your app is written in English and in this case, the translation will be German. Click on Load once you are done.

You can now start adding new phrases. To do so, click on Add new Phrases.

Enter some translations for phrases in you UI.

Up until now, all the translations that you entered will only be applied to your app. You can choose the scope of your translations in the select box at the top of the screen. If you select helloworld, the translations will only work within your app. common is the most broad scope. These translations will be applied everywhere and should therefore be used sparsely, because they might interfere with translations from other apps. You need to use this scope to translate the actual name of your app.

If you are done translating, click the Add button to go back to the main view.

EGroupware presents to you a list of all the translations and you are able to make some last minute changes, before you commit them. Do not forget to click Save. Once you are happy with everything, click on the Write button under Step #3.

There is one more thing you should do, which is writing an English to English translation. This is helpful, because it allows you to change the text inside your app, without editing the code. Start by selecting English as your target language, click Load, enter the translations for everything and click on Write once you are happy with them.

To see the results of your work, you just need to go to the preferences and change the language of EGroupware.

You might also want to take a look at the lang directory again. EGroupware has generated two files in this directory: egw_en.lang and egw_de.lang.

How everything works together

The last thing you need to know is a bit of trivia on how to navigate EGroupwares codebase and how the program sets up its functionality. This is partly because there are still a lot of functions which were not presented in this tutorial and which are not centrally documented anywhere else, and partly because it can be quite helpful see sample code of the things you want to implement yourself.

API functions

All API functions that EGroupware provides are somewhere within the phpgwapi and api directories. Though you should be aware that phpgwapi is slowly being deprecated and will be phased out over time. The most notable files are phpgwapi/inc/class.egw_framework.inc.php and phpgwapi/inc/class.html.inc.php. These provide all the static functions that enable you to display messages or enable file downloads. Basically all HTML-related features you can not use with eTemplate.

eTemplate

Speaking of which, everything related to eTemplate is inside the api/src/etemplate/ and api/js/etemplate/ folder. Most of the functionality is implemented in Javascript, so you should look inside api/js/etemplate/ first.

Calendar, Mail and Admin

These programs do not provide an API, but they are fairly large and well documented plugins. Whenever you are not sure how to do a certain task, you should look here first, because the chance to find a working implementation of the thing you need somewhere in their codebases is quite high.

Global variables

Finally, there are some global variables and objects you should know of that can provide helpful services to you. You can view all of these and their contents if you have already set up XDebug.

$GLOBALS['egw'] is one that you have already used in the database section to access the global database connection object, $GLOBALS['egw']->db. Most API related objects are accessible somewhere through $GLOBALS['egw']. If you want to change some account settings of a user, you will need $GLOBALS['egw']->accounts or if you want to provide your own hooks, that other plugins can use, take a look at $GLOBALS['egw']->hooks and the corresponding implementation phpgwapi/inc/class.hooks.inc.php.

The other global variable you should know is $GLOBALS['egw_info']. This is the main object you want to use if you need any meta information about EGroupware or the user of your app. $GLOBALS['egw_info']['server'] contains all kinds of information about the instance of EGroupware that is running in the background, $GLOBALS['egw_info']['apps'] has all the information you need about the apps that are installed and $GLOBALS['egw_info']['user'] is full of user related data, like their name, when they last logged in, or their email address.

Conclusion

This concludes the tutorial. If you have played around with everything that was shown, you will now have extensive knowledge about the workings of EGroupware. You should be able to set up your own applications, design their user interface, make it pretty and connect to a database to populate it. You are able to customize the behaviour of the app to your needs using JavaScript and if you do not know how to implement a specific feature, you can just go through the codebase and find the thing you need. Some of the most sophisticated tools in web development aid you in this task.

Congratulations, you can now rightly call yourself an EGroupware developer.

Back to Index >>

^ Back to top