Blog items tagged with "theming"

Integrating Bootstrap 4 into Exponent

TBootstraphe primary theme framework for Exponent CMS is Twitter Bootstrap, currently at version 3 (actually 3.3.7). The next Bootstrap release, version 4 should be available in the near future and is currently in the beta 2 stage. It would be good to integrate support for the Bootstrap 4 framework, but there are several obstacles:

  • Bootstrap 4 requires SASS/SCSS stylesheet compilation, where previous versions were based on LESS...and there is only one PHP based SCSS compiler available which chokes on some of our needed stylesheets. However, we've developed a 'hack' to compile them on the fly.
  • Bootstrap 4 also leans toward needing 'autoprefixer' support to add additional 'browser-specific' styles into the compiled stylesheets. There is currently no PHP based autoprefixer (except for some which require node.js be running on the server). This may not be an issue since most modern browsers are supposed to be moving away from vendor specific style properties.
  • Bootstrap 4 is a much greater departure (change) from the previous version (3) than in the past (e.g., v2 to v3). While not insurmountable, it will require updating a lot of Exponent code to produce compatible output for auto-generated form controls and menus, etc...

Now having said that, preliminary support for Bootstrap 4 (beta 2) is already being integrated into Exponent, which in turn also requires a new theme. Though the initial integration at this point is limited to functional navbars/menus and chrome, it is usable (if you can get past some of the odd styling on the page). It is expected this initial integration will be included in the next release of Exponent.

Once Bootstrap 4 is released as final AND we have fully integrated it with a functional theme, it will be released...most likely as Exponent v3. The roadmap to Exponent v3 will also throw off the shackles created by a need to support obsolete browsers and ancient PHP versions, both of which should not be used if security is of any importance. You can expect to see the next release of Exponent (either v2.4.1patch7, v2.4.2, or v3.0.0) around the end of the year.

Making your Custom Theme more Accessible

We're recently added better 'accessibility' support to Exponent so it may be used with a screen reader. This is mandated with some public website due to the Americans with Disabilities Act. While the code shipped with Exponent v2.4.0 includes these changes, they may need to be integrated into your custom theme. Though you can check your theme/subtheme templates and custom views with the ones we ship, here are some things to look for:

  • The theme/subtheme templates must contain a 'language' in the html tag
    • from
      <html>
      to 
      <html lang="<?php echo (substr(LOCALE,0,2)) ?>">
  • any {img ...} tag found in any template view (.tpl file), must include a 'alt=xxx' entry
  • any button or input area with NO label, or any with only an icon must include 
     aria-label="{'button label'|gettext}"

While this is not an all-encompassing list, it will get you through most of the errors that an accessibility plugin for your browser would report

Theming with Twitter Bootstrap version 3 - Part 3

Twitter Bootstrap 3(Corrected May 5, 2014) Recently, Google changed the way they rank search hits by elevating those from 'mobile friendly' web sites and lowering those which are not mobile friendly.  To be 'mobile friendly' your web site must conform to modern standards (HTML5) AND must be small device and 'touch friendly' ...meaning the page is viewable on a small screen and the buttons/links have some space/distance between them for 'fat fingers.  The easiest way to make your Exponent CMS site 'mobile friendly' is to switch or update to a Twitter Bootstrap 3 based theme.  Exponent CMS allows you to do this in just a matter of minutes.

The easiest (and most obvious)  method is to simply switch to the included 'bootstrap3theme'.  This would immediately ensure your web site is 'mobile friendly.'  In most cases, the content of you web site will remain unchanged, though some custom theme elements in the header, footer, and sidebar may not appear if you were using a non-standard 'source' name within the previous custom theme.  In its stock form, the bootstrap3theme is well, plain.

The next level of customization would be to 'customize' the shipped theme using the 'Configure' button found with the theme on the 'Manage Themes' page.  

  • We offer a dozen or so different theme styles which offer a variety of colors, fonts, and styles
  • You could spice up the look with some 'flair' to the widgets by selecting the 'Bootstrap v2 Styles' setting which will give them a slight 3d effect
  • You could choose a 'fluid' width which would make the content fill almost the entire width of the display or browser width.  'Fixed' width limits the overall width of the content.
  • You can also select the 'size' of the buttons, location of the main menu (navbar), whether the navbar is aligned to the left or right side of the page, whether the flyout sidebar container is displayed, and a couple of tweaks to adjust how the main navbar is displayed.

