Concrete5 Sandbox Theme Tutorial

Warning! This tutorial is for deprecated Concrete5 versions 5.6 and below. Many of the examples and methods are no longer relevant to modern Concrete5.

This multi-part tutorial will take you through the steps I used to create the simple C5 Sandbox theme. This detailed tutorial will take you from the planning and setup through the HTML and CSS coding required to build a simple Concrete5 Theme.

In this, Part 1, or our Concrete5 custom theme tutorial we will begin identifying the concept for our brand new theme and setup our theme infrastructure by copying an existing theme directory tree.

This is more of a stream of consciousness tutorial, so we are going to start out with pretty broad ideas and then refine them as we go along. It's also important to note that I am not going to be building a Photoshop mockup and then convert that to a theme, although most professional designs would be achieved this way. This tutorial is meant for your average joe site owner to get something completely custom off the ground.

Step 1. Get familiar with an image editing program

In order to do any kind of custom theming you are going to need a rudimentary understanding of an image editing program. The key features of a program like this should be layer support., transparency, and drawing tools. Adobe Photoshop is by far the most popular program of this type, but you don't have to shell out any money to get into the game. One neat clone is available right in your web browser, its called Pixlr and has a lot of the same features as Photoshop. There is also the more traditional GIMP, and Paint.NET.

Step 2. Determine the theme of your theme

This is obviously a pretty broad step for each and every theme you build, so I will take the space to simply describe what I have in mind. Attached to this website I have whats known as a Concrete5 Sandbox. This is a website setup so that anyone can log in as administrator and explore the Concrete5 system. I want to take this sandbox terminology literally and create a theme based on the beach. I want a nice repeating sand background texture and I want my content to lay out in the sun on a beach towel.

Step 3. Copy the default theme

I have found that the most efficient way of building a Concrete5 Theme is by taking a copy of the "default" concrete5 theme and editing it. To do this you will need to access your file structure through either your web hosts file manager utility or FTP. copy the concrete/themes/default directory into the themes/ directory. Now navigate to your themes/default directory and rename it to "sandbox".

Step 4. Strip down your sandbox directory

Now that we have the default theme renamed, I want to go ahead and remove everything but the bare essentials. Delete everything out of the sandbox directory except for the following:

  • Elements directory
  • default.php
  • description.txt
  • main.css
  • typography.css

Step 5. Make some basic changes

Open up the description.txt file. This file tells Concrete5 what to print when listing your theme. I changed mine to look like this:


Custom Sandbox

This is the Custom Sandbox theme created at concrete5tutorials.com


Save the description.txt file and the open up the main.css file. Delete everything in the "/* Page Structure / Navigation */" section. These are CSS rules used in the default theme that we will rewrite for our own theme. Save this file as well.

Now go into your elements/ folder and open the header.php file. These header and footer files are not a requirement, but they do make things a bit easier when developing mulitple page types like left_column, right_column, full, etc. When you bring in the header and footer from an external file that means you can make a single change here and that will propgate across all of your various page_types. Lets say christmas is coming and you want to hardcode a snowman at the bottom of your site, instead of having to go into each page_type template and adding it, you add it here and forget it, at least until april or so..

Back to the header.phpfile. Let so ahead and delete everything below the "

" around line 15. Basically, we are going to let our header setup theandopening tags, as well as open up our main container the page div. Let's remember that, because we are going to want to make sure we close all those tags in the footer.php file. Here is what my edited header.php looks like.


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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<!-- Site Header Content //-->

<link rel="stylesheet" media="screen" type="text/css" href="<?php echo $this->getStyleSheet('main.css')?>" />

<link rel="stylesheet" media="screen" type="text/css" href="<?php echo $this->getStyleSheet('typography.css')?>" />

<?php Loader::element('header_required'); ?>

</head>

<body>

<div id="page">


Now open the footer.php file. Here are the contents.


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

<div id="footer">

© <?php echo date('Y')?> <a href="<?php echo DIR_REL?>/"><?php echo SITE?></a>.

<?php echo t('All rights reserved.')?>

<?php

$u = new User();

