This is a short tutorial about customizing Simple Groupware to your needs. If you have any further questions, please use the Forum.

Folder structure

Language files are not parsed by Simple Groupware for every page request. Therefore there are two folders containing the sources and the translated sources: "src/" and "bin/". After the installation, only the "bin/" folder will be used by the system, so all changes should be made here.

Database structure

Every dataset contains common fields like created (creation time), created by (originator), lastmodified (modification time), lastmodifiedby (editor), id (unique identifier), dsize (size of the dataset including files). The system tables in detail:

simple_sys_tree: contains the folders in the tree

simple_seq_*: contains the highest ID for a special table, required for creating new (unique) IDs

simple_blank: empty table used by the default module ("schema/blank.xml")

Change the "<simple> Groupware" logo and link in the upper right corner

The logo can be changed by placing a new file at "bin/ext/<new_file>.gif". Then edit "bin/templates/core_css.conf", replace:
logo = images.php?image=logo&color=FFFFFF logo_link = http://www.simple-groupware.de

with:
logo = ext/<new_file>.gif logo_link = http://<your-homepage>

When finished, make sure to clear the output cache.

Change the "<simple> Groupware" logo and link in the login screen

The image can be changed by replacing the file "bin/ext/sgs_logo.gif" with a new one in "bin/templates/login.tpl". The link can be changed in the same line.

Change the background in the login screen

The image can be changed by replacing the file "bin/ext/bg_beach2.jpg" with a new one.

Remove the copyright in the lower right corner and the login screen

This is not allowed.

Change the webpage icon next to the URL in the browser

The icon can be changed by replacing the file "bin/ext/favicon.ico" with a new one. If you need a free icon editor, I reommend IcoFX.

Change the top menu

The top menu is defined in "bin/templates/menu.js". There are some functions to control the menu structure:

Example for a new menu entry:

Changing templates

All templates are written with the Smarty Template Engine and are stored at "bin/templates/*.tpl". The templates will be compiled to PHP and stored at "simple_cache/smarty/". The Smarty manual can be found here.

When finished, make sure to clear the output cache. To let this happen automatically, see the DEBUG parameter below.

Changing themes, styles and formats

Themes are stored at "bin/templates/core_css.conf". Every theme is initiated with "[theme_name]" and contains some variables in "field = value" pairs. The values contain typical CSS colors and font definitions. The first section is not initiated by a "[theme_name]" and contains common variables that belong to all themes. That means that all variables in a theme section override the common variables. By default, every user gets the "core" theme. This can be changed in setup settings.

To create your own theme, it is recommended to expand the "[core]" section. Smaller changes like the "logo" or the "logo_link" can be also made to the common variables in the first section.

Simple Groupware can automatically change the colors of the folder icons in the tree. This is configured by the field "folder" which can be filled with "adapt" to activate this function.

A background image can be also added to the user interface by filling the variable "bg_full" with a filename that is located at "bin/ext/".

Other styles can be set in the cascading style sheet located at "bin/templates/core.css".

Translation / localization

If You want to translate or localize Simple Groupware for Your language, please click here.

Customize modules

All modules in Simple Groupware are defined in their own language called sgsML (Simple Groupware Solutions Markup Language). A tutorial is available here.

Use PHP functions to display content in a view

Beginning with Simple Groupware 0.310, it is possible to load the content of a folder from a PHP function. Normally all content is defined and interpreted in Smarty templates. So it normally looks like this in a module:

This uses the template "asset_display.tpl" in the view "Display". To load the data from a PHP function, just use:

When creating a new module it should look like this:

  <view name="display" displayname="Display" function="get_my_data">
  </view>
  <field name="id" simple_type="id" displayname="{t}Id{/t}">
  </field>

This loads the data from a function named "custom_get_my_data". So you need to create a new PHP file, include it in "<sgs-dir>/bin/core/index.php" and write the function to this file, e.g.:

  $output = "<b>Hello World</b><br/>";
  $output .= "...<br/>";

  /* Smarty can be also used here (templates are in templates/*):
   *
   * $smarty = &$GLOBALS["smarty"];
   * $output .= $smarty->fetch("custom.tpl");
   */

  // use echo $output to avoid output filtering for bad HTML and Javascript
  return $output;

Note: For security reasons, Simple Groupware automatically filters the output for Javascript and dynamic HTML elements. To avoid this, use "echo $output;" instead of "return $output;".

Note: To be able to assign new modules to folders, remember to register the module in "schema/modules.txt".

Debugging

For debugging the code, you can use these functions:

debug_html($var) gives out the contents of a variable and stops the script

debug_html(array($var1,$var2)) gives out the contents of 2 variables and stops the script

debug_queries() gives out all queries that were executed by the request and stops the script

print_r($var) gives out the contents of a variable

print_r(array($var1,$var2)) gives out the contents of 2 variables

debug_file($var) writes the contents of a variable to "<sgs-dir>/simple_cache/debug/debug.txt"

In Smarty templates, you can use:

{$var|@debug_print_r} gives out the contents of a variable

{$var|@debug_file} writes the contents of a variable to "<sgs-dir>/simple_cache/debug/debug.txt"

Make changes persistent over new releases and updates

Beginning with Simple Groupware 0.413, all kinds of changes to the code, new files, images etc. can be made persistent over new releases.

During the update process, all files of the old release are moved to "<sgs-dir>/old", except those contents from the custom folder (<sgs-dir>/custom). Then the new files get extracted. Next, the setup process takes the language file (<sgs-dir>/lang) and the sources (<sgs-dir>/src), and merges both into the bin folder ("<sgs-dir>/bin").

After that, all contents of "<sgs-dir>/custom" are copied to "<sgs-dir>/bin". E.g. if you created "custom/modules/schema/newmodule.xml", it will be copied to "bin/modules/schema/newmodule.xml". Existing files will be overwritten!

Using this customization method helps you to: - keep your changes separated to the standard Simple Groupware code - persist your changes when doing an update

Individual changes to the source code can be made in "<sgs-dir>/custom/customize.php". The following commands can be used to change the Simple Groupware code base:

• Append code:
  customize_replace($file,$code_before,$code_before.$append_code);
• Replace code:
  customize_replace($file,$code_old,$code_new);
• Remove code:
  customize_replace($file,$code_remove,"");

This is a very low-level technique, but it enables you to change PHP files as well as Javascript files, Smarty templates or other files.

Examples:

Create two modules under "<sgs-dir>/custom/modules/schema/new_module.xml" and "<sgs-dir>/custom/modules/schema/news2.xml".

Add the modification commands to "<sgs-dir>/custom/customize.php" (\n = line break):

Tip: Never forget to document your changes!

General

If you change any images or icons, you may need to empty the browser cache to see the new image.
When changing templates, Javascript or CSS files, make sure to clear the output cache and the browser cache.

Note: If the DEBUG mode is enabled in setup settings, the templates will be automatically refreshed and the browser caching for Javascript and CSS files will be disabled.