exponent-cms team mailing list archive

[Phillip Ball <phillip@xxxxxxxxxxxx>]

Here's my unfinished start to the theming engine in exp2 now. I'll get coolwater upgraded in the next couple days. 



----------------------------------------------------------------------------------------

Exponent CMS 2.0 Theming Guide

Overview
This guide will show how to set up a theme in Exponent CMS 2.0. It covers the ins and outs of over to best interact with the system, making the most out of your Exponent project.

Parts and Pieces
An Exponent website ban be broken down in to 2 major components: themes and views. Themes (also known as Theme Variations and subthemes) comprise the main shell of the website, while views (smarty templates) display a particular module’s content.

Themes and Subthemes
Theme files are the shell if your site. The comprise of mostly HTML, but require the use of 3 php function calls, with an optional fourth. The main idea is to give a themer complete control over their layout, only plugging in in CMS functionality where needed. The 4 functions (class methods of expTheme) are:

expTheme::head(); // required
expTheme::main(); // required
expTheme::module(); // optional
expTheme::foot(); // required

expTheme:head(array)
This required function in the theme takes an array with 5 required keys, 4 of which pertain to the CSS portion Exponent’s Theming Engine. 

example of head config:

<?php 
expTheme::head(array(
	"xhtml"=>false,
	"css_primer"=>array(
    	    YUI3_PATH."cssreset/reset.css",
    	    YUI3_PATH."cssfonts/fonts.css"),
    	"css_core"=>array("common"),
    	"css_links"=>true,
    	"css_theme"=>true
        )
);
?>

expTheme::main();
A simple update of the current exponent_theme_main() syntax, bringing it to current static class method usage found throughout exp2. It’s the meet and potatoes of Exponent functionality, acting as a sectional container on 

expTheme::module(array)
A unified way to hard-code modules. expTheme::module() allows for hard coding both old-school modules, and new exp2 controllers. expTheme::module() takes 1 parameter, an array, describing what module to hard code on the page. 

Example code:

<?php
// hard coding a controller 
expTheme::module(array(
"controller"=>"links", // the name of controller (exp2 mod) to display
"action"=>"showall", // the action (class method) to run
"view"=>"showall_quicklinks",  // the view to display in
"source"=>"footer", // the source
"scope"=>"footer",  // the scope, either sectional, top-sectional, or global by default
"chrome"=>false // show or hide the chrome on this module (red chrome)
));

// hard coding an old school module
expTheme::module(array(
"module"=>"container", // name of old school module without “module” tacked on
"view"=>"Default",  // the view to display in
"source"=>"@leftcol", // the source
"scope"=>"top-sectional",  // display this container’s content on ever top-level page link
"chrome"=>false // don’t show this modules chrome
));

?>

expTheme::foot();
A simple update of the current exponent_theme_footerInfo() syntax, bringing it to current static class method usage found throughout exp2.

Actions and Views
coming soon



-------------------------------------------------------------




Exponent 2.0 Theming Engine

Overview
Exponent’s Theming Engine provides Exponent Themer’s the ability to quickly load stylesheets and javascript files on a module-by-module, loading only whats needed on a given page, and adhering to many of Yahoo's Best Practices for Speeding Up Your Web Site.

Details
It’s difficult to know which modules will be displaying on your page at any given time, you could be loading stylesheets and Javascripts on your page that aren’t needed, this increasing load times. Exponent 2.0’s Theming Engine (E2TE) solves this in a few ways. By delegating the task of loading stylesheets and Javascripts to the particular module’s views, a themer can be sure that if the module isn’t on the page, it’s not loading any stylesheets. Through using the {css} and {script} smarty plugins, external stylesheet and javascript files can be specified for inclusion, and moved to the <head> of the site. Inine styles will also be moved to the head, while inline javascript will be moved just above the closing </body> tag. 

When optional minification is enabled, all external stylesheets are minified combined in to one file, and all javascript files in to 2 files, limiting your http calls to just 3.

Lissa, an open source mashup of PHP YUI Loader and Minify, are used to accomplish the loading of YUI Javascript dependencies, and to minify both javascript and stylesheets.

The short of how it works
As the page executes, calls to various JS and CSS files are stored in php arrays. When the page is finished, and expTheme::foot() is called, parsing out the CSS and JS arrays (PHP YUI Loader handles the build of Javascript loading). At this point, we’ve either got a list of CSS and JS files, or 3 minified links to include on the page.

The last thing Exponent does before we see any content on the page is to flush the buffer. This give us one more change to execute some code via a callback function that we can execute on the buffer content (which is your page markup). The callback function simply replaces a comment placed by expTheme:head() with our links.

