doc/developer/PortalCustomization

Contributors: Benoit Grégoire, last update: 2007-06-04

Wifidog portal customization

The first question that new groups of wifidog ask once the have a successful installation is how they can customize it.

This documentation is in the design/developer section because it documents how customization can/should be done in the future, not how it is done now.

General philosophy

  • Custom static content (copyright notes, links and such) are added to the database as content types. They are placed in one of several structural zones.
  • No layout in HTML
  • Logos and interface layout are added as css
  • Static templates are only edited if ABSOLUTELY unavoidable.

Customizing the interface

Adding Custom content (links, copyright notes, taglines, RSS feeds, etc.) (Already exists)

All custom content (including custom HTML fragments) should be placed in the database through the content manager, normally using the TrivialLangstring? and Langstring content types. See

Custom content and Interface elements logical positioning (Completed 2006-05-09)

Note: The system now uses the structural layout documented below, but HTML and CSS refactoring isn't yet entirely complete.

We are in the process of taking as much layout oriented code out of the HTML so everything that is technically doable in CSS will be done in CSS. The structural markup of every page and content element will be uniformized to make more context information available for CSS and make style sheets easier to write and modify. Logical diagrams of the structural markup are available:

(Big thanks to Patrick Tanguay for reviewing the first version)

When content is assigned from the web interface, it will have 3 attributes:

  1. Page: "login", "portal" or "everywhere" (everywhere is not only login and portal, but also the admin interface and every other page)
  2. Area: The id of the grey divs in this diagram
  3. Display order: In what order is content displayed within an area

Changing the layout (CSS skinning)

Stylesheets in wifidog are applied as follows:

  1. Default wifidog stylesheet (default theme)
  2. Network specific stylesheet (network theme pack) selected in Network preferences
  3. Stylesheet content type(s) added in the content manager

Styling using the CSS theme manager (Available since 2006-05-10)

All network theme packs are stored in their own folders (themes packs), allowing the sharing and easy referencing of graphical elements within stylesheets. See source:trunk/wifidog-auth/wifidog/media/network_theme_packs/README.txt

The advantage of using network theme packs are:

  • Easy inclusion of images
  • Can be versioned in SVN, allowing developers to include your theme pack in search an replace, reducing your maintenance burden.
  • Negligible load on the server

Network theme packs are best used to create the general look and feel of your network. This is where you'd replace the wifidog logo with yours, etc.

Styling using the Stylesheet content type (Available since 2006-11-14)

It is possible to add one or more stylesheet snipplets using the content manager.

The advantage of using the Stylesheet content type:

  • Can be added to only sking a hotspot, a group of hotspot, or even a single piece of content.
  • Can be edited from the web interface.

The Stylesheet content type is best used for temporary changes, and for location-specific styling.

Customizing the UI

Static UI elements in the content manager (Ongoing development)

Several important interface elements (ex: list of online users) have been re-written as static content types so each group can configure each one and decide where it is to be displayed (if at all). The idea is the arrive with a practically empty portal to which you can add interface elements as you see fit. Those elements are available from the content manager.

Dynamic Smarty templates (Available since 2006-12-31)

You can now create custom UI elements directly in the content manager using the Smarty language. A number of stable variables from wifidog are available (Hotspot name, number of logged-in users, etc.). Instruction on getting the complete list are available when creating a SmartyTemplate?.

Localization

Static strings and gettext

All static strings (strings defined in php code or in a smarty template) can (or should...) be localized trough gettext by placing them within _(). If your language is not yet supported, see doc/developer/LanguageTranslation

A few notes of coding style:

  • Good: $output=sprintf(_('Welcome %s'), $username);
  • Bad: $output=_('Welcome').' '.$username;
  • Very bad: $output=_("Welcome $username");

Textual content in the content manager

All text-like content (content types inheriting from the Langstring class) can have a version for each installed language in Wifidog. If text in the exact language (ex: fr_CA) isn't available, Wifidog will try

  1. To display text in the same language (ex:fr_FR or fr),
  2. To display text in the country subcode (ex:en_CA),
  3. To display string in the default language
  4. To display any available string

When it isn't flexible enough…

...or until everything above is fully implemented. First of all, if there is something that Wifidog is preventing you to do, please post to the maling-list so we can add the necessary flexibility in the next version. You will save a lot of time down the line.

Creating new content types

The philosophy of the Wifidog CMS is to be a very sophisticated display engine for external or dynamic content, and a very minimalist CMS for static content. That being said, we recognize the need for new content types (ex: iCal aggregator, basic event manager, shoutbox, etc.) and will gladly accept contribution in this area. Since all content types are self enumerating, it should be easy for people to contribute new types without touching a single file in the current code.

Editing static templates (NOT recommended)

All templates in wifidog are meant to ease development, not primarily as a vehicle for customization. They can change at any time and should only be edited as a last resort, there is no mechanism to put templates somewhere to be used instead of the default ones, and there will not be one (in fact old versions of Wifidog once had such a mechanism, but it was removed on purpose).

Don't edit them unless you absolutely have to! It's bad for you (more work to keep up to date) and bad for the project (it doesn't get more flexible). If there is something you would like to do, but can't seem to figure out how, please try to do one of the following:

  • Ask the mailing list of IRC how you sould go about it.
  • Patch the template in a way that is not specific to your group, and send in the patch. Often it's as simple as making an HTML element targetable, and the like.

If you do edit the templates and not send your cahnges in, you will then be responsible for keeping them up to date with changes in the base templates. For this reason, it is strongly suggested that you run your production server from a tagged SVN checkout, not from a tarball. This way, SVN will do part of your change merging job for you, and notify you of the conflicts.

Integrating with an existing CMS

Some groups may already have some location-aware CMS that they want to keep on using, or do not intend to provide any location-specific content. Depending on the level of integration desired, existing systems or web sites can be integrated in one of two ways:

  1. Use the IFrame content type, which will display a web page as part of the Wifidog portal
  2. Use the SmartyWifidog? content type, to display a web page as part of the Wifidog portal while passing of some wifidog variables to the target as a get query. See the content manager tutorial
  3. Use the "URL to show instead of the portal" to completely disable the Wifidog portal for this node and show a custom URL instead.

Integrating with an existing authentication system

Wifidog already support several external authentication systems (Radius, Ldap) through extending the Authenticator class. In the future, the richness of this abstraction will be augmented by making the login interface, new user creation interface and parts of user administration defined by the authenticators.

Attachments