The Anatomy of a Theme

So here we are. You have installed Concrete5 onto your web server or local
machine and have everything running. The default theme for Concrete5 is
the Yogurt theme. It is nice and simple but I want to change it. How do I do
that and what sort of skill sets do I need to do this?

Well, honestly, not many. It does help that you know HTML and CSS pretty
well or at least an ability and time to learn it. Some PHP skills would be nice
as well so the few PHP tags that you need for your theme don't intimidate you
too much.

Hopefully, this paper will alleviate those fears and trepidations you may have
as you attempt and accomplish modifying or even creating your own theme.

On the Concrete5 website, there are several videos on how to take a theme or
set of templates from a statically set sight and migrate it to Concrete5. Even
though these are easy to follow they leave out some explanations the novice
may need more clarification on. So here goes.

This paper will attempt to break down the Theme process in bite size pieces.
As the more experienced developers that choose to view this will see that it is
written simplistically. You folks (devs) need to remember who this is written
for, THE NOVICE and SITE OWNERS. Not experienced developers.

There are several folders and files that will be absolutely necessary for all
themes. The novice/site owner must understand that these files are here for a
reason in each and every theme created if the theme is going work properly
on a Concrete5 enabled web site. Yes, there are ways to circumnavigate
some of these and many experienced developers have done this. I am writing
this for the NOOBS.
This list is a list of folders and files that are REQUIRED. If you have
reviewed the Concrete5 help files, you will notice that this is almost
verbatim. They are:
– elements/ (this folder is required)
– header.php (this file is required)
– footer.php (this file is required
– images/ (this folder is required. Any images used in your theme will
be located here.)
– js/ (this folder is optional. Any JavaScript files that your theme will
use should reside in this folder.)
– CSS/ (this folder is optional. Any additional CSS files that you may
want to use (such as a CSS file attached to a custom JavaScript)
should reside in this folder.)
– view.php (this file is required)
– default.php (this file is required)
– default/main/style.css (this file can be named anything you wish but
it is the main CSS file for your theme and is required.)
– thumbnail.png (this is required for the Dashboard)
– description.txt (this file is required. It is the theme description and is
used by the Dashboard to place a description in pages and themes)
– typography.css (this file is optional but highly recommended so that
all areas in Concrete5 play nice. You can edit this file to your needs
and should be included)
– left_sidebar.php (this file is optional)
– right_sidebar.php (this file is optional)

These files are what makes up a theme. There can be additional pages
created and stored here for each theme that you use. It is normally practiced
that you will NEVER modify any of the core theme files located in
yoursitename.org/concrete/themes. All themes that a user will use and
modify are located off the root of your site (ie yoursitename.org/packages or
yoursitename.org/themes).

So I have told you about the files. Big WHOOP. Now what? Now is the
time to start to understand what you can do easily and what you can't do.
The Big Easy

The easiest thing to do is modify your CSS file. This file controls where the
access of the images you want to use on your theme and how the theme will
look.

This is a short list of what your CSS file controls:

1. Background color
2. Type of font
3. Width of site
4. Column widths (if any)
5. Link colors
6. Hover colors
The list can go on and on. For every tag you have, you have attributes and
values for each one (there are A LOT). A good starting point in learning CSS
is a book by David Sawyer McFarland entitled “CSS – The missing manual”
or by going to www.w3c.org/Style/CSS to learn all there is to know about
CSS. You must understand what CSS does in order to ensure your theme will
work properly. Though if you “read” the CSS file, they are pretty intuitive if
you already have a basic understanding of HTML and CSS. Some naming
conventions are a little convoluted but you will pretty much understand them.

For each php page, it will have what are known as “DIV” tags. Each of these
div tags will have a reference of either “ID” or “CLASS” and these are
directly related to the main CSS file. Go have a look and you will see what I
mean.

There are basic HTML tags in all the theme files ending in .php. There is
also just a smidgen of php tags. So you don't have to worry about
understanding all php to get started creating your themes. As you progress in
creating a theme, you can hard code different blocks (if your choose and is
beyond this paper) that Concrete5 uses directly into your theme (see the
standard_blocks_definition.pdf for more on standard Concrete5 blocks).

Here is some example CSS from a style.css file:

“
/* Overall body styles. This is just the main widths and background colors
that you want. For H tags...see typography.css*/

html {
height: 100%;
}

body {
height: 100%;
width: 100%;
color: #ff7f50;
text-align: center;
background: #98fb98 url(images/background.png) no-repeat top;

/* Wrapper Div Tag. Change this for the color of your background in the
main content areas. */

#wrapper {
background: white;
margin: 0 auto;
width: 800px;
text-align: left;

}
“

As you can see, the html tags are in black. The brownish colored items are
attributes and the pink or green are values for that attribute.

Many of the tags you will see refer to exactly what CSS is created to do. Put
certain STYLES to certain HTML tags. As you progress in your CSS
knowledge, you will see that good naming conventions will be a great asset.
You will making quite a few DIV references in your themes and you will
need to assign easy to follow ID or Class names such as “Wrapper”. In many
cases with Concrete5, you will see “wrapper” as one of your top styles. It is
implemented so that your styles will not conflict. This may still occur but
ensures that YOUR styles don't conflict with Concrete5's styles. Think of the
wrapper style as your main wrapping paper for your theme.

As you can tell by now, your CSS file is what really sets your theme apart
from just plain HTML and plain PHP. It is what makes your theme yours.
You can take a pre-existing theme and essentially modify it so much that it
doesn't even look like what you started with. Having said that, it is good
FORM that you give credit where credit is due. If you use someone's theme
or style as a starting point, reference it in your comments of the CSS file.

The NOT so easy

In the following paragraphs, I will start to explain what it means to put a

theme together. It will also introduce those folks that don't have a clue about
PHP and what it means to them as they design their theme. As stated
elsewhere, you don't need to be a PHP wizard to create your theme(s). You
do however, need to know WHAT PHP you need in your theme to make it
work. Luckily, all you will need to do is cut and paste from a reference
theme and it should work. Franz and Andrew and the core team have made it
very easy to create and modify themes. Some of the naming conventions
may be a little intimidating at first, but then it will almost become second
nature to you as you create more themes.

So where do we start. As mentioned above, there are certain files THAT

MUST BE IN YOUR THEME. Don't try and get fancy and do things your
own way. Ok, that is a little far fetched but there are a few files that
absolutely MUST be in your theme folder. If you don't have a view.php or
default.php file you probably won't get far in your theme development. A
page or two may work but then, Concrete5 will start to look for “view.php”
or “default.php” and won't find it/them and throw a CANNOT FIND PAGE
error. You will then start looking like me and have little hair on top of your
head. I did this the first few times and couldn't understand what I had done
wrong. A more experienced Concrete5 user told me why (in very direct
terms) you must have view.php and default.php. Once that sunk into my
thick skull, I could essentially create a new theme in minutes. This does not
mean I can do graphics by the way. That topic is WAY BEYOND this paper.

The other file you must have is your CSS file or all that color and bling you
want won't happen. Oh, did I mention, if you want your nifty header and
footer information that you spent hours contemplating and creating to show
up properly, you will need those folders and files too. Sounds condescending
doesn't it. Well, sorry. Concrete5 looks for those files from some of the core
files. If they aren't there, a possible error will be displayed.

Before you start getting into all the code, I would make sure that you have
created or copied all the required files into one neat folder (known as the
theme folder). Then all your fun files will be handy and easy to get too.

So lets start exploring those somewhat daunting (for non-php peeps) files
with that .php extension. We will start with the “header.php” file located in
the elements folder. Here is what it looks like in its entirety. Don't go
screaming when you see it :)
<?php defined('C5_EXECUTE') or die(_("Access Denied.")); ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="verify-v1" content="CfzSg5VnpG5hCdDgT0dKMmPn3l5tIGvCfvemOSnGNdo=" />
<!-- Site Header Content //-->
<style type="text/css">@import "<?php echo $this->getThemePath()?>/style.css";</style>
<?php Loader::element('header_required'); ?>
</head>
<body>
<!-- header starts-->
<div id="wrapper">
<div class="header">
<div id="toplinks">
<div id="toplinks_inner">
<?php
$a = new Area('Toplinks');
$a->display($c);
?>
</div>
</div>
<div class="clearer">&nbsp;</div>
<div class="right">
<?php
$ah = new Area('Header Right');
$ah->display($c);
?>
</div>
</div>

