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.

About the author

Dave Leffler
Exponent CMS Developer

Comments

No Comment yet

Leave a comment

Fill out the above security question to submit your form.