The only drawbacks thus far are: 1) the theme and its 'configuration' will be overwritten the next time you update the site software with a new version since you are using a 'shipped theme', and 2) the basic Twitter Bootstrap themes are somewhat lacking in 'flash'.

Therefore the next level of customization would be to create a custom version of the shipped bootstrap3theme.  The documentation for creating a custom theme is found here.  A quick overview would be  to copy the entire /themes/bootstrap3theme folder into a new folder with a different name.  We'll say 'customtheme' for example and ensure we update the new custom theme's 'class.php' file to reflect the new theme's real name.  Once this complete, you'll need to select your new 'customtheme' from the Manage Themes page.  At this point your site will be identical to the previous step, but will not longer be in jeopardy of replacement when updating the site software version.  If you want to place the custom theme swatch files within your custom theme for further customization, you will need to:

  • Copy the .less files from the selected theme style which is found in /external/bootstrap3/less/'theme style name'.  You should find two files here...variables.less and bootswatch.less
  • WARNING! You MUST edit the new variables.less file which will fill in any missing, but essential variables:
    • Add the following line to the TOP of the new custom variables.less file
      • @import "../../../external/bootstrap3/less/variables.less";
    • The 'merge' the contents of the existing 'variables.less' file to the BOTTOM of the custom theme variables.less file to ensure any custom navbar 'collapse' width is followed.  
  • NEXT you MUST also insert the following line at the top of the 'bootswatch.less' file to get it to compile correctly
    • @import "variables.less";
  • Then if you want to make some subtle color changes, you can use a site like bootswatchr.com which will let you copy in your 'variables.less' file and allow you to edit it with instant feedback on color changes.

That's it, you now have a custom 'mobile friendly' web site.  Next time we'll dig a bit more deeply (and spend more time) to customize the theme to look 'less plain.'

Basic Theme Framework Concepts

Bootstrap 3A 'theme framework' is a tool or library of stylesheets and javascript code which help a web designer more efficiently create a stylish web site. In most cases they allow for effectively sectioning off a page using styles instead of tables. They also include code to easily create the different user interface 'widgets' and utilities which would otherwise take a lot of code (e.g. time) to produce.  Exponent CMS currently contains built-in support for two (2) different theme frameworks: 1) Yahoo User Interface (or YUI), and 2) Twitter Bootstrap (or Bootstrap).  And within each of these frameworks we include two (2) versions.  The question is 'which one to use?'

First, we'll cover some definitions which relate to the goals of each of these theme frameworks:

  • Fixed - this term relates to a section (page, column, etc...) having a 'fixed' width in terms of pixels.  Regardless of the size of the display (this includes the width of the browser window when resized), the section is the same size.  A fixed section may have to be 'zoomed' in order to be fully displayed on the screen, and then the size of the text may be unreadable.
  • Fluid - this term relates to a section having a 'fluid' width in terms of percentage of the parent section.  When the size of the parent container changes, the 'fluid' section will change.  A fluid section inside a fixed section would appear to be fixed, but could adjust based on the style used for that parent section.
  • Grids - this term relates to using html 'div' containers to section off a web page layout, instead of having to use html tables (which at this point in time is an ancient concept).  Most web pages have many grids, especially to make headers, columns, navigation areas, etc... for the page layout.  In other words, to keep the entire page from acting as if it were a single block of text.
  • Responsive - this term relates to the page layout (automatically) adjusting itself based on the size of the display (whether due to the physical size of the screen or width of the browser window).  Of these four definitions, this is 'the goal' for being able to present content to a visitor to your web site.  Imagine browsing to a web page on your smart phone, where the entire page is displayed but it is so small it is unintelligible...enter 'responsive' web site styling.  In days past, web designers were required to create two different web sites to provide content to both small handheld devices and desktop pc's.  Exponent provides built-in support for using two different types of sub-themes  based on whether a device is small or large (mobile theme variations), but that still requires creating two page layout designs.  'Responsive' styling allows a single page layout to provide the best information display to the user regardless of the size of display being used.

