Guidelines

This article describes the requirements of a theme you want to publish on the Themes part of PivotX.net. Because we want the themes to be easy to use for all users we use quite strict guidelines, at least in this article. If you create advanced themes this may differ. If so, please add a readme.txt with instructions to your theme to tell users how stuff works.

You'll find the default PivotX theme called Skinny with the necessary smarty tags in your PivotX templates folder. Please note that this theme does not (yet) follow all described guidelines. It is awkward to change this theme because it is the default theme and we have to keep downward compatibility in mind.

If you want to start building your own themes please read this article. When your theme is finished send it to Mail .

Theme folder contents

A basic theme consists of the following:

  • _sub_header.tpl
  • _sub_sidebar.tpl (optional)
  • _sub_footer.tpl
  • front.tpl
  • entry.tpl
  • page.tpl
  • archive.tpl
  • search.tpl (so no extra.tpl)
  • style.css (or themename.css)
  • folder named 'images' containing the used images (except themename.jpg)
  • folder name 'css' if you want to put the css files in a separate folder
  • themename.theme (export from a weblog that has this theme -- optional)
  • themename.jpg (300x200px) (a screenshot of the theme in action; obligatory when themename.theme is available)
  • filled in submission form (example will be in the standard template directory (not there yet)) 

The _sub_ files

A theme folder contains some files starting with _sub_. These are files that are included in your normal pages like your header, footer and sidebar. You include them with [[ include file="`$templatedir`/_sub_header.tpl" ]]. The use of variable templatedir makes your theme files more portable.

1. _sub_header.tpl

This is the header file included in all main templates of your theme. The header contains all standard header information and the first part of the <body> section, used on all pages (i.e. <div id="wrapper">, etc.) including the navigation part.
To make sure your theme follows the charset guidelines add

<meta http-equiv="Content-Type" content="text/html; 
charset=utf-8" />

to this file. Please also add

<link href="[[ template_dir base="true" ]]pivotx_essentials.css" 
rel="stylesheet" type="text/css" media="screen" />

to your header. This CSS file contains some basic markup PivotX uses. If you wish to alter the standard PivotX CSS, overwrite rules in your own CSS file.
Remember: When PivotX gets updated, pivotx_essentials will be overwritten.

Also useful to add to the header so users won't be bothered by setting the correct language settings:

<html xmlns="http://www.w3.org/1999/xhtml" [[lang type='xml']] 
[[lang type='html']]>

2. _sub_sidebar.tpl
The sidebar also appears on all pages (in this example at least). If you have multiple sidebars you can include a _sub_sidebar_left.tpl and a _sub_sidebar_right.tpl for example. If your theme doesn't have a sidebar you can leave it out.

3. _sub_footer.tpl
The footer contains the body and html closing tags and you can add some info here, like the name of the author and, of course, a link to PivotX.net.

 

The main template files

A basic theme consists of a front page, a page to show an Entry, a page to show a Page, an archive page and a search page. You can use the front template as an archive page but we choose to duplicate it and name it 'archive' so it's clear which file to choose when users setup and configure their site.

4. front.tpl
This is it, the main template of your website. The front page contains your [[subweblog]] and page navigation (if you want to).

5. entry.tpl
This is the template used for single entries and contains the stuff needed for commenting, entry navigation etc.

Important: please include the standard comment form. Use this tag: [[commentform]] instead of non-standard comment form code so all options will remain intact and users can choose their spam protection. If possible take into account that some entries won't have the possibility of commenting and use [[ if ($entry.allow_comments == 1) ]] to choose between that.

6. page.tpl
This template is used for pages. It can contain the same stuff as your entry page except the commenting part (you can't comment on pages yet)

7. archive.tpl
This template defines the look of your archives. It needs a subweblog so PivotX can get a list of entries from the database. This template can be identical to the front page.
If you want to have different lay-out for archives and front page paging then you should code at the start of the archive template:

[[ if !$modifier.archive ]]
    [[ include file="`$templatedir`/front.tpl" ]]
[[ else ]]
    .... Content of archive template ....
[[ /if ]]

This is because the archive template is also used when paging from the front page; if no separate lay-out is necessary then make sure the subweblog names are the same in both templates.

8. search.tpl
The page that shows search results. This template needs the [[ content ]] tag to show the search results. So please no extra.tpl!

 

Other files and folders

9. style.css or themename.css
You can name this file after the name of your theme as you wish. But you have to include pivotx_essentials.css too (see _sub_header.tpl). Your stylesheet should load after pivotx_essentials is loaded. So put the link to your css file after the link to pivotx_essentials.css.

10. folder called 'images'
This is the folder where you put all the graphics used in your theme.

11. themename.theme
This is the weblog configuration file. It can be created through a weblog configuration that is using it in PivotX. If people use your theme, the .theme file defines the templates and other weblog configuration stuff when they create a new weblog.
This is optional. If you submit a theme to the Themes part of PivotX.net the PivotX team usually creates a clean fresh .theme file. Remember that when creating this file your weblog language should be English otherwise people might have problems understanding your text strings. Also allocate categories Default and Linkdump to your subweblogs and, if possible specify dummy mail address "youraddress@example.org" on the reply mail (last tab).

12. themename.jpg
This is a screenshot of your theme. It has to be named the same as your theme folder name. If people use your theme and upload it to their webserver this picture is shown in PivotX when a weblog gets created (if a .theme file is present). Remember the language used on the jpg! Dimensions should be 300x200px. You can also supply an additional jpg called themename-big.jpg which will be used as pop-up on the themes site.

13. information file (optional)
Some plain text file explaining special features etc. So no file formats where you need additional software for to read them.

14. jQuery files
If your theme contains jQuery code please do not include the general jQuery files. PivotX already uses the most recent one in its installation. If you need some plugins or UI files first check whether they are included in PivotX' versions. For all 3 types of files there are host variables: jquery_url / jquery_ui_url / jquery_plugins_url.

15. submission form
In this form you supply some details about the theme.
The following information is needed (to be decided):

Theme Name: 
Theme URI: 
Description: 
Version: 
Date:
Author:
Author URI:
License: 
Required PivotX version: 
Used Extensions:  

 

Using extensions

If you are using extensions within your theme templates you should make the user aware of it. This can be done through the information file but better by adding a tag exists construction in your template:

[[ if !tag_exists('nivoslider') ]]
    Required extension nivoslider is not active!
[[ /if ]]


Compatibility and validation

Themes published on the Themes part of PivotX.net should be thoroughly tested on different browsers. If you develop themes on a Windows platform, test your theme by creating your own weblog using your theme and check it in Internet Explorer 7 and up, Firefox, Opera and Chrome/Safari. If you work on a Mac you probably test your themes in Chrome and Firefox but a test in Internet Explorer is really necessary. Your website should behave the same with all browsers. We prefer testing on both Mac and Windows platforms of course.
We know this is a lot of work and we will do some tests of our own. So if you are unable to test your theme then we will do that for you. But if you are able to do the testing yourself it would save us a lot of work.

Also be aware that all files have to be encoded as UTF-8 (without B(yte) O(rder) M(ark). And please refrain from using tabs in the source files (change them to spaces).

Last but not least we advice to check your HTML with the W3C validation service. The W3C CSS validation service enables you to check your CSS code for validity, and warns you if you are using browser specific code.

If you finished testing and want to submit your theme please create a zip only containing the theme folder (so no extra Mac files please) and send it to us.