You are here: start » dev » theming » guide_4.7

Documentation

Addons

Team area

Theming guide (pluck 4.7)
Converting pluck 4.6 themes
Directory structure

Theming guide (pluck 4.7)

This page will guide you through the process of making your own pluck-theme. You have to know your way around (X)HTML, and CSS. Knowledge of PHP is not required.

Converting pluck 4.6 themes

The theming system in pluck 4.7 is slightly different from the older system in pluck 4.6. Converting a pluck 4.6 theme for use with 4.7 is very easy, and requires only a few minutes of work. You will have to adjust the following two functions:

Rename all theme_module() functions into theme_area()
The theme_menu() function has changed. Scroll down this page to find the new specification of this function.

Directory structure

Each theme has its own directory in data/themes. Your can make your theme in data/themes/blue, for example.

There are at least 3 files needed in a theme-directory:

style.css - the CSS-layout file of your theme
theme.php - most important file: contains the (X)HTML of the theme
info.php - contains some info about your theme

We'll go through these files one by one.

The following file is optional:

style-rtl.css - the CSS-layout file of your theme, for RTL (right-to-left) languages, such as Hebrew. If you want your theme to support these languages, you can include this file. If this file is not included with your theme, pluck will try to convert your style.css itself.

style.css

This isn't very difficult: every theme needs a CSS-file. It's important that the name of the file is style.css, because the file will be included in the (X)HTML-code automatically. It's not necessary to include the file yourself.

Pluck uses a few style-objects to theme some objects. You can use the following objects in your css-file if you wish to enhance your theme further:

.album : for the divs in which the various albums or the images in the album module are shown
.albuminfo: for the span-element containing the title of an album or image
.blog_post: for the div in which a blogpost is shown
.blog_post_title: for the p-element containing the title of a blog post
.blog_post_info: for the span-element containing some info about a blog post
.blog_post_content: for the div-element containing the content of a blog post
#blog_reactions: for the div-element containing all reactions on a blog post
.blog_reaction: for the div-element containing one reaction on a blog post
.blog_reaction_name: for the p-element containing the name of a reaction on a blog post
.blog_reaction_info: for the span-element containing some info about a reaction on a blog post
.blog_reaction_message: for the p-element containing the message of a reaction on a blog post
#contactform: for the form-element of the contactform module

theme.php

This is the most important part. Here, you will specify the (X)HTML-code for your theme.

In this file, you can just put plain (X)HTML, no problem. However, you'll have to add some PHP-functions to include page-content, page-title and so on. Let's look at the PHP-functions we need to include.

PHP-functions

theme_meta()

<?php theme_meta(); ?>

This one, you can just put between your <head>-tags. It will input the following things:

Title-tag (so, you don't need to do that yourself)
Link to your CSS-file (you don't need to do that yourself either)
Meta-tag information that the user wants to include in his website
If needed, some things that a module wants to include

Pluck also provides you with the option to automatically include a CSS Reset file. To do this, use the function like this:

<?php theme_meta(true); ?>

theme_sitetitle()

<?php theme_sitetitle(); ?>

You can put this anywhere in your theme. It displays the title of the website.

theme_pagetitle()

<?php theme_pagetitle(); ?>

You can put this anywhere in your theme. It displays the title of the currently viewed page.

theme_menu()

<?php theme_menu($block, $inline, $active_id = null, $level = 0, $only_subpages = false); ?>

This one is important. It will display the menu-items.

This is what the variables do:

$block - The HTML block-level element for the menu. Usually "ul".
$inline - The HTML inline-level element for the menu. Usually "li".
active_id - Optional. HTML id given to inline element if the menu-link is the link of the currently viewed page.
$level - Defines which page levels should be displayed. By default shows only top pages ($level = 0). When set to 1, also displays subpages, when set to 2 also displays subsubpages, etc.
$only_subpages - If set to true, will display only subpages of the current top page (for example for use in a sidebar). Defaults to false.

Let's give an example. If we use the following code:

<?php theme_menu('ul', 'li', 'active', 0); ?>

The following HTML-code could be generated:

<ul>
  <li id="active"><a href="?file=home">Home</a></li>
  <li><a href="?file=about">About</a></li>
  <li><a href="?file=contact">Contact</a></li>
</ul>

theme_content()

<?php theme_content(); ?>

You can put this anywhere in your theme. It displays the content of the currently viewed page.

theme_area()

<?php theme_area('nameofarea'); ?>

One reason why pluck is so flexible, is that it features modules. These modules can be added to some different areas in the website. With this PHP-function, you can define where modules can be added to your theme. That way, a user can add a module to all pages on his website at once.

For example, if you have a sidebar in your theme, it's possible that some user wants to include an advertisement at that spot on all pages, with an advertisement-module. He can only do this if you define that it's possible to add a module there, with the following code:

<?php theme_area('sidebar'); ?>

You see, that you can change nameofarea in a short name that describes the place best.

Example

Take a look at the example below if you don't fully understand the module-part yet. It will be more clear then. We will take a look at an existing theme, and we'll show how we port it to a pluck theme.

This is the (X)HTML-code we have to port:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Home - website</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
 
<body>
<div class="wrap"><div class="header">Site title here</div>
<div class="menu">
    <ul>
       <li id="active"><a href="home.php">Home</a></li>
       <li><a href="about.php">About</a></li>
       <li><a href="contact.php">Contact</a></li>
    </ul>
</div>
 
<div class="content"><h1>Home</h1>
<div class="txt">These are the contents of the page</div></div>
 
<div class="sidebar">Here, we include some things like advertisements or polls.
</div>
 
<div class="footer">theme made by <a href="#">me</a></div>
</div>
</body>
</html>

Now, we'll port the code by stripping the tags from the head, and add the theme_head(); function there. We also change the site title, page title and page content with functions. Then, we add the theme_menu(); function, using the code of the menu-items. Then we see a nice place for modules: the sidebar. So there we put a theme_area();. We also put a module-space with the name main just after the content, and one in the footer with the name footer.

This is the resulting code:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<?php theme_meta(); ?>
</head>

<body>
<div class="wrap"><div class="header"><?php theme_sitetitle(); ?></div>
<div class="menu">
<?php theme_menu('ul', 'li', 'active', 0); ?>
</div>

<div class="content"><h1><?php theme_pagetitle(); ?></h1>
<div class="txt"><?php theme_content(); ?></div>
<?php theme_area('main'); ?>
</div>

<div class="sidebar">
<?php theme_area('sidebar'); ?>
</div>

<div class="footer">theme made by <a href="#">me</a>
<?php theme_area('footer'); ?>
</div>
</div>
</body>
</html>

info.php

In this php-file you specify some important information about your theme. The following two variables need to be included:

$themedir - the name of the directory in which your theme is situated, for example blue
$themename - the name of your theme, this can include capital letters and spaces, for example Nice Blue Theme
$module_space[] - PHP-array to define where modules can be added to the website. All the theme_area() functions you used in theme.php, you'll have to put here too. So if we use the above example, the code should be:

<?php
$themedir = 'blue';
$themename = 'Nice Blue Theme';
$module_space[0] = 'main';
$module_space[1] = 'footer';
$module_space[2] = 'sidebar';
?>

dev/theming/guide_4.7.txt · Last modified: 2011/08/03 18:21 by sander