How to convert a static HTML template into a concrete5 theme

I recently volunteered to be a part of my church’s website ministry. When I learned that we would be creating a new website using concrete5, I was not excited. I’ve used WordPress quite a bit, I’ve dabbled in Drupal, and I’ve experimented with a handful of other CMS’s. When given a choice, however, I almost always end up creating my own CMS for all of my projects. It’s not because other CMS’s aren’t great products, but I usually need more flexibility than they offer without the learning curve that they often present.

After working with concrete5 for a few days, it’s clear to me that this is the CMS I’ll be using for all of my future projects. With little more than a basic understanding of PHP, it’s incredibly easy to convert any HTML template into a concrete5 theme. Most of this process is explained very well in Andrew Embler’s excellent tutorial. There are a few steps he left out that I found were necessary to get everything working properly, so I’ll explain those here.

The first thing Andrew points out is that you need a description.txt file and a thumbnail.png file in your theme directory. Then you need to prefix all relative paths in your HTML template, which should be named default.php, with the following PHP statement:

<?php echo $this->getThemePath(); ?>

Next, he tells you that you need to replace the title in the head of your default.php file with this:

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

I found that this statement had to be placed in the head after my .css files had been added but before my .js files had been added. This is because the concrete5 toolbar includes a copy of the jQuery script, which needs to be loaded once – and only once – in order for some jQuery plugins to function correctly. Any .js files that are dependant on jQuery need to be loaded after that.

Then he points out that to make a content area editable you need to replace the HTML contents with this:

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

You can replace “Main” with any other string. Each content area must be named something different, so if you want two areas named “Main,” the second one must be named “Main2” or something like that.

If you’re already signed in at this point, or if you know the URL to your sign in page, this is all you really need to do. However, I wanted an easier way for myself and the other web administrators to sign in. I found this code in another concrete5 theme that I downloaded, which I then placed in the footer area of my default.php file:

<?php 
// Don't remove the stuff below - it's needed for sign in
$u = new User();
if ($u->isRegistered()) {
?>
<p>
	Currently logged in as <?php echo $u->getUserName(); ?>
</p>
<p>
	<a href="<?php echo $this->url('/login', 'logout'); ?>">Sign out</a>
</p>
<?php } else { ?>
<p>
	<a href="<?php echo $this->url('/login'); ?>">Sign in</a>
</p>
<?php } ?>

Let’s break this code down: If a user is currently signed in, the page will display the text “Currently logged in as” followed by the user’s name and a “Sign out” link. If a user is not signed in, the page will display a “Sign in” link.

The next thing I noticed was the concrete5 toolbar was blocking some of the content at the top of my page. I needed to shift everything on the page down by 53 pixels to make room for the toolbar, but only when a user is signed in, so I placed the following code just inside of the body tag of my default.php file:

<?php 
// If a user is signed in, shift everything on the page down by 53px to make room for the toolbar
$u = new User();
if ($u->isRegistered()) {
?>
<div style="min-height: 53px"></div>
<?php } ?>

At first, the need to do this baffled me. When the toolbar is loaded, it applies a margin-top property to the body tag of the page, which should shift everything on the page down anyways. Later, I figured out that I needed to wrap everything on the page in a div container, and that I could give this container a padding-top property and eliminate the need for the code above. However, the reason I needed to wrap everything like this was because my stylesheets weren’t playing nicely with the toolbar. This is explained on this page of the concrete5 site:

When converting existing themes to use with concrete5, a lot of the free css templates out there tend to add some pretty greedy style properties to standard elements (like padding or margins on all li or div tags for example).

This causes some major issues with the way stuff in the concrete toolbar and popups are rendered. An easy way to fix this is to wrap the template markup with a DIV with an ID of page or “wrap” just inside the BODY tag.

Then in your main.css and typography css, prepend the #page or #wrap to each css rule, to limit its scope.

