Like most content management systems, PyroCMS uses front-end themes. Though PyroCMS themes are built a bit differently than what you might be used to from other systems, they're still quite easy to create. They're so easy, in fact, that very little PHP experience is required to assemble them!
The Folder Structure
PyroCMS themes consist of HTML, images, CSS, and JavaScript, arranged into the following supported folders:
- css
- img
- js
- views
- views/layouts
- views/partials
- views/modules
While these folders will no doubt look familiar to you, the "views" folder makes the most sense within the context of MVC. When building a theme for PyroCMS, you are really building the views (including assets) of a MVC patterned application. These views consist of a master layout file and multiple partial files (i.e. a header.html or footer.html) that shares presentation logic between different layouts. We'll discuss this more shortly.
Getting Started
To get started building your first PyroCMS theme, create the supported folder structure in one of the two places that themes may reside within an instance of PyroCMS:
addons/shared_addons/themes (for themes available to all sites)
Or:
addons/[site-name]/themes (for themes available to only one specific site)
Once you have the base theme folder containing the supported folder structure created, the first file that you'll want to add to your theme is theme.php.
addons/shared_addons/themes/[my-theme-name]/theme.php
This theme.php file contains all essential details for your theme, including its name, author, version, etc. In a way, this file is similar to the comment block found at the top of a WordPress theme's style.css file. Here's a basic example of a theme.php file for your PyroCMS theme:
<?php defined('BASEPATH') OR exit('No direct script access allowed');
class Theme_Foo extends Theme
{
public $name = 'Foo';
public $author = 'Zac Vineyard';
public $author_website = 'http://zacvineyard.com';
public $website = 'http://example.com/themes/foo';
public $description = 'The antithesis theme to your Bar theme.';
public $version = '1.0';
}
/* End of file theme.php */
Please take note that this file extends a PyroCMS class, called Theme. Also, because you are declaring a PHP class in this file, you'll need to make sure that the name of the folder containing your theme is used in the class declaration. So, if the folder housing your theme is called, "foo," the class created in your theme.php should be named, Theme_Foo (instead of Theme_Custom, as shown in the example within PyroCMS' documentation).
Once you have created your theme.php file, you can login to your PyroCMS control panel and view your theme listed in the Themes module.
Layouts
All layouts files for a PyroCMS theme exist in one of two locations:
addons/[site-ref]/themes/[my-theme-name]/views/layouts/
Or:
addons/shared_addons/themes/[my-theme-name]/views/layouts/
Every theme should have a layout file, named "default.html" in one of the locations listed above. Additional layout files are optional; I'll show you how to add more layout files in a moment. First, it's important to review the contents of a layout file.
Layout files in PyroCMS are built using HTML and a tag parser, referred to as the Lex Tag Parser. This is what a very basic PyroCMS layout file looks like:
<!DOCTYPE html>
<html>
<head>
<title>{{ template:title }}</title>
{{ template:metadata }}
</head>
<body>
<h1>{{ template:title }}</h1>
{{ template:body }}
</body>
</html>
The special tags you see in this bit of HTML are Lex parser tags. If you've ever used Smarty templates in PHP, these may look somewhat familiar. The primary benefit to using Lex parser tags in your layout files is that you don't have to put PHP directly in your views (remember, we're using MVC), which gives you the best chance of creating PyroCMS themes that follow the don't repeat yourself pattern.
The example that I've given above is simple, of course, but Lex parser tags are quite powerful. They can loop through data, work with attributes, and more. Learn more about the Lex Parser in the PyroCMS documentation.
A more complex PyroCMS layout file looks like this:
<!DOCTYPE html>
<html>
<head>
<title>{{ template:title }}</title>
{{ template:metadata }}
{{ theme:favicon file="favicon.png" }}
{{ theme:css file="style.css" }}
{{ theme:js file="site.js" }}
</head>
<body>
<div class="header">
<div class="logo">
{{ theme:image file="logo.jpg" alt="Your Cool Logo" }}
</div>
<div class="nav">
{{ navigation:links group="header" }}
</div>
</div>
<div class="content">
<h1>{{ template:title }}</h1>
{{ template:body }}
</div>
</body>
</html>
You'll notice that this layout file, using Lex, includes assets, like CSS, JavaScript, and images. Using Lex tags and HTML allows PyroCMS developers to build layout files very quickly.
Partials
Partials in PyroCMS, which stands for partial layouts, allows you to break layouts into reusable parts or sections. These sections can then be loaded by different layout files. This keeps you from typing the same code (header, footer, etc.) into multiple layout files.
Depending on where you've placed your theme files, partials are created in one of two locations:
addons/[site-ref]/themes/[my-theme-name]/views/partials/
Or:
addons/shared_addons/themes/[my-theme-name]/views/partials/
Partials are loaded into layouts using this Lex tag:
{{ theme:partial name="partialname" }}
This Lex tag operates exactly like a PHP include statement - similar to one that you would find in WordPress or other themes. The code below is a simple example of a PyroCMS layout that takes advantage of partials.
{{ theme:partial name="header" }}
<div class="content">
<h1>{{ template:title }}</h1>
{{ template:body }}
</div>
{{ theme:partial name="footer" }}
The contents of the header.html partial and footer.html files are, of course, the HTML we'll need to reuse from the template in our previous code example above. One quick pointer: there is no limit to the number of partials that you can use in one layout. Additionally, partial files may contain any combination of valid HTML and Lex.
Multiple Layout Files
To add another layout to your instance of PyroCMS, create one more layout file in your theme's views/layouts/ directory. This file may receive any name, but it's a good idea to name it as descriptively as possible - like about.html.
For added flexibility, you can make use of as many layout files as you'd like. When you edit or create a Page Type in your PyroCMS control panel (Control Panel→Pages→Page Types) and select your desired file from the dropdown, all the layouts in your theme's layout file will be available to use.
Mobile Layouts
PyroCMS is able to easily display separate layouts for mobile and desktops. To use this feature, move your layout files into a folder, called "web" within the views folder, so that your default layout will be located here:
[your-theme]/views/web/layouts/default.html
When a user accesses your site using a desktop browser, the primary layout files in this location will be used. If the user accesses your site using a mobile device browser, users will be supplied with the mobile layouts that you've created in this location:
[your-theme]/views/mobile/layouts/default.html
This feature works with multiple layout files.
Please take note of this warning found in the PyroCMS documentation: "PyroCMS does not consider the iPad a mobile device, so it will not load your mobile layouts if the user is accessing your site using an iPad." If, however, on your site, you'd like to make an iPad recognized as a mobile device, you can change the "user_agent.php" file within the config/ directory to make the iPad recognized a mobile device.
Finished!
Using this article as a guide, you can see how easy it is to create a theme in PyroCMS. The code examples provided are quite simple, so I encourage you to explore the PyroCMS documentation to become more experienced with layouts, mobile layouts, partials, and the Lex Parser in PyroCMS. Have fun!
Comments