if ($u->isRegistered()) { ?>

<?php

if (Config::get("ENABLE_USER_PROFILES")) {

$userName = '<a href="' . $this->url('/profile') . '">' . $u->getUserName() . '</a>';

} else {

$userName = $u->getUserName();

}

?>

<span class="sign-in"><?php echo t('Currently logged in as <b>%s</b>.', $userName)?> <a href="<?php echo $this->url('/login', 'logout')?>"><?php echo t('Sign Out')?></a></span>

<?php } else { ?>

<span class="sign-in"><a href="<?php echo $this->url('/login')?>"><?php echo t('Sign In to Edit this Site')?></a></span>

<?php } ?>

</div>

</div>

<?php Loader::element('footer_required'); ?>

</body>

</html>


You can see that on line 2 we open up a "footer" div and the proceed to fill that with a lot of various credits and user code. I like to leave the footer in tact at this point of development. We will probably go back in here and make some changes later, but now I can see that on line 24 my "page" div is closed up and at the end my body and html tags are closed, so all of our bases are covered.

Finally, lets go back out to the main themes/sandbox directory and take a look at the default.php file. This file is used to display a concrete5 page if no other page_type has been selected. It's the only mandatory page_type. Open it up and see if you can tell what it does. Here are the contents of my unedited default.php file:


<?php

defined('C5_EXECUTE') or die("Access Denied.");

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

<div id="central">

<div id="sidebar">

<?php

$as = new Area('Sidebar');

$as->display($c);

?>

</div>

<div id="body">

<?php

$a = new Area('Main');

$a->display($c);

?>

</div>

<div class="spacer"> </div>

</div>

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


Line 3 imports all the code we left in the header.php file, line 24 imports everything from the footer.php file, and everything in between is used to render anything that you have put onto that Concrete5 page. Since we are going to start from scratch lets delete everything from between those two lines except for the following:


<?php

$a = new Area('Main');

$a->display($c);

?>



Step 6. Install your new theme

It helps to be able to check your work while you build a theme, so we are going to go ahead and install our sandbox theme now. At this point the theme is completely useless because we deleted all the code that would show us any of the content, but lets make sure it will install. Log in to your website and access the "Pages and Themes" tab of your dashboard. At the bottom of the Theme list you should see your new custom theme in the "Themes available to install" area.

Hit the "Install" button, and if all is well you will be shown a confirmation screen. When that is done return to the "Themes" page. Now scroll down to your "Sandbox" theme and "Activate" it. Now if you go and view your website you should see a pretty basic and ugly representation of your page.

In the next section we will begin gathering the design resources and building our HTML and CSS.

Part2: Gathering your Design Elements

December 14th, 2010

In Part 1 of this tutorial series we set up the files required to build our custom Concrete5 theme, and made sure we were familiar with an image editing program. In this segment we will gather up the design elements required to execute our vision.

Step 1. Determine what Patterns you need

When designing websites I generally have at least one, if not more, seamless image patterns built into the design. These are typically required for the background image, because we are never sure what resolution monitor our users will be visiting with, and we don't want any odd stops or starts to the background.

In the case of our simple sandbox theme I can think of at least two seamless patterns I am going to need to find. For the background I want a nice beach sand texture, and on the foreground I want a seamless beach towel texture.

What I am thinking is that the header will be in the sand above the towel, the main content will be on the towel, and the footer will be back in the sand below the towel. Because we are never going to be certain how tall our content (towel) area is going to be, that will need to be vertically seamless as well.

Why only vertically? I like to create most of my websites with a fixed width. It gives me better control of the "look" of the content than a fluid layout which changes width depending on the browser window. I choose to design my websites at a maximum width of 960 pixels. I choose this number because it is easily divisible when creating columns, and it fits perfectly for users with the 1024x768 monitor resolution.

I would like to maintain dark colored text over a lighter background, so we will need to keep that in mind when we search for our towel texture.

click image to enlarge

click image to enlarge

Step 2. Find / Create your textures

There are a couple of different ways we can go about finding textures for our sandbox theme. I want to keep everything free and reusable, so I visited a Free Stock Photography Website and did a search for "Sand Texture" and "Towel". You can find textures like these all over the web, but it helps when no attribution is required. I ended up downloading two textures from the aforementioned website, and then editing them in Pixlr to make them seamless. This is pretty easy in Photoshop and described here. In Pixlr, I had to do a bit more work because the program doesnt have an "offset" filter, but the rest was the same, I just cloned over the seam. You can just download the textures on the right and save yourself a little work for now.

