Changes between Version 1 and Version 2 of doc/developer/PortalCustomization

Show
Ignore:
Timestamp:
06/04/07 12:34:18 (13 years ago)
Author:
benoitg
Comment:

Big update

Legend:

Unmodified
Added
Removed
Modified
  • doc/developer/PortalCustomization

    v1 v2  
    1 Author: Benoit Grégoire, [[Timestamp]] 
     1Contributors: Benoit Grégoire, last update:  2007-06-04 
    22[[PageOutline]] 
    33= Wifidog portal customization = 
     
    1111 * No layout in HTML 
    1212 * Logos and interface layout are added as css 
    13  * Templates are only edited if absolutely unavoidable.  
     13 * Static templates are only edited if ABSOLUTELY unavoidable. 
     14 
     15= Customizing the interface = 
     16== Adding Custom content (links, copyright notes, taglines, RSS feeds, etc.) (Already exists) == 
     17 
     18All 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  
     19 * [wiki:ContentDistributionSystem] 
     20 * [wiki:doc/auth-server/ContentManagerTutorial] 
     21 
     22=== Custom content and Interface elements logical positioning (Completed 2006-05-09) === 
     23Note:  The system now uses the structural layout documented below, but HTML and CSS refactoring isn't yet entirely complete. 
     24 
     25We 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: 
     26 
     27 * attachment:"structural_layout_wifidog.odg" Open Document 
     28 * attachment:"structural_layout_wifidog.pdf" PDF  
     29 
     30(Big thanks to Patrick Tanguay for reviewing the first version) 
     31 
     32When content is assigned from the web interface, it will have 3 attributes: 
     33 
     34 1. Page: "login", "portal" or "everywhere" (everywhere is not only login and portal, but also the admin interface and every other page) 
     35 1. Area: The id of the grey divs in this diagram 
     36 1. Display order: In what order is content displayed within an area  
     37 
     38 
     39== Changing the layout (CSS skinning) == 
     40 
     41Stylesheets in wifidog are applied as follows: 
     42 
     43 1. Default wifidog stylesheet (default theme) 
     44 1. Network specific stylesheet (network theme pack) selected in Network preferences 
     45 1. Stylesheet content type(s) added in the content manager 
     46 
     47=== Styling using the CSS theme manager (Available since 2006-05-10) === 
     48All 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 
     49 
     50The advantage of using network theme packs are: 
     51 * Easy inclusion of images 
     52 * Can be versioned in SVN, allowing developers to include your theme pack in search an replace, reducing your maintenance burden. 
     53 * Negligible load on the server 
     54Network 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. 
     55 
     56=== Styling using the Stylesheet content type (Available since 2006-11-14) === 
     57It is possible to add one or more stylesheet snipplets using the content manager. 
     58 
     59The advantage of using the Stylesheet content type: 
     60 * Can be added to only sking a hotspot, a group of hotspot, or even a single piece of content. 
     61 * Can be edited from the web interface. 
     62 
     63The Stylesheet content type is best used for temporary changes, and for location-specific styling. 
     64 
     65== Customizing the UI == 
     66 
     67=== Static UI elements in the content manager (Ongoing development) === 
     68Several 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. 
     69 
     70=== Dynamic Smarty templates (Available since 2006-12-31) === 
     71You 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. 
     72 
    1473== Localization == 
    1574=== Static strings and gettext === 
     
    3291 1. To display any available string  
    3392 
    34 == Customizing the interface == 
    35 === Custom content (links, copyright notes, taglines, etc.) (Already exists) === 
    36  
    37 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. 
    38 === Interface elements === 
    39  
    40 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. 
    41 === Custom content and Interface elements logical positioning (Completed 2006-05-09) === 
    42  
    43 When content is assigned from the web interface, it will have 3 attributes: 
    44  
    45  1. Page: "login", "portal" or "everywhere" (everywhere is not only login and portal, but also the admin interface and every other page) 
    46  1. Area: The id of the grey divs in this diagram 
    47  1. Display order: In what order is content displayed within an area  
    48  
    49 === Custom css (System now uses this structural layout, but HTML and CSS refactoring isn't complete) === 
    50  
    51 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: 
    52  
    53  * attachment:"structural_layout_wifidog.odg" Open Document 
    54  * attachment:"structural_layout_wifidog.pdf" PDF  
    55  
    56 (Big thanks to Patrick Tanguay for reviewing the first version) 
    57 === CSS Theme manager (Completed 2006-05-10) === 
    58  
    59 The handling of CSS style sheets will be changed to allow theming and easier sharing of designs. Stylesheets will be applied as follows: 
    60  
    61  1. Default wifidog stylesheet 
    62  1. Content class specific stylesheet 
    63  1. Network specific stylesheet (network theme pack) 
    64  1. Hotspot specific stylesheet (Eventually, if enabled in network configuration)  
    65  
    66 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 
    67 == When it isn't flexible enough… == 
     93= When it isn't flexible enough… = 
    6894 
    6995...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. 
    70 Editing templates ¶ 
    7196 
    72 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). 
     97== Creating new content types == 
     98The 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. 
    7399 
    74 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. 
    75 Creating new content types 
     100== Editing static templates (NOT recommended) == 
     101All 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). 
    76102 
    77 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. 
     103Don'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: 
     104 * Ask the mailing list of IRC how you sould go about it. 
     105 * 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.  
     106 
     107If 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. 
    78108== Integrating with an existing CMS == 
    79109 
     
    81111 
    82112 1. Use the IFrame content type, which will display a web page as part of the Wifidog portal 
    83  1. 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 
     113 1. 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 
    84114 1. Use the "URL to show instead of the portal" to completely disable the Wifidog portal for this node and show a custom URL instead.  
    85115 
    86 == Integrating with an existing authentication system == 
     116= Integrating with an existing authentication system = 
    87117 
    88118Wifidog 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.