Don't worry, it isn't as bad as it looks. Line 1 (your first php line) is looking
for Concrete5. If it doesn't find it and the associated files, it throws and error
and wont execute. The next few lines you should be familiar with. They are
normal “Head” tags for an HTML file. You will then notice and include line.
This is looking for your CSS file. If you have gone through the helps
sections on Concrete5.org, you will notice some php code in several of these
standard HTML lines. These allow your theme to communicate with the core
of Concrete5. They have to be there or your site won't operate correctly.
Notice all the div tags. This is grabbing information from your CSS file and
making the page look how you have envisioned your site looking. You will
also notice some additional php tags. These php tags are creating those
handy dandy editable areas when you go into edit mode via the dashboard.
Next, I will show the code for a typical view.php file.

<?php
defined('C5_EXECUTE') or die(_("Access Denied."));
$this->inc('elements/header.php'); ?>

<div>
<div class="fullcolumn">
<?php
print $innerContent;
?>
</div>
</div>

<?php $this->inc('elements/footer.php'); ?>

Nothing really crazy going on here. The file is opened and looks that
Concrete5 is available and executes correctly if it is. Next, it looks for your
header.php file. If it finds it, it will continue. It sets the page up for content.
It sees that it is a full width page (hence the class=”fullcolumn”) and prints
whats ever block you have placed there via the dashboard. Then it closes the
FULLCOLUMN and looks for the footer.php file. Then it stops printing
information to the browser.