Step 3. Get ready to code your CSS

I put this step in here because I wanted to familiarize you with my greatest design tool. Its called Firebug and it is a plugin for the mozilla firefox browser. This plugin allows you to view and adjust CSS rules in real-time (among other things) and is indispensable for the next phase of our theme development. If you don't have it already go download it and familiarize yourself with its CSS features.

In the next segment we will begin writing the html and CSS code to build the basic structure of our theme.

Part 3: Building the Basic Structure

In part 1 and part 2 of this tutorial series we began by copying and stripping down a default concrete theme and then gathering the image resources required to build the basic structure of our new sandbox theme. In the segment we will start coding the HTML and CSS for the basic page structure to include elements that are likely to remain the same over several different page_types.

Step 1. Fill in the background

In the last step we created our nice seamless sand texture that will fill in the background behind our theme. Lets apply that image file to our theme now.

First, lets create a new folder within our theme directory themes/sandbox/images . This images directory will hold elements of our theme design that are put into place by the CSS file. Upload the sand_texture.jpg and the towel_texture.jpg files to this directory now.

Now go up one directory into the main themes/sandbox directory and open up the main.cssfile. This file holds the majority of your sitewide CSS rules and is where we will begin our coding.

In order to define our background image lets create a rule for the html body tag. We are going to use the CSS background rule to fill the page with our repeated sand texture.

The existing rule set for the HTML body tag should already be defined in your main.css file right near the top. Mine currently looks like this:

body {/* customize_background */ background-color: #ffffff; /* customize_background */ padding: 0px; margin: 0px; }

This line currently defines the background color (making it adjustable from the concrete5 UI) and sets padding and margin rules.

I'm going to split the rule out into its three parts and setup the background woth a color, image, and repeat property. Here is my completed body CSS rule.

body {
	background:#C4B084 url(images/sand_texture.jpg) repeat; 
	padding: 0px; 
	margin: 0px;
}

I changed the background image from #ffffff to #C4B084 a brown color, similar to the sand in our background image, and removed the Concrete5 UI adjustment. I gave the url of the imagewe uploaded, and made sure it was relative to the location of the main.css file. Finally, I set the image to repeat, which tiles it vertically and horizontally.

Save the main.css file and go take a look at your theme. You should see the sand texture in the background with some nearly unreadable text floating over it. We will get all that content contained onto our towel in the next step.

Step 2. Define the main Content Container

Now that we have the background sorted out, lets go ahead and build our main content container. If you remember from part 1, we left a div with the id of"page" in the head and footer elements. Lets open up our main.css file again and define some CSS rules for that div.

In the "Page Structure" section of the file add the following CSS rule for the #page ID.

  1. #page {
  2. width: 960px;
  3. margin: 0 auto;
  4. }

This new rule constrain all of the content on the page to 960 pixels in width. The margin: 0 auto rule centers the div on the page.

Step 3. Setup the Header

Next we will set up a customizable header area that will float above the beach towel. To do this, we need to create a new div within the #page div. I figure every page on the website will have this header area, so lets embed it in the themes/sandbox/elements/header.php file. Open this file and add the following HTML/PHP code at the bottom.

	<div id="header">
		<?php
		$a = new Area('Header');
		$a->display($c);
		?>
	</div>

This code creates a new div with an ID of "header" and the populates it with a Concrete5 editable area also called "Header". Now that we have the div built into the page structure, we need to style the way it looks with CSS. Open up the main.css file again and add the following below the #page rules.

#header {
	padding: 15px 0 0 0;
}

This code puts 15 pixels of padding inside the top of the new #header div which keeps any elements from bumping up against the top of the browser window.

Step 4. Building the content area

Now lets work on building up the main content area. To make the content area look more like a towel we are going to end up putting two nested divs around the content area. The outermost div will be our full 960 pixels wide and will represent the towel edge. The inner div will be 10 pixels inside that edge div have the towel texture repeating in the background. Because every page_type will have this same structure we are going to open the new HTML in the header.php file and close it in the footer.php file. At the bottom of the header.php file add the following.

	<div id="towel_edge" class="drop_shadow">
		<div id="content_area" class="inner_shadow">

