Layouts in Mercury
In Mercury there is a distinction between page content and the layout that the content sits in. Most of the pages on any given site share a header, a footer, a navigation and perhaps some other design elements. In Mercury we use a file called html/layout.php to create a layout within which all of your content will be displayed. Actually, we'll start with a single layout and then we'll look at how to use different layouts in the same site.
Anatomy of layout.php
The good news here is that you can put anything you want into layout.php. Envision taking a full HTML page that is populated with content. Typically there is one main area where most of this content lies. Strip this content out of your HTML and save it. Now you should have a page that has a big open space (possibly a div, possibly a table cell). This is where your content will go.
Put the following code into the div or table cell where your content belongs:
<?= $pagecontent ?>
Save this file as your layout.php. It's that simple.
Sure, you have to make your images, your CSS, maybe a flash header (and so on) but to actually take your HTML layout and create a full Mercury site it's that easy. When you create CMS pages, when you display forum content or blog posts they will be inserted into your layout.php file where that $pagecontent variable is located. And Bob's your uncle.
Order of Operations and Specifying a Layout File
It is important to know the order that Mercury operates. In an HTML file you start at the top and work your way to the bottom. In Mercury you start with the middle (the content) and then insert it into the top and the bottom (the layout).
This lets us do a couple of things. One is that we can set some variables in our content processing and have them show up in the title tags and meta data. It also lets a piece of content request a specific layout. This is done by calling code like this:
m("core", "setLayout", "layout2.php");
This example would look for a file called html/layout2.php instead of html/layout.php.
If you want to serve your content straight (ie. with no header, footer or layout) then you can call that same function and pass in a blank name like so:
m("core", "setLayout", "");
This is useful if you want to serve dynamic CSS or javascript files and don't want the layout around it.
Enhancing layout.php
Another goal of Mercury was to have clean headers at the top of the HTML. By putting the following lines at the top of your template file Mercury will have access to a couple of variables for the title tag and meta-data. The main Mercury CMS sets these variables automatically for you.
<?php
echo m("core", "head");
?>
The easiest way to see what this does is to put it in your code and try it, then view source.
Another part of keeping clean HTML is to group CSS files and javascript files together in the document HEAD. The tag above will take care of this for you if you specify your CSS and javascript files using some Mercury functions.
<?php
m("core", "addCSS", array('name' => 'menu', 'path' => '/css/style.css'));
m("core", "addJavascript", array('name' => 'custom js', 'path' => '/scripts/myfile.js'));
echo m("core", "head");
?>
Mercury will collect all of the addCSS and addJavascript requests that take place in the content process and at the top of your layout. When the core/head function is called it will generate HTML to include all of the files. This keeps you from having your javascript includes and CSS files scattered all willy-nilly throughout your document.