WOW! That is not hard to understand and all I have to do is make sure that
file is in my theme!!! WOO OOO!!!!!!

Getting a little more bold we will look at a left_sidebar.php file. All this file
is doing is setting the content areas you want on the page to display in TWO
columns. The more narrow column being to the left of the page. Here it is.

<?php
defined('C5_EXECUTE') or die(_("Access Denied."));
$this->inc('elements/header.php'); ?>
<div id="main">
<div id="left">
<?php
$as = new Area('sidebar');
$as->display($c);
?>
</div>
 <div id="right">
<?php
$a = new Area('main');
$a->display($c);
?>
</div>
<div class="clearer"><span></span></div>
</div>
<?php $this->inc('elements/footer.php'); ?>

Almost the same as the view.php. Just additional php code identifying that
you want columns and the names of your new areas. It really isn't hard to do.

Ok the last file I will show you is the footer.php. Here it is.

<?php defined('C5_EXECUTE') or die(_("Access Denied.")); ?>

<!-- Bottom Navigation starts here-->
<div id="navigation">
<div class="center_wrapper">
<?php
$a = new Area('Header Nav');
$a->display($c);
?>
<div class="clearer">&nbsp;</div>

</div>
</div>

<!-- footer starts here -->

<div id="footer-wrapper">
<div id="footer">
<div id="navigation">
<?php
$as = new Area('footer');
$as->display($c);
?>
</div>
</div>

<div id="footer-bottom">
<p class="bottom-left">&copy; <?php echo date('Y')?> <a href="<?php echo DIR_REL?>/"><?php
echo SITE?></a>.
&nbsp;&nbsp;
<?php echo t('All rights reserved.')?>&nbsp;
<a href="<?php echo DIR_REL?>/">Home</a> |
<a href="<?php echo $this->url('/login')?>"><?php echo t('Sign In')?></a> </p>
<p class="bottom-right" >
 <p class="bottom-right" >
<a href="http://www.facebook.com/">
<img src="http://www.yourdomainname.org/themes/yourtheme/images/facebook.png" width="30"
height="30" border="0" alt="Facebook" /> | </a>
<a href="http://www.twitter.com/">
<img src="http://www.yourdomainname.org/themes/yourtheme/images/twitter.png" width="30"
height="30" border="0" alt="Tweet" /></a>
</p>
<!-- End Footer-Bottom -->
</div>
</div>
<!-- footer ends here -->
</div><!-- page-wrap ends -->
</body>
</html>

The code is the same sort of thing but with some more HTML thrown in.
Nothing cosmic!!!

This is the basics of creating your theme. Admittedly there are other things
you may need to learn but visit the forums and/or IRC channel to ask more if
you need too.

Graphics are time consuming to create. Remember that they must be small in
file size but should be WOW to the site visitor. If you have a graphics person
to do them for you, congratulations. If you don't, expect spending more time
on creating your graphics then you will on creating your THEME !!!!!

Have fun and email me if you have questions and I will try and answer them.
Look for my profile on Concrete5.org (bcarone) or email me direct at
bcarone@carolinageek.com.