6.0.0-git
2024-03-19
Last Modified 2013-09-04 by Jan Schneider

Modifying Horde Aspect

This information is valid for Horde 3 only.

Currently being written by: Ciro DurĂ¡n <ciro - at - ldc - dot - usb - dot - ve>


Document status

This document (in the traditional Wikipedia style) is a stub. You can help Horde Wiki by expanding it.

Introduction

This tutorial is intended to give designers a first insight on how to modify the default Horde 3 layout. We are not talking here about creating a new theme for the default layout (you can consult more about that in the Doc/Dev/ThemesH3 page), but to alter completely the layout (frames included). At the current version of Horde, this requires a substantial amount of work, as you need to mess with a good deal of HTML and CSS files.

Motivation

Let's start saying that you don't have any trouble with the default layout. It's well done, has nice bright colors, and is very attractive in general, and it's surprising that despite the ease of use the Horde Framework and Horde Applications have achieved, you have to learn a lot of stuff about the Horde Framework just to start mangling with the .inc files in the /templates directory. And when you want to deliver the power Horde has for, say, a client, you need the layout to be customizable, as they want to establish the graphic style their new portal will have.

In this tutorial we have saved that amount of work for you, and if you want to learn more about the functions the default layout uses, we have provided links to the API in http://dev.horde.org, thus you can consult the links in the References section, in the end of this document.

Prerrequisites

If you are a web designer, you should know a good deal of HTML, Javascript, CSS, and PHP. This tutorial assumes you know all this, thus the HTML, CSS and Javascript conflicts between Mozilla and Internet Explorer. About Horde Framework knowledge, we will assume you don't know its internals, so we will give as well a short insight of the process Horde follows in order to deliver the applications the user needs.

What is Horde?

Horde is an "Application Framework," this is, a set of tools created in order to aid a programmer to easily implement a web application. Thus, with Horde, you can make your application be used by other Horde applications, i.e., you can use the contacts module, Turba, to store contact mails to be used when sending mail using IMP, the webmail application.

The Horde default download only includes the framework. When you install it, you will see the most basic functions only, that is, nothing useful to the user. You need to install other modules in order to give your site more features. As of June 2005, the features you can install from the Horde site are:

  • Webmail - Implemented by IMP. The most popular Horde module.
  • Contacts book - Implemented by Turba. Almost always installed together with IMP, but is capable of working with other modules.
  • News - Implemented by Jonah.
  • Bookmarks storage - See Trean.
  • Web calendar - See Kronolith.
  • Other features you can see in the projects page.

Getting started

(An introduction to this section. This section explains some standard procedures Horde follows to do common tasks)
In this section, we will explain some standard things Horde does, so you can understand the workflow it follows to serve user requests.

What does Horde do when someone enters it?

How does Horde authenticate?

How does Horde keep preferences? What values does it keep?

What are templates? What's the difference with themes?

Templates are the files Horde uses in order to separate the page presentation from the application logic. Each Horde module has its set of templates in order to give structure to the information they generate. The templates are usually in the $MODULE_WEBROOT/templates directory.

Although some templates use a tag delimiter to mark where the generated information should go (as Jonah does), others still use a bit of PHP (like the basic Horde templates) in order to accomplish the same. From my point of view, this complicates the page design for web designers. The Horde authors have expressed their concern about this, and promise in following versions of Horde to simplify the template creation. For now, we have to conform to the current version :-).

The themes are CSS files which mostly change the colors and small details of a template. A theme usually can change the font colors, the border colors, their roundness, the appearance of the input elements, add a background image somewhere. The templates should use the CSS IDs and classes Horde provides in order to use those colors. In the creation of a new template, if you add more classes, you should create and establish the characteristics of those classes in all the themes.

I don't want to change the structure of the templates. I just want to change the colors.

If you want to do this for the login screen, you should locate in the preferences file '$HORDE_WEBROOT/config/prefs.php' this snippet:

// UI theme
$_prefs['theme'] = array(
    'value' => 'bluewhite',
    'locked' => false,
    'shared' => true,
    'type' => 'select',
    'desc' => _("Select your color scheme.")
);

This snippet establishes what theme will be set for a user. The value specified in 'value' tell Horde the default theme to use in the login page, or in the user pages when he has not specified a theme to use. Change it to any title present in the $HORDE_WEBROOT/themes directory. If you want to lock this style for all the users, you should set the 'locked' key to true, and delete all the rows in the horde_prefs table which pref_name is 'theme'.

How does Horde standarize its interface?

Horde provides two common widgets across all the applications: the Sidepanel and the Menu. The sidepanel provides access to the user to all the modules' functionality in a convenient tree-like structure. The menu provides access to the currently used module's features in a list; it also provides some other common features across all the applications (like the "Problem", "Help", and "Log out" icons).

The Sidepanel

The Sidepanel is a tree-like structure where all the active modules and its features are presented for the user. Each module locates itself in the sidepanel using the registry, and puts its features in folders. Some modules create an entire new folder (like Imp), and other modules just add their functions below a folder (like Ingo, which add the Filter function below the Mail folder). This organization is completely customized in the registry.

Customizing the sidepanel organization

In order to change the sidepanel organization, you must change some things in the registry file. In particular, you should watch the 'name' and 'menu_parent' keys in the application hash in the registry. If the 'name' key is present in an application, it must specify a title, the sidepanel will create a folder with the title specified there, and put its functions there. If the 'menu_parent' key is present, it must specify a module present in the applications hash, and the functions this module provides will be put in the folder created by the module specified, provided that this one has a 'name' key.

Let's see an example so you can watch what Horde does. Here's an excerpt from the registry file:

$this->applications['imp'] = array(
    'fileroot' => dirname(__FILE__) . '/../imp',
    'webroot' => $this->applications['horde']['webroot'] . '/imp',
    'name' => _("Mail"),
    'status' => 'active',
    'provides' => 'mail',
);

$this->applications['ingo'] = array(
    'fileroot' => dirname(__FILE__) . '/../ingo',
    'webroot' => $this->applications['horde']['webroot'] . '/ingo',
    'name' => _("Filters"),
    'status' => 'active',
    'provides' => array('mail/blacklistFrom', 'mail/showBlacklist', 'mail/whitelistFrom', 'mail/showWhitelist', 'mail/applyFilters', 'mail/canApplyFilters', 'mail/showFilters'),
    'menu_parent' => 'imp'
);

As you can see, the 'imp' application's functions will be put in the "Mail" folder (the name can change depending on the language the user has established), while the 'ingo' functions will not created a new folder, but rather will put them in the same "Mail" folder. Here's an screenshot of the sidepanel using this configuration.

A picture of the functions put by the registry file. Note that the filters function is provided by Ingo, while the rest of functions are provided by Imp

The Menu

The Menu provides access to the currently used module's features in a list; it also provides some other common features across all the applications (like the "Problem", "Help", and "Log out" icons). The menu rendering is controlled by the Menu class.

The Menu class allows you to render the current application utilities' links in an HTML unordered list, allowing you to set the style of it using CSS. The default Horde layout uses the menu ID to fix the menu on the top right corner of its templates.

If you wish to customize the menu, you need to create a Menu class. The constructor function accepts one parameter, called $mask, which is useful to add common links in the menu, like a Help link, or a Problems link.

A picture of the icons whose appeareance is determined by the Menu mask.

In the image above, you can see the icons that can be masked by the Menu class. Number 1 corresponds to HORDE_MENU_MASK_PROBLEM'.

An introductory example: The login screen

TODO: An easy example of changing the login screen structure.

References