A basic rundown of the five (5) available frameworks (we'll count 'NO' theme framework as one) included in Exponent are:

  • YUI2 - has been deprecated since 2011 and was the primary framework used in Exponent v0.9x..  The styles allow for both fixed and fluid grids, but they are not responsive.  It also provides many widgets from its own javascript code library.  
    • YUI3 based widgets are automatically displayed, since we've replaced all the YUI2 javascript code (as of about v2.3.0)
    • To use the YUI2 grids, you must specially load the stylesheet 'YUI2_RELATIVE."yui2-reset-fonts-grids/yui2-reset-fonts-grids.css"' in your expTheme::head();. YUI2 grids typically use a class name with a 'yui-' prefix and provide both fixed and fluid variations
    • Though we don't recommend creating new custom themes based on YUI2, there is an example theme named 'basetheme'  based on YUI2 available here.  
  • YUI3 - is no longer supported by Yahoo, but is still being maintained.  It was the primary framework used in Exponent v2.x until v2.2.0.  The styles allow for both fixed, but mostly fluid grids, and more recently (since v2.2.0) allows for minimal 'responsive' support.
    • YUI3 based widgets are automatically displayed.  To display jQuery library based widgets (if they are available instead of YUI3), you can set the theme framework to 'jquery' in your expTheme::head(); (which also automatically loads the jQuery javascript library).  You can also display Bootstrap 3 based widgets (including the Exponent and module menus) by setting a config.php constant named 'NEWUI'.
    • To use YUI3 grids, you must specially load the stylesheet 'YUI3_RELATIVE."cssgrids/cssgrids-min.css"' in your expTheme::head();.  YUI3 grids typically use a class name with a 'yui3-u-' prefix.
    • Though we don't recommend creating new custom themes based on YUI3, we ship an example theme named 'simpletheme'  based on YUI3.  
  • Bootstrap 2 - was originally shipped with Exponent v2.2.0.  The styles allow for both fixed and fluid grids with some responsive support.  The typical grid system uses 12 columns.  To use the Bootstrap 2 theme framework, set it to 'bootstrap' in your expTheme::head();
    • Bootstrap 2 based widgets are automatically displayed (using jquery or YUI3 widgets if Bootstrap 2 ones are not available).  The Exponent and module menus are still YUI based.  Bootstrap 2 widgets use the jQuery library, but are written to support Bootstrap 2 styling.
    • Bootstrap 2 grids are automatically available with responsive support and columns typically use a class name with a 'span' prefix.
    • We also automatically provide Font Awesome v3.x support with icons having an 'icon-' prefix.
    • Since Bootstrap 2 has reached 'end of life', we don't recommend it for new custom themes, however we ship an example theme named 'bootstraptheme' based on Bootstrap 2.
  • Bootstrap 3 - is the current recommended theme framework for Exponent and has been available since v2.3.0.  Like Bootstrap 2 it's grid system uses 12 columns, but allows for fully 'responsive' web designs since it is 'mobile first'.  Each grid may be 'classed' as to how it should display on various sized devices (large widescreen desktops, medium desktops, tablets, and smart phones).    To use the Bootstrap 3 theme framework, set it to 'bootstrap3' in your expTheme::head();
    • Bootstrap 3 based widgets are automatically displayed (using Bootstrap 2, jquery, or YUI3 widgets, in that order if Bootstrap 3 ones are not available).  Bootstrap 3 widgets use the jQuery code library, but are written to support Bootstrap 3 styling.
    • Bootstrap 3 grids are automatically available with responsive support and columns typically use a class name with a 'col-' prefix.
    • We also automatically provide Font Awesome v4.x support with icons having an 'fa-' prefix.
    • Bootstrap 3 is the recommended theme framework and we ship an example theme named 'bootstrap3theme' based on Bootstrap 3.
  • No framework - you are not required to use a theme framework for a custom theme in Exponent CMS.  In fact most web theme templates can be converted for use in Exponent (see this article)
    • YUI3 based widgets are automatically displayed.  To display jQuery library based widgets (if they are available instead of YUI3), you can set the theme framework to 'jquery' in your expTheme::head(); (which also automatically loads the jQuery javascript library).

If you have already developed a custom theme for Exponent, you may want to stick with a known quantity and use that familiar theme framework.  However, if your just starting a custom theme, we'd recommend using Bootstrap 3.  Though we will continue to include, support, and fix the YUI2, YUI3, and Bootstrap 2 theme frameworks, in the future most of the new features will emphasize Bootstrap 3.

NOTE: For details about building a custom theme for Exponent CMS or about how themes work, please visit our help/documentation pages found here.  Details about the expTheme::head() method are found here.

Theming with Twitter Bootstrap version 3 - Part 2

Mobile FirstIn the first article, I explained some of the basics of creating a Twitter Bootstrap 3 (BS3) based theme for Exponent.  In this article I'll attempt to alleviate some of the myths or quirks associated with BS3 that may be delaying your move to use this versatile framework for your next custom theme.

Myth #1 - BS3 themes are limited to a one page design - NOT TRUE.  While many of the examples found across the internet are limited to one (possibly) long page with a menu of relative links on the page, you can still use the multi-page approach Exponent has used in the past.

Myth #2 - BS3 themes must have the fixed menu (navbar) always displayed at the top of each window - NOT TRUE.  Again, while many examples on the internet follow this approach, our sample BS3 theme (bootstrap3theme) provides the option of 'static top' (stays at the top of the content and will scroll out of view), 'fixed bottom' (always displayed at the bottom of the window), or 'fixed top' (always displayed at the top of the window).

Additionally, you may place a banner above the navbar using one of the techniques found here.  You are not limited to generic sort of layout.  Some example non-Exponent themes can be found at:

Quirk #1 - BS3 navbars are limited to children only (depth of two) and no grandchildren (depth of three or more) - While we support multi-level navbars of any depth, this will NOT work with touch devices (grandchildren are only displayed on 'hover'), nor with the 'collapsed' menu provided on small devices (or small width browser windows)

Quirk #2 - Not everything is 'touch' enabled - Though we're working inside Exponent to alleviate (work-around) this, some elements like the 'carousel' are not 'touch' enabled, in addition to the aforementioned multi-level menus.

Quirk #3 - The site looks slightly different on different sized devices or different browser widths - This is actually a feature, NOT a problem.  With BS3 you won't need to develop a complex stylesheet based on media queries, nor have separate mobile subthemes (a feature of Exponent documented here).  Since BS3 is 'mobile first' it makes it simpler to desing a web site style and layout which works equally well on large (desktop) or small (smartphone) displays.

Hopefully, this has alleviated some of your fears in pressing forward into the Bootstrap era.  I do still plan to write another article/tutorial on converting an open-source/free BS3 theme (from one of the sites listed above) into an Exponent theme, which may be a greater incentive to take the plunge.

Theming with Twitter Bootstrap version 3

Twitter Bootstrap 3 - MObile FirstTwitter Bootstrap version 3 (BS3) is becoming the user interface framework library of choice for Exponent CMS.  Though initially shipped with Exponent v2.3.0, that BS3 implementation was still lacking some refinement, and wasn't fully implemented across the entire user interface.  This has been somewhat remedied by the first three patches to v2.3.0, and will be even more-so in the upcoming patch #4 release.  In this article I'll attempt to share some of the basics of how to create a Twitter Bootstrap 3 custom theme.

First off, this is NOT an introduction to using Twitter Bootstrap 3 or it's grids, nor understanding what 'mobile first' or 'responsive' means.  There are several tutorials on the web including this one.  However, we won't avoid those topics as we focus on Exponent CMS theming specifics as they apply to using BS3.

We ship a BS3 sample theme with Exponent v2.3.0 appropriately named 'bootstrap3theme'.  Since the release of v2.3.0 we have tweaked this theme (as we said we would), therefore the one being included in v2.3.0 patch #4 has some changes from the one included in the initial release.  This article assumes you have access to those sample theme files and can use it as a starting point.  Eventually I may also publish a second part to this article to walk you through converting an existing open source BS3 theme template for use as an Exponent template (with the purpose of it being added to the help/doc site).

When you examine the /themes/bootstrap3theme/index.php default theme template, you'll note several Exponent specific things in the 'head' section with the expTheme::head() parameters: 

  • the 'framework' parameter is set to 'bootstrap3'.  This automatically ensures we are loading the BS3 stylesheets, jQuery script, and 'prefer' the '.bootstrap3' view template variation (which includes any form control or template engine plugin variations) if available.
    • BS3 scripts are never automatically loaded, but must be requested by the expJavascript::pushToFoot() call or the theme template {script} smarty function using the 'bootstrap=' parameter.  This parameter works just like the 'yui3mods' and 'jquery' parameters.
  • there are no 'reset' scripts being loaded.  The new standard css reset script, 'normalize.css' is automatically loaded by BS3.
  • we can optionally load the BS3 'theme' stylesheet which gives a BS2 appearance to BS3 styles, if that setting was saved within the theme configuration.
  • though the 'viewport' parameter is optional since we always set the minimum defaults, it is in this theme template as a point to deviate from.
  • we account for two (2) less stylesheet compiler variables (lessvars) we pull from the theme configuration settings which are mandatory for this theme's .less stylesheets.  Most (but not all) stylesheets used with a BS3 theme are in the .less format to allow custom configuration by the end user.  For example, the bootstrap3theme allows selecting from the entire set of 'BootSwatch' themes.  

Now a short sidebar on some BS3 basic concepts...there is a hierarchy of three (3) basic components for the BS3 grid system: 1) container, 2) row, and 3) column.  

  • The 'container' class element is mandatory as the highest level element for the grid system.  It may NOT be nested as this will create anomalies with display of the page.  The classname used for a container element is 'container'.
  • The 'row' class element MUST be placed within a 'container' class element, however unlike the container, they may be nested if the nesting occurs within a column.  In a basic sense, the row is a placeholder for up to 12 equal-width columns of data.  The classname used for a row element is 'row'.
  • The 'column' class element MUST be placed within a 'row' class element, and like the container may NOT be nested...except when found within a nested row.  The classname for a column element is more complex and composed of at least three (3) parts:
    • 'col-' to signify that this is a column
    • a designator for the device size the column setting applies to (more or this later).  But in our example we'll use the size for a small device or tablet with a max-width of 768 pixels which is 'sm-'.  Grid column classes are divided into device sized groupings:
      • 'lg' for large devices such as wide-screen monitors (max width 1200 pixels)
      • 'md' for medium sized devices such as desktop monitors (max width 992 pixels)
      • 'sm' for tablet sized devices
      • 'xs' for extra small devices such as phones (max width 640 pixels
      • These can be mixed within the same element to provide for a different layout on different devices.  E.g., a 4 column wide layout on a desktop would become a 2 column layout on a tablet (2 rows high) or a single column layout (4 rows high) on a smartphone.
    • and a digit to set the number of column units of width this column is to fill (from 1 to 12)
    • so the simplest column element would be 'col-sm-12' for a single column the entire width of the row.  A equal-width 2-column layout would be two elements each with a class of 'col-sm-6' (6 + 6 = 12).

<body>
    <div class="container">
        <div class="row">
            <div class="col-sm-12">
               This is a full width column, 12 units wide.
               A row with columns could also be placed within this element.
            </div>
        </div>
    </div>
</body>

Therefore, in Exponent, the template theme/subtheme template MUST hold any 'container' element(s).  There must NEVER be an element with the class of 'container' found within a view template.  A BS3 styled view template can ALWAYS assume it is being loaded within a 'container' and/or a 'column' element.  Therefore, the view template should be wrapped within a 'row' element if it will be subdividing its display using the grid system with 'column' elements.  The only exception to this is the navigation menu (navbar) which in most examples (including the main BS3 site) is simply wrapped within a 'container' element without rows nor columns.

So within the 'body' section of the /themes/bootstrap3theme/index.php default theme template, you'll note:

  • We have two (2) containers: one for the menu and one for the content
  • Within the menu container we have NO rows or columns, so the menu 'template' view can assume it's within a container
  • Within the content container we have two rows: one for the actual page content, and one for the page footer area
  • Within the actual page content row we have two columns: one for the main content, and one for the sidebar

For the Exponent theming system to work correctly with several UI frameworks, we allow for view templates to also have theme framework variations.  These system view templates are denoted by a framework type suffix before the file type.  So a system 'showall.tpl' view template with a BS3 variation would be named 'showall.bootstrap3.tpl'.  In the absence of a BS3 specific view template, the system would fallback and choose a BS2 template with that framework suffix...in this example if the BS3 variation template did not exist but a BS2 variation template existed named 'showall.bootstrap.tpl, it would be used instead of the base 'showall.tpl' file.  Since a custom theme can only use one UI framework, ALL custom template views use the root name without any framework variation.

A note about the /themes/bootstrap3theme/config.php theme configuration settings file.  You MUST include a variable named 'SWATCH' or the .less stylesheet compiler will crash when compiling the BS3 stylesheets. 

There MUST always be a file /theme/customthemename/less/variables.less, even if it's an empty flle. This file is ALWAYS compiled by the bootstrap.less file and overrides any bootstrap 3 and swatch variables as needed.  A failure to include this file (it may be empty) WILL result in a .less compiler crash.  This file should ONLY contain .less 'variables' as it will also always be compiled as a theme stylesheet and any 'styles' included within in it will also create a theme stylesheet named /css/variables.css.

In summary:

  • The theme/subtheme template MUST include the un-nested BS3 'container' element.  The theme/subtheme template is the only place the 'container' element will be found.  It may optionally contain 'row' elements' so long as it also contains 'column' elements within the 'row'.
  • The view template can always assume it's being displayed within a 'container' and/or also a 'column' element.
  • Any 'custom' view templates must only have the '.tpl' file type suffix and can NOT contain the '.bootstrap3.tpl' framework variation suffix.
  • Failure to follow these guidelines will cause horizontal margin anomalies and prevent theme custom views from loading

Preparing to Upgrade to v2.3.0

Version 2.3.0 is the follow-up to version 2.2.3 and was given a version bump due to the many new features added.  It also marks a 'slowing down' of version releases as it's purposely been five months since the last release.  While it doesn't require as many changes as the move to v2.2.0 (which deprecated all the old 1.x code), it would still be wise to note and adhere these following changes.

The navigation showall_Flydown view for a bootstrap based theme now includes all the associated markup in the view instead of in the theme template.  Therefore if you use this view or have based your custom theme on 'bootstraptheme' (it is the default menu for the boostraptheme) you MUST edit your theme templates (including subthemes)

  • The older code looked something like:
    <!-- navigation bar/menu -->
    <div class="navigation navbar <?php echo (MENU_LOCATION) ? 'navbar-'.MENU_LOCATION : '' ?>">
      <div class="navbar-inner">
        <div class="container"> <!-- toggle for collapsed/mobile navbar content -->
          <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span> <span class="icon-bar"></span>
          <span class="icon-bar"></span> </a>
          <!-- menu header -->
          <a class="brand" href="<?php echo URL_FULL ?>"><?php echo ORGANIZATION_NAME ?></a>
          <!-- menu -->
          <?php expTheme::module(array("controller"=>"navigation","action"=>"showall","view"=>"showall_Flydown")); ?>
        </div>
      </div>
    </div>
    <div class="navbar-spacer"></div>
    <div class="navbar-spacer-bottom"></div>
  • This is simply replaced by:
    <?php expTheme::module(array("controller"=>"navigation","action"=>"showall","view"=>"showall_Flydown")); ?>
  • Depending on which exponent version you created your theme from (first shipped w/ v2.2.0), you may not have all those lines above.  In fact, in v2.2.0, the menu was a theme custom menu simply call 'showall'

There may be duplicate Search Engine Friendly (SEF) URLs.  We include an optional upgrade script to correct this issue, but do NOT run it automatically.  Duplicate SEF URLs can cause issues when using the new 'Workflow' feature.

If your pages/content seems to have disappeared for non-admin users, you should first (re)run the 'Fix Sectionrefs' upgrade script.  If that doesn't fix the problem, you need to ensure the 'Disable Privacy Feature' is selected found in 'Confgure Website' Exponent menu item, under the 'Display' tab.

If you have manually loaded the 'jQuery' script, it may be colliding with the auto-loaded jQuery script.  The BEST method to ensure that jQuery is auto-loaded, is to set the theme framework (in the theme template/subtheme templates) to either 'jquery'.  jQuery is also auto-loaded with the bootstrap theme frameworks.  Documentation found here.

Again, not a lot of earth shattering changes required, but we always recommend doing a test before upgrading a production web site, just in case.

Coping with the v2.0.9 Upgrade

Unlike most previous releases, the release of v2.0.9 has seen it's share of problems.  Though most of these are minor issues, they can seem to be an obstacle if not addressed.  Here's some things to watch out for, and steps to correct these issues:

Git Pull upgrade creates a merge conflict and the site 'crashes':

'Git' is supposed to prevent this, but for some reason when updating (git pull) a 'git' maintained site from 2.0.8 (or the patches) to 2.0.9, you'll receive a notice of a merge conflict and the site will no longer work.  The problem lies in two files (exponent_version.php and framework/modules-1/calendarmodule/class.php).  There are a couple different options to fix this, so you'll find the details in this forum post.  We are working to alleviate this issue!

Menus don't work the same as before the upgrade:

Even though the new navigation controller includes some compatibility to still allow old style navigationmodule modules to work...this apparently isn't true in all circumstances, especially complex menus.  The solution is to update the calls and the templates/views to the new 2.0 navigation module format.  This is a fairly simple change as it entails copying and renaming those custom templates.  You'll find the details in this forum post.

My customized site 'crashes':

This occurs if you are running customized modules (controllers) on your site.  Because PHP v5.4.x enforces greater code standards, we've had to update some of the main code which in turn requires updates to any custom modules (controllers).  This is a fairly simple update as it entails adding the 'static' keyword to the static functions inherited from the parent expController class.  You'll find the details in this forum post.

We'll keep this article up to date as things progress.

Tutorials: How to Convert a Generic Theme to Exponent

Here is a tutorial that will be appearing on the docs site which walks you through converting a generic web theme/template found on the internet into an Exponent theme.

Here's how you can create a custom theme using a generic web theme template.  There are countless free and paid web templates available on the internet.  You may search one of the template collection web sites to locate a 'theme' you would like to incorporate into Exponent.  For the purposes of this tutorial, we'll select a simple 3-column liquid template.

The template we've chosen can be found at http://matthewjamestaylor.com/blog/ultimate-multi-column-liquid-layouts-em-and-pixel-widths and we'll use the 3 Column (Blog Style) Liquid Layout which can be downloaded here.  Most themes are very easy to convert EXCEPT for the menu.  In this case the menu is an easy drop in replacement since the basic template doesn't really feature a menu,  Other templates might require custom styles to make it look similar, where others might require a near rewrite to create a duplicate menu.

Extract the template package to a new subfolder within the /themes folder.  Rename the folder to 'blogtheme'.  ALL themes MUST use a folder name that ends with the 'theme' phrase!  Inside the folder you'll note several files, one of which is 'index.htm.'  Open it in your browser to see what we've got.  You'll also note several graphics and a single stylesheet file in the folder.

Next we'll need to reorganize the folder to conform to Exponent theme requirements.  Create a 'css' folder and place all the stylesheets there (in this case only screen.css).  Create an 'images' folder and place all the images there (in this case none of the images are really used in the theme).  Next edit the index.htm and css/screen.css files to update the references to the new locations.

  • In index.htm, you'll need to change the stylesheet and image references (this isn't necessary, but a good troubleshooting step).
    • <link rel="stylesheet" type="text/css" href="screen.css" media="screen" />

      to

      <link rel="stylesheet" type="text/css" href="css/screen.css" media="screen" />
    • <img src="mjt-125x125.gif"

      to

      <img src="images/mjt-125x125.gif"

      there are several of these.

  • In css/screen.css, you need to change the references to graphics.  This is NOT necessary in this tutorial since there are NO graphics referenced by this particular css file, HOWEVER this is not simply a trouble shooting step!

    • Search for every instance of 'background : url(' and correct the url.  In this sample if there were any images, we could add an '../images' prefix to point to the new location of images.

  • Refresh the sample page in the browser and you should see NO changes if everything went well.  Otherwise you need to check your edits.