Now open up the footer.php file and close those two divs by adding the following to the top of the file.

		</div>
	</div>

Now let's style our two new elements. Open the main.css file and add the following rules.

#towel_edge {
	width: 960px;
	background: #9eb6b9;
	padding: 10px;
}
 
#content_area {
	width: 940px;
	background:#abcdd1 url(images/towel_texture.jpg) repeat;
	padding: 10px;
}
 
.drop_shadow {
	-moz-box-shadow: 0px 0px 8px #000;
	-webkit-box-shadow: 0px 0px 8px #000;
	box-shadow: 0px 0px 8px #000;
	/* For IE 8 */
	-ms-filter: "progid:DXImageTransform.Microsoft.Shadow(Strength=4, Direction=135, Color='#000000')";
	/* For IE 5.5 - 7 */
	filter: progid:DXImageTransform.Microsoft.Shadow(Strength=4, Direction=135, Color='#000000');
}
 
.inner_shadow {
	-moz-box-shadow: 0px 0px 2px #628399;
	-webkit-box-shadow: 0px 0px 2px #628399;
	box-shadow: 0px 0px 2px #628399;
	-ms-filter: "progid:DXImageTransform.Microsoft.Shadow(Strength=2, Direction=315, Color='#628399')";
	/* For IE 5.5 - 7 */
	filter: progid:DXImageTransform.Microsoft.Shadow(Strength=2, Direction=315, Color='#628399');
}

While the CSS looks a bit complicated, it's pretty straight forward. The first two ID rules simply setup the placement of the towel. The two class rules setup a neat shadow effect that should give the towel some depth and realism. Take a look at your website and you will see that we have made some progress. There is one glaring problem though. On my website, the text is a light grey and is getting washed out by the towel. Wel will change that up in the next step.

Step 5. Editing the typography.css file

There are two main files that dictate your themes appearance. Most of your rules will go into the main.css file, but some select rules should be placed in the typography.css file. Both CSS files are used when a page renders, but any rules in the typography.css file are also visible from within the WYSIWYG editor. Its advisable that all your general text rules be set here, so the user get a beeter idea of what the text will look like when it is applied to the website. Open up the themes/sandbox/typography.css file, we will start by changing the default color and size of the text. This is defined in the body tag.

body { 
	/* customize_body */ font: normal normal 18px Arial; /* customize_body */
	/* customize_body */ color: #000; /* customize_body */
	line-height:18px;
}

In the above lines I increased the default font size to 18 pixels, and the default color to #000 (black). Lets change the default colors for hyperlinked text as well.

a,a:visited,a:active {
	/* customize_link */ color: #1F1B94; /* customize_link */
}
a:hover {
	/* customize_link_hover */ color: #3A34E3; /* customize_link_hover */
} 
 

I edited the anchor states to display a dark blue color normally, and then a brighter blue on rollover. Because I left the /* customize */ code in place these attributes will still be editable within the Conctrete5 UI.

Step 6. Adding some rules for the footer

Back in Step 1 we left the default footer in tact, but what you probably notice now that the text runs up too close to the main content area. Lets open up the main.css file again, this time we will create some rules for the #footer div.

#footer {
margin-top: 25px;
}

I also like to have an editable area in my footer because I generally put some navigation elements in there. To add that area we will need to go into thethemes/sandbox/elements/footer.php file and add the following within the #footer div.

<?php
$a = new Area('Footer');
$a->display($c);
?>

I put this code directly after the openeing <div id="footer"> tag. That way it shows up above the credits and login info.

That's it for this long tutorial segment on creating your own Concrete5 Theme. In the next part we will create a few different page types to be used with our theme.

Part 4: Creating Page Types


In part 1, part 2, and part 3 of this Concrete5 Theme Tutorial we built our header and footer framework and added our basic background graphics. In this segment we will create some essential page types that users typically expect with a theme.

Step 1. Create the full.php layout

Our first layout will be a simple copy of the default.php we have already created. This is a simple single column layout with a single editable area named "Main". Make a copy of thedefault.php and rename it full.php.

