Understanding and Building Themes in Concrete
Screencast on building themes.
Launch>
When you add a page in concrete5, you MUST choose a Page Type. A typical concrete5 install contains several page types, which define several editable areas. There can be many areas attached to a particular page type. Typical areas might be "Main Content," "Sidebar," "Header," or "Header Image." Developers can easily define new Page Types through the Site Dashboard, along with typical meta information attached to those types of pages, and a thumbnail to represent the page type.
Themes are collections of Templates. Themes each get their own sub-directory in the /themes/ directory. Each Theme can contain its own sub-directories to store images, css, PHP include files, etc. If as a developer you've chopped your basic layout into HTML, that entire directory is most likely going to become a Theme with a unique Template file for every Page Type in your site. Think of Templates as the View in Model/View/Controller development, and think of the Theme as a package of Templates. Templates take the same name as the page types they match, with a ".php" as their suffix. For example, if you've added a page type to your site with the handle "product_detail," then your theme should likely contain the "product_detail.php" template, unless you're SURE that this particular theme will never need to be mapped to a product detail page.
Finally, when rendering a page, concrete5 (the Controller if we're following MVC thinking) looks at the instance of a created Page to determine which Theme it's using. concrete5 then looks in that Theme directory for a Template filename that matches the Page Type. If none exists, it chooses the default.php template which is the only required file in any Theme.
What should be a Page Type, what should be a Theme?
There's no absolute right way of breaking these up. In earlier versions of concrete there were only Page Types, and we found a lot of sites would end up of a couple of dozen redundant ones (ie: article blue, article green, etc.) With concrete5 we took the opportunity to create a matrix relationship which you can use to solve many problems in many ways.
When we decide how to build sites, we tend to think in these lines:
First, what wireframes do we have for this design? Looking at that documentation, are there unique data requirements for one page versus another. If so, they should absolutely be unique Page Types. If we see About Pages, Product Pages, and Press Releases in a site map, it's easy to assume they'll need to be unique Page Types because not only will they likely look different from one another, but they'll actually have unique data like Size or Color for Product, or Date and By-line for Press Release. So we'll pul out everything that must be unique, and see whats left.
In the remaining wireframes, what is being described as unique that might from a data model prospective, might be the same. There is little difference to a programmer in an About Page and a Services Page if they are both just long columns of text with a side nav area. If you can look at all the instances and say "gee, they might want to add this type of page elsewhere as the site grows, with no changes beyond cosmetic" than it is quite likely you're looking at one Page Type with a couple of Themes.
If you are building an extension to concrete5 that might need a few unique data views (ie: a forum) than you will most likely define Page Types for your application views and let other people customize that data presentation with Themes.
Too many Page Types in a typical install make it difficult to keep track of what type of page you're supposed to add where (although this can be limited with advanced permissions.)
It also tends to make it difficult to do site wide edits later. You can add a block to the Page Type from the Dashboard in concrete5, so every instance of that Page Type will have a copy of that block added instantly. This bulk apply ability is powerful, but means some planning as to what those eventual expectations will be has to go into determining what really needs to be a unique Page Type.
How do Themes and Page Types work?
When loading a page, first the theme for this particular page is determined. Then, a template file corresponding to that page's current page type is applied, if one exists in that theme's current directory. If a matching filename cannot be found, "default.php" is loaded.
The template file is HTML, CSS and PHP. It includes short PHP calls that define the block areas that exist for the page type.
Typically a developer will chop their design into static HTML files with a few images and layout directories as a first step. With concrete5 the whole directory structure can be dumped wholesale into a new theme directory and quickly added to the site.
- Chop your site into a working HTML directory.
- For every page type in this theme, create a "my_page_type.php" template file in the directory.
Within this template, make sure all stylesheets in your theme are referenced with
$this->getStyleSheet('your_stylesheet.css');
Within your templates, make sure that all images and files in your theme are prefixed with
$this->getThemePath();
If desired, add a 120x90 thumbnail graphic to this directory. This file should be named "thumbnail.png"
- Add "description.txt" to your theme directory. The title of your theme should go on the first line, the description of it on the second.
- Create a directory in "/themes" for your new theme.
- Upload the complete contents of your chop to /themes/new_theme."
- Enter the "themes" section of the concrete5 dashboard.
- On the themes page in the dashboard, you should see your theme, with its title and thumbnail image, in a section of the page titled "Themes Available to Install."
- Click the install button next to your theme.
- When your theme is installed, you should be redirected to a second step, entitled "Inspect Theme." Here, you will be able to automatically create page types for any special template files found in your theme. If your theme doesn't currently contain any special template files, you can click "Return to Themes."
- Your theme will be installed and should be listed with any others that are available to use on your site.
- To activate your theme to use throughout your entire site, click the "Activate" button. You will have to confirm your choice. (**Note: This action cannot be undone and will overwrite any custom theme choices on particular pages that may have been set.)
If you wish to remove a theme at any time, you may click the remove button next to its thumbnail. This will remove the theme from the concrete5 dashboard, and move its directory to the "files/trash/" directory.
Now, whenever you click the design button when editing a page, your theme's thumbnail should appear in the theme scroller, and you should be able to apply it to any page in your site.
Advanced Topics
Introduction to Themes Screencast
Keep Themes from Interfering with concrete5 Styles
Enabling Style Customization in Your Theme
Themes as Applied to Single Pages
Templates as Views: Helpful Functions For Use Within Your Templates
Specifying Themes by Path Using "site_theme_paths.php"
Order of Precedence When Assigning a Theme to a Page
A list of areas and page types for themes
Converting a site into a theme
Submitting a theme to the concrete5 marketplace
Comments:
http://www.concrete5.org/community/bugs/dashboardpagestypescontroller_spelling
Also it wasn't noted that you need an echo/print before the statement, which would have been helpful.
Im definitely uploading to the correct directory - for example I can change the .png thumbnails and see the changes when I refresh. But if I change the description.txt of the exiting themes, nothing happens?
Any help appreciated.
ps. I also get the error at the bottom of the page:
Get More Themes
Unable to connect to the marketplace.
How's the best way to do this?
I have a question regarding themes and page types—can you upload a page type template after the theme for that template has already been installed? Or would you have to go back and re-install the entire theme with all the page types you want to have?
It must be possible, because if I work with the Plain Yoghurt theme, header navigation and a banner image are automaticly insterted.
Can anyone tell me how to do it? Thanks a lot!!
defined('C5_EXECUTE') or die(_("Access Denied."));
I'm assuming that this is basically saying... "only execute this file within c5"?
I see it in the custom block example and in the themes that ship with c5 but nothing in the tutorials about it. Any explanation would be great!
Good message - we'll try and put a notice about it somewhere in a tutorial.
"How do Themes and Page Types work?"
Point 4 says to place
$this->getViewPath();
before images etc. It's actually:
$this->getThemePath();
Took me a little searching to find that and get my theme to render properly.
"How do Themes and Page Types work?"
Point 4 says to place
$this->getViewPath();
before images etc. It's actually:
$this->getThemePath();
Took me a little searching to find that and get my theme to render properly.
This is somewhat incorrect - if the page type is from a package, the contents of the page type will be rendered in the view.php's inner_content just like a single page.
If it's just a page type that doesn't have a package connected, it uses default.php...
