New Themes Guide

From ExponentCMS Docs

Jump to: navigation, search

Edit Menu

  • Icon_Designers_20px.png Designers
  • New Theming Guide (0.97.0)
    Theming conventions and instructions for the new Exponent
  • Old Themes Guide
    An overview of Exponent Themes.
  • Themes List
    A list of Themes currently included with Exponent or available for download.
  • Themes and PHP
    Guide to PHP codes specific to Themes development.
  • Themes and Smarty
    Guide to Smarty codes specific to Themes development.
Edit Menu

Image:Icon_Designers_40px.png Image:Icon_Developers_40px.png New Themes Guide

This page contains a New Themes Guide which is currently being implemented in the Exponent 0.97.0 development trunk.

Contents

Intro

We have made several new changes to how css files are structured, included and stored on the file system. We now collect all the stylesheets and pass them off to a new PHP class called minify. Minify was a Google “Summer of Code” project that takes CSS and JS files and minifies the results, meaning it strips out all whitespacing, linebreaks, unnecessary punctuation, comments, etc. The purpose is to compress our CSS output to the smallest possible file size. We have taken this and are outputting the minified results into one CSS file which then the only css include needed for any given theme. Thus keeping the http requests to an absolute minimum, as suggested by Yahoo's “Best Practices for Speeding Up Your Web Site”.

Rebuilding a Minified Stylesheet

A minified stylesheet can easily be rebuilt. Through the interface, navigate to your administration control panel, and click “Rebuild CSS Files” located under the Developer category. Also, as an alternative, simply delete the .css file located in /tmp/css/ directory, and Exponent will automatically rebuild the stylesheet for you.


Filesystem Structure

The theme directory is now laid out as follows: 

/exponent-install-dir/
    /themes/
       /common/
          /css/required/
          /css/
       /mythemedir/
          /css/required/
          /css/

This provides a default order of inclusion for css files to allow for proper cascading of styles. Exponent will first load the required stylesheets located in /themes/common/css/required. Any stylesheets included in this directory are assumed required by the system in order to display correctly.

The Common Directory

Located in themes/common/css, the common css styles are provided in order to style various views within Exponent that otherwise would not look or function correctly. It provides a place for theme-ambiguous styles. For example, a news module can apply common style to all “read more” links throughout a site, regardless of the theme a designer is using.

Cascade-ability

Upon finding a file in the above directory, exponent will immediately look inside /themes/<mythemedir>/css/required/ for a file of the same name. For example, if admin.css exists in /themes/common/css/required/, Exponent will look inside /themes/<mythemedir>/css/required/ for admin.css, and upon finding it, will include this file directly after, allowing css rules defined in /themes/<mythemedir>/css/required/admin.css to override css rules defined in /themes/common/css/required/admin.css

New exponent_theme_headerInfo() Configurations

There are now several new theme level configurations for the required exponent_theme_headerInfo() function for easily loading & overriding stylesheets. The configuration is set up by passing an array to this function, switching on or off certain options. The default configurations are as follows: 

array(
“reset-fonts-grids”=>false,
"xhtml"=>true,
“include-common-css”=>true,
“include-theme-css”=>true
)

The usage of this function typically works like this: 

<?php
$config = array(
"reset-fonts-grids"=>false,
"xhtml"=>true,
"include-common-css"=>true,
"include-theme-css"=>true
);
echo exponent_theme_headerInfo($config);
?>

Configuration Definitions and Load Order

reset-fonts-grids

This will include YUI's reset-fonts-grids.css, normalizing all fonts and DOM elements, along with applying styles for YUI grids.

xhtml

If it's set to true, a constant called XHTML_CLOSING gets set to " / " . If set to false or left empty, it's set to nothing. It can be used in Smarty in your views as such:

<img src="{$smarty.const. THEME_RELATIVE}images/myimage.jpg" alt="stuff about the image" {$smarty.const. XHTML_CLOSING}>

This way, we can keep any modules' views outside a theme (/modules/ newsmodule/views for example) doctype ambiguous.

Most themers will never need to know it as they will be designing for a particular doctype, but as we're (on the development side) cleaning up views, you'll see this more in the views that ship with Exponent.

include-common-css

This will include all stylesheets in /themes/common/css/, with the same cascade-ability features as the required css functions provide. Finding a .css file in /themes/common/css/, Exponent then looks in /themes/<mythemedir>/css/ for the corresponding file of the same name, and includes this file immediately after, providing proper cascading.

include-theme-css

By default, the include-theme-css flag is set to true. This will then include all CSS files in the Themer's /themes/<mythemedir>/css/ and /themes/<mythemedir>/ directories in to the minified file that are not picked up if the include-theme-css flag is set.

Having both include-common-css and include-theme-css flags set to true, include-theme-css will only grab the files that are not included through include-common-css.

For backward compatibility with older themes, Exponent will look in /themes/<mythemedir>/ for the given stylesheet, just as a fail-safe. When converting older themes, move style files located here into the /themes/<mythemedir>/css/ directory for consistency.

base-styles.css

