Converting an Artisteer Theme to Yii

You are viewing revision #1 of this wiki article.
This is the latest version of this article.

There are two approaches to converting an Artisteer theme. The first is to simply copy an existing Artisteer – based Yii theme, overlay the CSS and images, then make any necessary tweaks to the layout files. This is undoubtedly the fastest route, but won't teach you as much as doing it from scratch. That's ok. Sometimes getting the job done is the top priority. The second approach is more general and will apply to some extent to other HTML templates that you may want to convert. I'll be covering the first approach in detail, while the second will be more of a general discussion.

Artisteer vs Yii

Artisteer can be used to generate themes for Drupal, Joomla, and other CMSes. It can also generate HTML templates. It is the HTML template that can be converted to an Artisteer theme.

Artisteer files:
page.html
style.css
style.ie6.css
style.ie7.css
script.js
images	 (subdirectory)

Yii theme files:
theme_name (directory)
	css (subdirectory)
		<contains various css files, possibly image files>
	views (subdirectory)
		layouts (subdirectory)
			main.php
			column1.php
			column2.php
			...
		site (subdirectory)
			index.php
		system (subdirectory)

The Artisteer files are straightforward. You have a set of stylesheets (i.e. CSS files) and images to support them. You also have a file called page.html. Page.html demonstrates the use of the various styles supported by the template. For example, you'll see the H1 tag, how links are styled, and the default format for HTML tables. You'll also see Artisteer specific classes demonstrated. I will revisit this file in more detail when I cover the second approach.

The Yii theme files are a little more involved. The css subdirectory is obvious. In many ways, CSS is like a structural foundation. The views, then, are the walls and the doors, the windows and the floors that complete the theme. Layouts are those special views that define the header, the footer, and column layouts. (see the Yii Definitive Guide for more info)

Approach #1: Fast and Furious

So, you've generated an Artisteer theme that you like and exported it as an HTML template. Or you've downloaded one of the freebies online. Step 1: Download a copy of one of the Artisteer – based themes from http://yiithemes.mehesz.net/

  If possible, find one that is structured close to the one that you want to convert.  For example, if your menu position is below the header, you'll do less editing if the theme you download as a starting point already matches.  Install the theme according to the instructions.  When you're sure the theme works, move on to the next step.

Step 2: Make a copy of the working theme from Step 1 and give it a new name.

Step 3: Remove the css/images subdirectory from the new theme

Step 4: Copy the Artisteer files from the generated HTML template into the css directory.

  Overwrite any files with matching names.  Note: form.css is from the standard Yii install.  Artisteer does not provide forms CSS in their generated template.

Step 5: Set 'theme'=>'yournewtheme' in the main.php config file and tweak!

  Basically, go to the home page of your webapp (something like http://localhost/myapp/).  You should see a one column display very similar to what you get if you view page.html.  This page is generated from yourtheme/views/site/index.php (it will say so on the screen).  When present in your theme, this file takes precedence over your webapp's site/index.php.  
Compare the browser display (i.e. http://localhost/myapp/) with an open window/tab of page.html.  If the menu, for example, is in the wrong location, viewing the HTML source for both web pages and noting the differences will help you alter the various layout files.  In particular, note which DIV tags are nested within others and which blocks of tags follow each other.  You might even be missing a set of tags if a header is included in one theme, but not in another.  
If you need the column2.php layout (or others of your own design), you'll need to setup a test to use it.  There is dummy info included in the column2.php layout to further demonstrate use of Artisteer CSS classes.
Second Approach: More General

A more general approach to converting HTML templates to Yii themes can be summed up in the following steps:

Step 1: Find a theme/template you like and download it.

Step 2: Find the “demo” page that shows the various CSS styles and formatting. Page.html, index.html, etc. and view the source.

Step 3: Copy the header into a new text file. This will become your main.php file in the layout subdirectory. Replace any references to files on the filesystem with paths that take into account the location of the theme. For example,

<script type="text/javascript" src="<?php echo Yii::app()->theme->baseUrl; ?>/css/script.js"></script>

Step 4: Examine the source and figure out where to separate the HTML that should be the rest of main.php and what would go into a single column display (i.e. column1.php). Note: Upon execution, column1.php gets inserted into main.php replacing the placeholder variable $content. (Examine any existing theme to get an idea of how this works.) You have to understand how layouts work and the resulting HTML before you can successfully look at a file and know where to separate. Of course, you can always try something and if it isn't quite right, adjust it.

Step 5: Create other layouts as needed.

Final Thoughts

That covers converting Artisteer themes and in general, other HTML templates. This document does not pretend to cover every detail of every step, but if you take the time to look at HTML source, existing themes, and this guide, you'll be well on your way to converting your own themes.