Next we'll create the theme class file.  Copy the 'class.php' file from the simpletheme folder.

  • Change the following line:
    if (class_exists('simpletheme')) return;
    to
    if (class_exists('blogtheme')) return;
  • and change the following line:
    class simpletheme extends theme {
    to
    class blogtheme extends theme {
  • Change the string in the name() function to "3-Column Blog Theme", you could also eidt the author() and description() strings as desired.

Now we'll convert the index.htm file into a theme template.

  • Rename index.htm to index.php
  • Replace the contents of <head>...</head> with expTheme::head() since Exponent handles this for us:
    <head>
        <?php 
        expTheme::head(array(
    	    "xhtml"=>false,
        	"css_core"=>array("common"),
        	"css_links"=>true,
        	"css_theme"=>true
            )
        );
        ?>
    </head>
  • We'll also need to add the mandatory Exponent footer just above the closing </body></html> tags since this is what actually places the css and javascript on our pages

    <?php expTheme::foot(); ?>

You should now be able to select your new (useless) theme in Exponent, so log on to your site and Manage Themes and select your new "3-Column Blog Theme".  Don't expect too much just yet as we have NO dynamic content.  If you can select the theme and the site displays properly with the Exponent menu, we can proceed.  Otherwise you'll need to check the above steps and your editing for accuracy.

Next we'll clean the dead wood (static content) out of our template, index.php and replace it with dynamic content code.

  • Delete all the lines between <div id="header"> and its closing </div> tag, about 13 lines and replace it with our header and menu 
    <h1>
        <a href="<?php echo URL_FULL; ?>" title="<?php echo SITE_TITLE; ?>"><?php echo ORGANIZATION_NAME; ?></a> <sub><?php echo SITE_HEADER; ?></sub> 
    </h1> 
    <?php expTheme::module(array("controller"=>"navigation","action"=>"showall","view"=>"showall_YUI Top Nav","source"=>"@top")); ?>
  • Look for the <!-- Column 1 start --> comment and delete all the lines to the <!-- Column 1 end --> comment and replace it with our main container

    <?php expTheme::main(); ?>
  • Look for the <!-- Column 2 start --> comment and delete all the lines to the <!-- Column 2 end --> comment and replace it with our left column container
    <?php expTheme::module(array("module"=>"container","view"=>"Default","source"=>"@left")); ?>
  • Look for the <!-- Column 3 start --> comment and delete all the lines to the <!-- Column 3 end --> comment and replace it with our right column container
    <?php expTheme::module(array("module"=>"container","view"=>"Default","source"=>"@right")); ?>
  • Finally, replace all the lines between <div id="footer"> and it's closing </div> with our footer text module
    <?php expTheme::module(array("controller"=>"text","action"=>"showall","view"=>"single","source"=>"@footer","chrome"=>1)) ?>

We're almost done, but need to add some styling to the .css file to ensure Exponent menus, etc.. are always in front of other items.

  • The easiest way to do this is to create a 'base-styles.css' file in the /css folder.  We'll need to ensure the <div> id's match the one's used in the template.  Here's what our's would look like
    #header, #bd, #footer {
        position:relative;
    }
    #header {
        z-index:3;
    }
    #header {
        position:relative;
        z-index:5;
    }
    #bd {
        z-index:2;
    }
    #footer {
        z-index:1;
    }