base-styles.css is the first file to get loaded after the required CSS and YUI's reset-fonts-grids.css (if the reset-fonts-grids flag is set) are loaded. This file should contain all default and global css for the theme.

Viewing Load Order and troubleshooting stylesheets

When theming a site, simply setting your development CONSTANT to 1 (located in /conf/config.php) will halt minification, and print your stylesheets directly to the <head> of the DOM. Switching your development CONSTANT can be done through the interface by navigating to your administration control panel, and clicking “Turn error reporting on” under the Developer category. This will allow themers to find exactly what styles are getting applied from what stylesheet easily.

New exponent_theme_footerInfo() function

All exponent themes now require a function in the foot of you DOM, just before the closing </body> tag called exponent_theme_footerInfo(); This function works in combination with Exponent's {script} plugin, moving all javascript anywhere in the DOM down to the bottom, just before the closing body. This function is required as there's lots of new admin-side functionality that will not otherwise run without exponent_theme_footerInfo(). Here's example markup: 

<?php
	echo exponent_theme_footerInfo();
?>
</body>
</html>

Shorthand for Footer and Header Functions

exponent_theme_headerInfo() can also be called via headerInfo(). The same applies to exponent_theme_footerInfo(), as it can also be called via footerInfo().

Naming Convention

Although a Themer can specify any name to their CSS documents, it’s recommended that if specific style rule needs to be overridden within a given stylesheet in either common or required, a stylesheet of the same name be created within the theme’s css folder, and that rule be overwritten. In this fashion, styles will be easy to track down, modify, and overwrite.

Styling Conventions

To help simplify the styling of views, styling conventions have been implemented to make theming easier and more efficient. While you are free to style your custom views however you like, we ask that if you are planning to contribute your views back to the community that you adhere to the conventions laid out here.

All views will now be encased in a wrapper <div> which will be classed with the module name and view name (lowercase and replacing spaces with hyphens). For example, the listing module in “Top Ten” view will now have a wrapper div that looks like such.... 

<div class=”listingmodule top-ten”>
	.... view output ....
</div>

Within the wrapping <div></div> elements, we will then specify our markup on a theme by theme basis. 

<div class=”listingmodule green-boxes”>
	<h1>Coming up</h1>
</div>

As an example, we will use a Listing Module. With our new conventions, all listing modules can be styled by applying a .listingmodule{} CSS rule. To apply styles on the view specific level, ie the “Top Ten” view, we apply a .listingmodule.top-ten {} rule to our stylesheets, and specify specific elements within them as such .listingmodule.op-ten h1{ font-size:1.5em; }

Here an example full conventionalized markup for a Listing module view named “Green Boxes.tpl”: 

<div class="listingmodule green-boxes">

	{if $moduletitle}<h1>{$moduletitle}</h1>{/if}

	{foreach key="key" name="listings" from=$listings item=listing}
	<div class="item">

		{permissions level=$smarty.const.UILEVEL_PERMISSIONS}
		<div class="itemactions">
			<!-- item actions: re-rank, delete, edit -->
		</div>
		{/permissions}

		<div class="bodycopy">
			{$listing->body}
		</div>

	</div>
	{/foreach}
	<div class="moduleactions">
		<!-- module actions: add item, view all -->
	</div>
</div>

Issues with Internet Explorer 6

IE 6 has a hard time with interpreting multiple class style rules in CSS. For example, according to our conventions, .listingmodule.green-box{} would be interpreted as: .greenbox{}, dropping the .listingmodule portion of our rule.

As our conventions are very much forward compatible, and in most cases, because IE 6 still picks up the correct stylings, this convention should prove a solid solution for designers. As another solution, check out http://code.google.com/p/ie7-js/

Example Usage

Implementing YUI Grids and headerInfo configurations, here's and example of theme-level markup: 

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
 "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
	<?php 
	$config = array(
	"reset-fonts-grids"=>true,
	"xhtml"=>false,
	"include-common-css"=>true,
	"include-theme-css"=>true
	);
	echo exponent_theme_headerInfo($config); 
	?>
</head>
<body>
	<div id="doc" class="yui-t2">
		<div id="hd">
			<?php exponent_theme_showModule("loginmodule","Expanded"); ?>
			<h1 class="logo">Exponent CMS</h1>
			<?php exponent_theme_showModule("navigationmodule","YUI Top Nav","","@top"); ?>
		</div>
		<div id="bd">
			<div class="yui-b">
				<?php exponent_theme_showModule("containermodule","Default","","@left"); ?>
				
			</div>
			<div id="yui-main">
				<div class="yui-b">
					<div class="yui-g">
						<?php exponent_theme_main(); ?>
					</div>
				</div>
			</div>
		</div>
		<div id="ft">
			<?php exponent_theme_showModule("containermodule","Default","","@footer"); ?>
		</div>
	</div>
<?php
   echo footerInfo();
?>

</body>
</html>

Image:Icon_Resources_20px.png Additional Resources

Image:Icon_Resources_20px.png Designers Resources

Retrieved from "http://docs.exponentcms.org/New_Themes_Guide"
Personal tools