Customizing the mobile experience
concrete5 allows you to render pages server to mobile browsers in a different, mobile-specifc theme of your choosing. To learn more, check out Mobile Theme in concrete5.6 and Mobile Theme Switcher for older versions.
When a separate, mobile theme is activated, a constant named MOBILE_THEME_IS_ACTIVE is set so you can test within your page types and themes to conditionally display certain elements depend on the user agent detected.
What is a Theme?
Every page in your concrete5 must have a theme assigned to it. Themes are actual directories in your file system with all the presentation code needed for your outer page wrapper. Themes generally contain multiple Template files. Templates generally contain lots of HTML and CSS and just a little bit of PHP to define where the editable areas of the page area.
You can use more than one theme in a site, simply change the theme from the Design tab in Edit Mode for a page and all new pages you make below will use the new theme. You can apply a new theme to every page in your site by going to Dashboard > Pages & Themes and clicking "Activate" next to the new theme.
How do Themes and Page Types work?
When loading a page, first the theme for this particular page is determined. Then concrete5 looks at the Page Type for this page. If a template file matching the Page Type handle is found in the theme, it is used. If a matching filename cannot be found, "default.php" is used. If the page is a single page, view.php is used.
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 design in your theme, create a "my_page_type.php" template file in the directory.
- In the HTML head tag, before any references to CSS stylesheets, add:
Loader::element('header_required');
and right before the closing body tag add
Loader::element('footer_required');
add all JS in your theme after the footer element, and all CSS after the header element. -
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();
-
Add a 120x90 thumbnail PNG-format 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.
Confused? Watch Andy convert a static HTML template into a concrete5 theme in under 8 minutes.
Keep Theme Styles from Interfering with concrete5
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. This will ensure that these greedy styles only affect the theme's elements, rather than concrete5's toolbar and dialog window as well.
View.php
The concept of single pages in concrete5 is discussed more elsewhere: in short, single pages are a simple way of creating one-off pages for specific functionality in your site. For example, say you have complicated search page, with multiple forms and a special layout that's unlike any other page on your site. You wouldn't want to create a page type for this page, since it will not likely be added more than once throughout your site (and certainly won't appear than in more than one theme.)
Hence, the concept of "single pages." These are also sometimes referred to as "static pages," but this is a misnomer, since these single pages are capable of holding concrete5 block areas, being renamed through content management system, and can have arbitrary page attributes assigned to them.
Themes and single pages interact mostly the same way that page types and themes do: if a template for a particular single page appears within a themes directory, it is applied. However, there is an additional directory on the server for "single_pages." Within this directory is PHP and HTML content for the main area of a page. Additionally, within the theme that is going to be applied to your single page, there should be an extra file, named "view.php." This file is similar to "default.php" in that it is used automatically, however it requires that a variable, named $innerContent, is printed in one spot. This is the spot in this particular theme wrapper file, that the contents of the single page are going to be printed.
This allows multiple single pages to be added, and the user to automatically include the content within a matching wrapper file, like CakePHP or Code Igniter does with their concepts of "views" and "layouts." View.php within the theme directory is the layout file, and the specific single page in the single_pages directory is the view.
The PageTheme object provides the following methods:
$theme = PageTheme::getByID($id)
Returns a PageTheme object by ID.
$theme = PageTheme::getByHandle($handle)
Returns a PageTheme object by handle.
$themes = PageTheme::getList($where)
Returns a list of all installed themes. $where is an optional parameter that can be used to filter the list.
$themes = PageTheme::getAvailableThemes($filterInstalled = true)
Returns a list of all themes available for install.
$theme = PageTheme::getByFileHandle($handle, $dir = DIR_FILES_THEMES)
Searches the specified $dir for a directory of a certain handle, and populates the themes information based on its contents.
$theme->outputStyleSheet($file, $styles = false)
Looks into the current theme and outputs the contents of the stylesheet.
$theme->reset()
Removes any custom styles by clearing them out of the database.
$theme->saveEditableStyles()
Takes an associative array of pagethemeeditablestyle objects and saves it to the PageThemeStyles table.
$styles = $theme->getStyleSheets()
Returns a list of all stylesheets in a theme.
$styles = $theme->getEditableStylesList()
Retrieves an array of editable style objects from the current them. This is accomplished by locating all style sheets in the root of the theme, parsing all their contents.
$theme = PageTheme::add($handle, $pkg = false)
Adds a new theme to the site.
$files = $theme->getFilesInTheme()
Gets an array of all files in theme.
$theme->applyToSite()
Activates a theme and applies it to a site.
$theme = PageTheme::getSiteTheme()
Gets the active theme for a site.
$theme->uninstall()
Uninstalls a theme.
$theme->getThemeID()
Returns a theme's ID.
$theme->getThemeName()
Returns a theme's name.
$theme->getPackageID()
Returns a theme's package ID.
$theme->getPackageHandle()
Returns a theme's package handle.
$theme-> getThemeHandle()
Returns a theme's handle.
$theme-> getThemeDescription()
Returns a theme's description.
$theme->getThemeDirectory()
Returns a theme's directory.
$theme-> getThemeURL()
Returns a theme's URL.
Customizing System Pages
If you want your theme to apply to some of the system pages (such as /login and /register), there are a few additional steps you need to do:
- Copy the appropriate file from /concrete/single_pages to /single_pages (for example, if you want to customize the register page, copy /concrete/single_pages/register.php to /single_pages/register.php). Modify this file as you see fit, being careful not to alter or delete any of the php code.
- If it doesn't exist, create a file named site_theme_paths.php in your local config/ directory.
- Within this file, add the following lines:
$v = View::getInstance(); $v->setThemeByPath('/register','your_theme'); $v->setThemeByPath('/login', 'your_theme')