At this point we should have a fully functioning theme suitable for use.  In most cases you may need to tweak the theme styles to override system styling or other conflicts resulting from the theme's styles.  This may be as simple as too much/little spacing to the menus don't work because most menus are actived by css styling or javascript which rests on using css styling.

The last thing we might want to do is to create a CKEditor css file.  You can find those details here.

(updated) Two Column Forms (or something like that...)

(Updated Aug 2nd) We've had several requests lately to 'make forms look like they did in versions prior to v0.97.'  Meaning, place the label and input control on the same line instead of the label above the input control.  Since we're trying to move away from using tables to format the layout (the html5 way of doing things), it's not an easy fix, HOWEVER we can simulate the look using css styles.  (NOTE: we have implemented a Single column/Two Column form settings option in the next version 2.0.9 which will easily implement this feature)

Forms in 2.0

Forms in 0.96

Restyled Forms in 2.0

Though you won't necessarily end up with an exact reproduction, it will look similar.  One drawback is the width of the label is a hard width and will truncate long labels.  This more robust styling below prevents the label truncation.  Enter/Change this into your theme stylesheet: (updated Aug 2nd)

.control  {
    overflow: auto;
}

.control .label {
    display: block;
    float: left;
    width: 150px;  /* non-flexible part truncates label */
    text-align: right;
}

.control.radio .label {
    width: auto;  /* make radio buttons look normal */
}

.control.checkbox .label {
    width: auto;  /* make checkboxes look normal? may not be needed */
}

.datetime.date, .control table, .control.radiogroup table, .control.radio table, .control.checkbox table {
    display: inline;
}

.control-desc {
    margin-left: 160px;  /* make description fall directly under input */
}

.formmoduleedit .item-actions {
    display: inline;
    float:  right;
}