$a = new Area('Header Nav');
$a->display($c);

Originally posted at dowdrake.com

concrete5 is very intuitive from the user perspective, but (at least for me) a bit of a challenge at first to figure out what's going on under the hood. After playing with the application and meandering around the documentation for a while, I had two burning questions:

Question 1: While editing the home page (with the default content), I wondered: "Where do these page areas, like 'Header Nav', 'Header', 'Main' and 'Sidebar' get defined?"

Question 2: After messing around in the dashboard for a while, I wondered: "How do I really define a Page Type?" I could see that the Home page was set to Page Type 'Right Sidebar'. I could also see a list of pre-defined Page Types:

• Full Width
• Left Sidebar
• Press Release
• Right Sidebar

I clicked the button to 'Add a Page Type' which took me to a form, but basically it just asked me for a name, a handle and an icon... I filled in some reasonable values -- Name: "joe chicken", Handle: "silly" and picked one of the icons. But it didn't matter what values I selected -- once I saved and assigned my new Page Type to a page, I always ended up with a page structure that looked strikingly like 'Right Sidebar'. So what's going on? ... and where do I go to actually structure the thing?

The Answers 

In case you or someone dear to you is asking themselves the same questions, the answers to all these and more lie in the file system, specifically in the template files, which live inside of theme folders.

Take a look at the contents of the folder:
SITEHOME/concrete/themes/ 

The first thing to notice is that there's a folder called 'dark_chocolate' and another called 'greensalad', but none called 'plain_yogurt' or anything like that. However, there is one other folder in there called 'default'. Yep, you guessed it, the 'Plain Yogurt' theme is in that folder. If I look in the dashboard under 'Pages and Themes' it even says so in the description of 'Plain Yogurt'. 

Why do we need a default theme? Don't we have to select a theme for the site and/or individual pages? Good question. I'm not entirely sure, but in general, defaults are a good thing in that they keep things from going horribly wrong if something does go missing...

Let's look inside that folder:
SITEHOME/concrete/themes/default/

There are four PHP files in there:

• default.php
• full.php
• left_sidebar.php
• view.php

Ok, so left_sidebar.php is the template for Page Type "Left Sidebar" and full.php is for "Full Width", but what about Page Types "Right Sidebar" and "Press Release"? As you probably guessed by now, those Page Types use the template default.php (and so does my "joe chicken" page type). Why? Because whenever no template can be found in the page's theme with a file prefix corresponding to the handle of the Page Type assigned to the page, the default template is used. 

So now we know why pages assigned type "Press Release" or "joe chicken" look the same as ones based on "Right Sidebar" -- They all use the same template.

Ok, so let's take a look inside a couple of these templates. Here are the contents of default.php:

<?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">&nbsp;</div>        
    </div>

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

It's pretty simple, just a couple of nested <div>'s and a little bit of PHP. The lines

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

are essentially just including two other files. Let's open them too... It's a bit of code, so I won't paste it all in here, but the main thing to notice is that we can now see where the mysterious page areas in Question 1 are defined. For example:

The page area objects are created with a handle while the page is being rendered. There's quite a bit going on in that little $a->display($c) method call. It's something like this.

1. Get the most recent version for our page (a page is basically a collection of blocks with some structure imposed by the template).
2. Look in the database in the 'CollectionVersinoBlocks' table to find all the blocks with that collection and revision and with arHandle 'Header Nav'. Also get their display order, then render them.

I'm sure there's more to it, especially when you get into blocks with layouts and so forth, but that's the basic idea.

You might be asking yourself, "I wonder what would happen if I added a bunch of blocks to various pages in a page area with handle 'Main' and then some joker came along and edited the default template and changed the handle of that page area to 'FunkyChicken'?" Well, I just tried it, and all the content goes away. But change the handle back to 'Main' and it all comes back. So now you can relax and get some sleep.

You may have noticed that I didn't say anything about view.php in the theme directory. Well, yeah... that's for another day.