Goals & Objectives

Recently I have been exploring how to make the process of skinning MindTouch a little easier.  It’s not that skinning Ace, Fiesta or Deuce is hard but there are some improvements that could make customizing MindTouch faster and more flexible.  So, I created a new theme designed specifically to meet the following goals.

1. Provide much more granular control over the layout
2. Make PHP skinning functions understandable
3. Provide a more bare-bones HTML layout for designers to customize as they see fit
4. Require designers to modify just one CSS file
5. Make navigating the theme file system more intuitive

Implemented Changes

As of now this is still experimental and I have no immediate plans to ship it with a MindTouch release.  I figured I could at least document it in the meantime to provide some insight into our skinning ideas.  Here are some of the steps I have taken so far.

1. Separated most of the PHP & HTML
   Formerly only one markup file existed for each theme and its name matched that of the theme, ace.php, fiesta.php, deuce.php.  Each of the these files were loaded with markup, PHP and JavaScript, much of which was not important to a designer.  Additionally because these files were so cluttered visually parsing them was difficult, even for the trained eye.  To solve this problem I moved the HTML content from the markup file to a new file called HTML.php.  The new separated file is intended to provide designers with a more accurate and manageable skinning experience.  I also located HTML.php inside the skin folder to provide more granular control over each skin.  With this change now each skin can have custom markup that is independent of other skins.
2. Restructured the theme files
   When creating this new theme I wanted to make accessing its files more intuitive.  With the other themes there are multiple files in numerous folders that are inserted into the skin.  Custom CSS modifications were always stacked on top of a large underlying layer of MindTouch prescribed CSS.  This approach limited flexibility and forced a very sculpted look & feel upon designers.  In order to solve this problem I removed the base CSS files (_common.css, _style.css) in exchange for one CSS file, _style.css, which resides in the skin folder.  I also shifted the _print.css, html.php and all images to the skin level.  Again, this provides much more granular control over the look & feel of each individual skin and also eliminates any MindTouch defined CSS dependencies.
3. Renamed all the PHP skinning functions
   When I set out to change the theming process I immediately noticed that the PHP skinning functions in each markup file were inconsistent and could be challenging to a non-developer.  For instance there were references to wfMsg(), $this->html(), $this->haveData(), $wgTitle, $wgUser and many more.  While programmatically these functions all make sense they add an unnecessary burden on a designer.  As an alternative I gave these functions new pseudo names that follow a simple pattern and consistent naming schema.  For instance:
   1. $this->SiteLogo();
   2. $this->PageTags();
   3. $this->PageEdit();
   4. $this->PageAdd();
   5. $this->PageTitle();
4. Consolidated CSS files
   Initially when we built MindTouch themes we planned for CSS modifications to be made as an addition to the existing CSS.  While this enabled very rapid theme development it also limited the flexibility of the design and greatly raised the skill level required to completely customize MindTouch.  Additionally it also made many assumptions about how MindTouch should look and generally limited the scope of customization to aesthetic CSS such as colors, fonts, etc.  As a solution I decided to completely remove the base CSS files (_common.css and _style.css) and only reference the _style.css in the skin folder.  I will add, however, that _content.css will remain, as content styling has proven to be the most challenging portion of creating a new MindTouch skin.  The _content.css file is pre-populated with default content CSS but can be modified on a per skin basis.
5. Eliminated unnecessary structure
   In order to make theming more flexible there were some deeper consideration required for the PHP skinning functions.  Whereas the older PHP skinning functions contained a large amount of predefined HTML I opted to remove most of this HTML and place it directly in HTML.php.  This may seem fairly useless but it does shift the control of the HTML into the hands of the designer.  For instance I removed extra wrapper <div>, <li> and <span> elements that were added for CSS identification or to meet some assumed function.  Ultimately now you can decide if your logout button is in a dropdown list, wrapped in <div class=”logout-wrapper”> or just by itself.

Theme File Structure

• Theme (called beech as an example)
  
  • _reset.css – Resets CSS
  • beech.php – The base php file, formerly contained all markup and php
  • head.php – Contains all <head> included files:  CSS, JS, favicon, etc
  • pale/ – Skin folder (called pale as an example)
    • _content.css – Contains editor/content CSS
    • _print.css – Contains CSS for MindTouch print preview
    • _style.css – Contains all chrome/layout CSS
    • css.php – Consolidates css files
    • html.php – Contains the markup for your skin

Conclusion

As I continue to develop this theme I will do my best to keep the community informed via my documentation.  Seeing as this is currently experimental there are no immediate plans to releases.  Please let me know if you have any thoughts or suggestions regarding my approach.

I will continue to document this theme at http://developer.mindtouch.com/Deki/Skinning/Beech

Thanks for your time

Damien Howley
@DamienH