There’s one more thing I should mention. On my HTML template, I have a number of content areas that are hidden via a jQuery script when the page loads and unfold when a user clicks on them. This presented a problem with concrete5, which wouldn’t allow me to edit the contents of these areas in edit mode. Thankfully, I had written my jQuery script to allow for graceful degradation, so if a user didn’t have JavaScript enabled in their browser, they would still be able to access these areas of the page.

The fix for this problem was wrapping an if statement around the lines where my .js files were loaded inside the head of my default.php file:

<?php
// If a user is in edit mode, remove this jQuery script so they can edit text inside hidden divs
if (!$c->isEditMode()) {
?>
<script src="<?php echo $this->getThemePath(); ?>/js/script.js"></script>
<?php } ?>

Considering that this step was the most frustrating of the whole process, converting my static HTML template into a concete5 theme was remarkably simple. The thing I like most about this CMS is that it’s really intuitive for any other administrator of the site to edit the content on the page. There is no need to navigate around an administrator interface to find the content to be edited just to change the text on the page.

Let me know if you have any questions or if this tutorial helped you in any way!

EDIT 2/13/2012: As of a February 2012 update, the following code is required in the footer of default.php above the closing body tag:

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

EDIT 7/27/2012: I’m not sure when this was fixed, but I haven’t needed to wrap everything in a div container to get my stylesheets to play nicely with the toolbar for some time now. If this really was fixed, it makes the whole process of converting a static HTML template into a concrete5 theme a lot easier.

Advertisements

4 thoughts on “How to convert a static HTML template into a concrete5 theme

  1. gmlimages

    An excellent article just what i was looking for, all I need now is to get to grips with getting the whole site converted to Concrete5. Can’t work out how to get the menu to play nicely, also can I just leave some pages static – ie. non-editable?

    This is the site I want to convert http://www.burstowparkec.co.uk

    Reply
    1. Dave Post author

      Sounds like you need separate templates: one for the pages that are editable, and one for the pages that are not. I’m not sure if there’s a way to “lock” certain content areas on certain pages. Let me know what you end up doing.

      Reply
    2. Dave Post author

      Try putting your concrete5 code in your default.php file and putting your static code in another file, called static.html or something. Instead of adding your static page to the concrete5 CMS, just add a link to static.html in your default.php file like so:

      default.php

      <!doctype html>
      <html>
      	<head>
      		<link href="<?php echo $this->getThemePath(); ?>/css/style.css" rel="stylesheet" />
      		<?php Loader::element('header_required'); ?>
      		<?php
      		// If a user is in edit mode, remove this jQuery script so they can edit text inside hidden divs
      		if (!$c->isEditMode()) {
      		?>
      		<script src="<?php echo $this->getThemePath(); ?>/js/script.js"></script>
      		<?php } ?>
      	</head>
      	<body>
      		<div class="header">
      			<?php $a = new Area('header'); $a->display($c); ?>
      			<a href="static.html">Link to Static Page</a>
      		</div>
      		<div class="main">
      			<?php $a = new Area('main'); $a->display($c); ?>
      		</div>
      		<div class="footer">
      			<?php $a = new Area('footer'); $a->display($c); ?>
      		</div>
      		<?php Loader::element('footer_required'); ?>
      	</body>
      </html>
      

      static.html

      <!doctype html>
      <html>
      	<head>
      		<link href="themes/my_theme/css/style.css" rel="stylesheet" />
      		<title>My Title</title>
      		<script src="themes/my_theme/js/jquery.min.js"></script>
      		<script src="themes/my_theme/js/script.js"></script>
      	</head>
      	<body>
      		<div class="header">
      			<h1>
      				My Title
      			</h1>
      			<img src="themes/my_theme/img/logo.png" />
      			<a href="default.php">Link to Home Page</a>
      		</div>
      		<div class="main">
      			<!-- Static content goes here -->
      		</div>
      		<div class="footer">
      			<h6>
      				My Title © 2012
      			</h6>
      		</div>
      	</body>
      </html>
      

      In your static.html file, just remove the PHP tags, include your title in the head element, and include a reference to jQuery if you’re using it. Finally, replace any placeholders ($a = new Area etc.) with the HTML content that goes inside.

      Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s