doc/developer/PortalCustomization

Version 1 (modified by benoitg, 13 years ago)

Restore page mistakently deleted as part of SPAM cleanup

Author: Benoit Grégoire,

Error: Failed to load processor Timestamp
No macro or processor named 'Timestamp' found

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
  • Templates are only edited if absolutely unavoidable.

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

Customizing the interface

Custom content (links, copyright notes, taglines, 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.

Interface elements

Several important interface elements (ex: login form, list of online users) will be re-written as static content types so each group can decide where it is to be assigned.

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

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

Custom css (System now uses this structural layout, but HTML and CSS refactoring isn't 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)

CSS Theme manager (Completed 2006-05-10)

The handling of CSS style sheets will be changed to allow theming and easier sharing of designs. Stylesheets will be applied as follows:

  1. Default wifidog stylesheet
  2. Content class specific stylesheet
  3. Network specific stylesheet (network theme pack)
  4. Hotspot specific stylesheet (Eventually, if enabled in network configuration)

All stylesheets 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

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. Editing templates ¶

All templates in wifidog are meant to ease development, not primarily as a vehicle for customization. Templates 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).

If you edit the templates, 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. 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.

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 IFrameRest content type, which will display a web page as part of the Wifidog portal and allows passing of some wifidog variables to the target as a get query
  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