All themes in CumulusClips are stored in the themes directory located at: /cc-content/themes. Each theme sits in it's own directory at this location. You can have as many themes as you want, however only two can be enabled, one for the main site and one for the mobile site. To see which themes are available within CumulusClips visit the themes section on the admin panel at: Admin Panel -> Appearance -> Themes.
Creating a Theme
The best way to create a theme for CumulusClips is to copy the default cumulus theme and rename it to something unique. Then open the theme.xml file with your text editor of choice and update the theme name, author, and any other desired fields.
If you feel like you're up for the challenge and wish to completely build your theme from the ground up, then below is a list of the required files for a theme. Simply create a directory inside /cc-content/themes. The directory name should be unique and all lower-case with no special characters or spaces in it. Next, add all the required files within your newly created theme directory.
There is no official theme installation process. Just make sure all the required files are in your theme and it will automatically should show up in the themes section of the admin panel.
There are several files and directories which are required to build a theme for CumulusClips, these are:
From within views, blocks, and layouts you have access to the $config system object, all system constants, and any variables assigned to the View object.
Normal variables meant to be accessed from theme files need to be assigned to the View object in either the controller or plugin e.g.
View::$vars->my_variable = 'This will be accessible from a view';
To access them in your theme files simply reference them as a normal PHP variable e.g.
Basic meta data which consists of page title, and meta keyword & description tags come from the currently loaded language file. These values are stored in the View object's meta property, if defined at all (some pages may intentionally omit these tags). To access page meta data simply reference the View::$meta property, e.g.:
<head> <title><?=View::$meta->title?></title> <meta name="description" content="<?=View::$meta->description?>" /> </head>
The above example may be slightly misleading because it depicts manual insertion of the meta description tag. This tag is actually automatically added to your theme via the Meta Queue. Queues will be discussed later on in this guide.
Config - System Object
The $config system object contains several system settings and values which are used throughout the application as well as your themes. Most of $config values are assigned within the application bootstrap file (/cc-core/config/bootstrap.php). You can review this file to see some the values available to you. Keep in mind though, that the $config object's content can change from the bootstrap to the point your theme is called.
The $config object is globally made available to your theme files so it can be accessed directly in theme files. One of the most commonly used $config values are the video URLs, such as the H.264 video URL e.g.:
<video width="640" height="480"> <source src="<?=$config->h264_url?>/video.mp4" type="video/mp4" /> </video>
Theme - Constant
All system contants are available to your theme, however the THEME constant is particularly useful. It provides the direct web accessible URL to the root of your theme. It provides a URL which looks like this:
<link rel="stylesheet" type="text/css" href="<?=THEME?>/css/main.css" />
Theme Path - Constant
THEME_PATH is similar to the THEME constant above only that it provides a filesystem path to your theme instead of URL. It's output is something like this:
This is useful when programming within your theme such as including scripts via PHP. Here's an example of including a PHP script in your theme using the THEME_PATH constant:
include_once (THEME_PATH . '/scripts/random.php');
Parts of a theme
The screenshot is a 200px wide thumbnail of your theme in png format. This file is displayed along with your theme's information in the Themes section of the admin panel. It should simply be called 'screenshot.png' and sit at the root of your theme.
The theme XML identifies your theme to CumulusClips. This is where you would add descriptive information about your theme like title, description, author, etc. Below is a sample theme XML file:
<?xml version="1.0" encoding="UTF-8"?> <theme> <author>Miguel A. Hurtado</author> <name>Cumulus</name> <mobile>false</mobile> <description>The default theme for CumulusClips</description> </theme>
This information is only made visible to admins within the Themes section of the admin panel. The following items within the theme XML are required:
- author - Person / Organization who created the theme
- name - Name of the theme
- mobile - Whether or not the theme is a mobile theme. (true if it's for mobile, false if not)
- description - Short description for the theme
Feel free to add your own additional information. The theme XML file should be named 'theme.xml' and sit at the root of your theme.
Every page on your video website has a corresponding view. The view contains all the HTML specific to that page.
The view is loaded first, before any other part of your theme. This is to allow you to write custom code before the page is actually rendered, such as changing the page layout.
From the view you can instruct the system to load the header/footer layout files at whatever location you like by calling the View::Header and View::Footer methods. A sample view would look as follows:
<?php View::Header(); ?> <h1>View Header</h1> <p>Text for body of page</p> <?php View::Footer(); ?>
Structure for your theme is provided by layouts. A layout is a pair of files, a header & footer, in the layouts directory. They should be named according to the following convention:
Both files are required, even if theme doesn't have a header or footer; you can leave them blank if that's the case. Layouts are meant to wrap around the individual views providing core shared HTML elements such as Doctype, Meta tags, Html, Head & Body tags, headers, footers, sidebars, columns, and menus.
CumulusClips will automatically look for the default layout:
You can override this behavior and use a different layout by calling the View::SetLayout method within your view and passing in the desired layout name, e.g.
CumulusClips will then use the 'my_custom_layout' layout instead.
Blocks are used for sections of HTML that are repeatedly used throughout various parts of your theme. Rather than having that code duplicated you can place the HTML in question within a block and then simply reference the block wherever you want. A good example of this would be an ad on your website. Your ad HTML would appear on every single view / page, but instead of repeating that code you would use a block in each view.
A block can be inserted by calling the View::Block method. You must pass to it the name of the block which you want to include, e.g.
That would result in the 'ad_300' block being included. The View::Block method can accept both a block filename or a full filesystem path to a block. By default, this method will look in the blocks/ directory of your theme first. If the directory or file don't exist then the given name will be treated as a filesystem path. Blocks can be used in all views, layouts, and even other blocks.
Repeating blocks are identical to normal blocks. However the thing to note when using repeating blocks is that they're meant to be output numerous times consecutively. To output a series of repeating blocks use the View::RepeatingBlock method and pass the name of the block you want repeated and a list for which to loop through, e.g.
View::RepeatingBlock ('block.tpl', $list_of_records);
Repeating blocks output the block once per entry in the passed list / array. This is extremely useful when creating a list of records. For example, if you wanted to output a list of videos simply compile a list of video ids and call the repeating block method on the video block, e.g.
<?php $list_of_videos = array (43, 59, 81, 92, 101, 166); ?> <!-- Recent Videos --> <div id="recent-videos"> <?php View::RepeatingBlock ('recent_video_block.tpl', $list_of_videos); ?> </div>
The above would output a list of 6 videos, specifically the videos in the array. The value of each entry in the array will be made available to the block being repeated via the $_id variable. You can in turn, add code to the block to load a video with that id and output it's information in a format you like, e.g.
<!-- recent_video_block.tpl --> <?php $video = new Video ($_id); ?> <div> <p><a href="<?=$video->url?>/"><?=$video->title?></a></p> <p><?=$video->description?></p> </div>
The CumulusClips theme engine makes use of queues to allow theme and plugin developers to queue up items so that they can be output togerther at a later time. There are four types of queues in the theme engine. These are:
- CSS Queue
- Meta Queue
- Sidebar Block Queue
Using queues is a two step process. First you must add an item to the queue using the Add method. Next you must instruct the theme engine dump all the items in the queue using the Write method. All of the queues listed above work in the exact same way.
In order to add an item to the CSS Queue you would use the View::AddCss method. You must provide it with the file your wish to add to the queue. This method accepts both a filename or a direct URL to a file. It will by default look for the given file in the css/ directory of your theme first. If the file or directory don't exist it will treat the provided argument as a direct URL and use it as is. Here's an illustration of both methods:
View::AddCss ('http://random-site.com/styles/reset.css'); View::AddCss ('test.css'); View::AddCss ('main.css');
Later on in the Head section of your theme you would dump all your queued CSS using the View::WriteCss method, e.g.:
<head> <title>My Page</title> <?php View::WriteCss(); ?> </head>
The View::WriteCss method will automatically write the HTML required for properly linking a CSS file. The above output would look as follows:
<head> <title>My Page</title> <link rel="stylesheet" type="text/css" href="http://random-site.com/styles/reset.css" /> <link rel="stylesheet" type="text/css" href="http://example.com/cc-content/themes/example/css/test.css" /> <link rel="stylesheet" type="text/css" href="http://example.com/cc-content/themes/example/css/main.css" /> </head>
View::AddJs ('https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.js'); View::AddJs ('plugin.js');
</div> <!-- END Wrapper --> <?php View::WriteJs(); ?> </body> </html>
In order to add an item to the Meta Queue you would use the View::AddMeta method. This method accepts a key value pair, that being the name of the meta tag and it's content. The meta queue is only able to produce named meta tags, others such as http-equiv cannot be generated with the Meta Queue. Here's an example of adding to the Meta Queue:
View::AddMeta ('robots', 'noindex,nofollow'); View::AddMeta ('author', 'Billy Joe Bob');
Later on in the Head section of your theme you would dump all your queued meta tags using the View::WriteMeta method, e.g.:
<head> <title>My Page</title> <?php View::WriteMeta(); ?> </head>
The View::WriteMeta method will automatically write the HTML required for a complete meta tag. The above output would look as follows:
<head> <title>My Page</title> <meta name="robots" content="noindex,nofollow" /> <meta name="author" content="Billy Joe Bob" /> </head><
Sidebar Block Queue
In order to add an item to the Sidebar Block Queue you would use the View::AddSidebarBlock method. You must provide it with the block file your wish to add to the queue. This method accepts both a filename or a full path to a block file. It will by default look for the given file in the blocks/ directory of your theme first. If the file or directory don't exist it will treat the provided argument as a filesystem path and use it as is. Here's an illustration of both methods:
View::AddSidebarBlock ('/var/www/html/cc-content/plugins/sample/custom-block.tpl'); View::AddSidebarBlock ('login-box.tpl');
The default location for writing queued sidebar blocks is in the sidebar of course, which is located in the footer file of the layout. The method can be called however from any part of your theme. In order to output all the queued sidebar blocks you would use the View::WriteSidebarBlocks method, e.g.:
<!-- BEGIN Sidebar --> <div id="sidebar"> <?php View::WriteSidebarBlocks(); ?> </div> <!-- END Sidebar -->
The above would result in all the blocks in the queue being included into your theme at this location.