Step 2. Create the left_sidebar.php page type

Our next page type will be left_sidebar.php. This layout will require some additional structure and CSS rules. The left_sidebar page type will feature a narrow column on the left side of the page with an editable area names "Sidebar", and then the balance of the page will belong to the "Main" content area. Here are the contents of my new left_sidebar.php file.

<?php 
defined('C5_EXECUTE') or die("Access Denied.");
$this->inc('elements/header.php'); ?>
 
<div id="right_main">
	<?php
	$a = new Area('Main');
	$a->display($c);
	?>
</div>
 
<div id="left_sidebar">
	<?php
	$a = new Area('Sidebar');
	$a->display($c);
	?>
</div>
 
<?php  $this->inc('elements/footer.php'); ?>

In the main.css file I added these new rules.

#left_sidebar {
	float:left;
	width: 180px;
	margin-right: 20px;
}
 
#right_main {
	float:right;
	width: 740px;
}

The above structure and formatting creates a layout with two columns with a 20 pixel space between them. If you were to upload and activate this page type now you would find that your content overflows the towel area. This crops up when you start floating divs within containers. The fix for this is to add yet another div with the clear:both rule applied. Let's do that in our footer.php file. Save the following line in your themes/sandbox/elements/footer.php file, just before the closing tags for the two divs at the very top of the file.

<div class="spacer"></div>

This code creates an empty div with the class name "spacer" which happens to already be declared in my main.css file. You may want to check your main.css file for the following line towards the bottom. If you don't have it, add it.

div.spacer,div.ccm-spacer{ clear:both; font-size:1px; line-height:1px }

Step 3. Create the right_sidebar.php file

The next page type will be the same as the last, just with the sidebar on the otherside of the page. Most of the structure will be identical with the exception of the id names. Copy all the content from your left_sidebar.php file into a new right_sidebar.php file. Then simply swap the left and right names.

<?php 
defined('C5_EXECUTE') or die("Access Denied.");
$this->inc('elements/header.php'); ?>
 
<div id="left_main">
	<?php
	$a = new Area('Main');
	$a->display($c);
	?>
</div>
 
<div id="right_sidebar">
	<?php
	$a = new Area('Sidebar');
	$a->display($c);
	?>
</div>
 
<?php  $this->inc('elements/footer.php'); ?>

Next we add a couple of more rules to the main.css file.

#right_sidebar {
	float:right;
	width: 180px;
	margin-left: 20px;
}
 
#left_main {
	float:right;
	width: 740px;
}

That should do it. Now you have a a left and right sidebar page type.

Step 4. Create the view.php file

Our last page type is not really a page type at all. It is called view.php and it is the skin that wraps any single pages you create on your website. I like to create this file from the default.php file. Create a new file called view.php. Copy the contents of the default.php file into your new file and replace the php code that renders the "Main" area with the following:

			<?php>
			print $innerContent;
			?>

Step 5. Install your new Page Types

Now that we have created and uploaded your new page types to the themes/sandbox directory we need to tell Concrete5 that they exist. Login to your website as administrator and navigate over to the "Pages and Themes" area. Here, click into the "Page Types" tab.

This page shows you the currently installed page types. On my development site I show only one page type in this list "Left Sidebar". This means we need to tell Concrete5 about our full.php page type and our right_sidebar.php page type.

Click the "Add a Page Type" button and name the new page type "Right Sidebar". The Handle needs to match the pages file name without the extension. In this case "right_sidebar"

Next up select an icon that reflects the layout of the page type we are adding. In this casse the second from the left looks correct. If you wind up building your own custom page types you can add additional icons to this list.

Finally select your page types default attributes. The attributes you select here will be available within the page properties without the user having to manually add them. I typically add "Meta Title" for Search Engine Optimization reasons.

Finally click the "Add Page Type" button to finish things up. Do the same for the "Full" page type.

Once complete, you should be able to add new pages to your website using all of the page types you have created.

This completes the "Theme" portion of our Concrete5 Sandbox Theme Tutorial. If you were to apply the theme to your website now it would be pretty unimpressive. Thats because vital elements like the header and navigation are non existant. I feel these important elements are mcuh more versatile when placed within page type defaults. We will start setting those up next.