What E2TE accomplishes
Loads stylesheets from a view (smarty template) and moves stylesheet links to the <head> of the page automatically
supplies a directory of commonly used styles that can quickly be called throughout the system.
builds a “queue” of stylesheets files as needed on page execution to be added att the end


Stylesheets
Configuring how Exponent handles the stylesheets is done through the configuration array passed in to expTheme::head() within your theme files. The sole purpose of this configuration is to tell Exponent what style to load, and where to load them. The array takes 5 indexes, 4 of which pertain to CSS loading (css_primer, css_core, css_links, css_theme), the 5th index (xhtml) tells other parts of the system what doctype we’re dealing with, XHTML or HTML.

Execution Order
Exponent will display stylesheets first by the order in which the keys in the configuration array appear, and second be sorted alphabetically within the keys. All keys passed in the configuration array are required. It’s up to the themer to decide in which order those keys should be in.

expTheme:head(array)
This required function in the theme takes an array with 5 required keys, 4 of which pertain to Exponent’s CSS Engine.


example of head config:

<?php 
expTheme::head(array(
	"xhtml"=>false,
	"css_primer"=>array(
    	    YUI3_PATH."cssreset/reset.css",
    	    YUI3_PATH."cssfonts/fonts.css"),
    	"css_core"=>array("common"),
    	"css_links"=>true,
    	"css_theme"=>true
        )
);
?>

Configuration Array description

xhtml
Tells Exponent weather to act as an XHTML or HTML document. 

css_primer
Takes 1 of 2 values: an array of css file paths, or ‘false’. If passed an array of tiles, Exponent will load those files. This index of the config array is intended to allow themers to load stylesheets first in the CSS cascade, such as ‘reset’ stylesheets. 

css_core
Takes 1 of 3 values: true, false, or an array of common css file names. Common files are located in framework/core/assets/css/, and are files that do not pertain to any particular module, but are needed throughout the system like pagination, button, forms, tables, etc. In the example above, common is set to an array with a single value of ‘common’. This tells Exponent that on every page using this theme, include common.css from framework/core/assets/css/. 

css_links
Takes 1 of 2 values: true or false. If set to false, exponent will not pick up any stylesheets specified in view files as Exponent executes. There probably will never be a case where a themer would want to disallow linking from a theme, but the option is there. 

css_theme
Takes 1 of 2 values: true or false. When true, exponent will automatically pick up all css files within themes/yourtheme/css/

CSS Plugin
The CSS plugin serves many used to a themer at the view level. It allows for linking stylesheeets, both pushing these stylesheets to the head of the page and insertion in to the minification queue. It allows for the inclusion of core css files, It also allows for the inclusion of inline CSS to be pushed to the head of the site.

Plugin code example:

{css unique="news" link="`$asset_path`css/news.css" corecss="common,pagination"}
{literal}
.calssname {
	color:red;
}
{/literal}
{/css}

The css plugin takes 3 parameters: unique, link, and corecss. It also takes ‘content’ which is whatever is placed between the opening and closing {css} smarty tags.

unique
A unique identifier for the plugin instance. This will eliminate the potential for pulling a stylesheet in twice if there are 2 instances of a module’s view on a given page. This is also what the $css_links array sorts on when preparing for display, so naming your unique parameter offers the themer greater ability to order stylesheets.

link
takes a single file path of a local stylesheet. In the code above, the variable $asset_path is being used, which is the file path to assets directory for the particular module.

corecss
Takes a comma-separated string of file names (sans the .css extension), telling Exponent to include these files from framework/core/assets/css/.

Content between the tags
Placing styles between the opening {css} and closing {/css} tags will be moved to the head of the document. This will be displayed in the actual markup, and is the same as if you were to hard code styles right in to your HTML document, except for the fact that you css, when using the plugin, will be placed above the closing </head> tag, rather than in the actual <body>

Javascript Plugin
coming soon

My page exploded
coming soon

On Oct 3, 2010, at 4:15 PM, Bill Wilson wrote:

> I have some free time and started to do some testing with the latest 2.00 branch updates from Launchpad.  It looks like there have been some theme framework changes which have broken my custom theme (and also apparently the Coolwater Theme).  Any guidance on how to update existing themes to be compatible.  I could reverse engineer the changes but if there are any quick suggestions it could speed me on my way.
> 
> Thanks
> 
> Bill Wilson
> (617) 826-9819
> _______________________________________________
> Mailing list: https://launchpad.net/~exponent-cms
> Post to     : exponent-cms@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~exponent-cms
> More help   : https://help.launchpad.net/ListHelp