Themes best practices and definitions

Theme structure and rules effective from ImpressPages CMS 2.3

General rules

When developing a theme keep in mind:

Every widget can be dragged to any content block. Therefore, the styles should be developed accordingly.
Define image sizes for main block and scale with CSS rules for other blocks.
Configure all styles for all widgets and their layouts.
Make styles reusable. For example, text is used not just in Text widget. It can be part of form module. Therefore, don't restrict text style only for text widget. Unless you intentionally want to do it.
Always put user first - his needs and purposes for the website. Keep it simple, but not simpler.

Theme structure

Theme can be as complicated as you want or need. ImpressPages CMS is really flexible to support your imagination. However, there are some pieces that must be in the theme to make it work.

By default there are these file types inside the theme:

PHP files - layout files. They are responsible for the output of the content.
CSS files - style files. They are responsible for the style, design, colors, etc.
JS files - Javascript files. They are responsible for the dynamics of your website.
Image files - talks for themselves.

Usually you can find some folders in the theme:

/img/ - contains all image files to make structure of the files in theme folder cleaner.
/install/ - contains technical elements to make theme installable with one click.
/modules/ - optional. It contains php (layout) files to override default HTML output of the system for various elements.
other folders that theme developer may use for various purposes.

The minimal requirements for the theme to work is /install/ folder (with required contents), main.php and blank.php layout files.
NB! Minimal requirements don't mean that theme will be usable. It just don't throw system errors.

File - main.php

This is the main, required and most important layout file in the theme. This is used to show all the content of the website.

The minimal set up of this file is as follows (explanations are here):

<?php if (!defined('CMS')) exit; ?>
<?php echo $this->doctypeDeclaration(); ?>
<html<?php echo $this->htmlAttributes(); ?>>
<head>
<?php echo $site->generateHead(); ?>
</head>
<body>
    ...Your HTML...
 
    <?php echo $site->generateBlock('main'); ?>
 
    ...Your HTML...
 
    <?php echo $site->generateJavascript(); ?>
</body>
</html>

File - blank.php

This is required for RSS and other functionality (XML, etc.). Should be included without changes into each theme.

File - ip_content.css

This is main and the most important CSS file of the theme. It defines styles for all widgets and modules. Moreover, it should contain global styles that core elements or external plugins may depend on.

ip_content.css file is automatically added to tinymce for rich text editing.

Always check the ip_content.css file in default theme of newest version of ImpressPages CMS. It will contain all definitions of classes in use by default. It's always safer to copy and change it, instead of developing it from scratch on your own.

Most important classes that easily can be forgotten:

clearfix - automatically clears the bottom of the element if it contains floated child elements.
clear - invisible elements that clears all floated elements above it.
mceContentBody - default class added to the body of tinymce rich text editor. This is used to make theme and rich text editor styles to look the same.
caption, signature, note - default text style classes in tinymce rich text editor.

If your theme has more than one content block (for example, default theme "LT Pagan" has two: main and side), make sure all widgets look good on any of them.

Default ImpressPages CMS installation has 16 widgets that users can drag&drop:

Widget	Codename	Default layouts	Description
Title	IpTitle	default, level1, level2, level3
Text	IpText	default
Separator	IpSeparator	default, space
Text with image	IpTextImage	default, right
Image	IpImage	default, lightbox
Image gallery	IpImageGallery	default
Logo gallery	IpLogoGallery	default
File	IpFile	default
Table	IpTable	default
Newsletter	IpNewsletter	default
HTML	IpHtml	default, escape, preformatted
Rich text	IpRichText	default
F.A.Q.	IpFaq	default, disabled, expanded
Form	IpForm	default
User login	IpUserLogin	default	Shows up when "user" zone is created.
User registration	IpUserRegistration	default	Shows up when "user" zone is created.

File - site.js

Theme must contain at least one Javascript file (by default it's site.js, but the name can be different, it doesn't matter as long that file is properly included in the theme in main.php file).

This is required to make lightbox to work. The code that makes it happen (if default lightbox 'Colorbox' is included):

$(document).ready(function() {
    jQuery('.ipWidget-IpImageGallery li a, .ipWidget-IpImage a').colorbox({
        rel:'ipwImage',
        maxWidth:'90%',
        maxHeight:'90%'
    });
});

You may use your own styles for the lightbox or use one of the 5 default ones. Just add the code in your theme's main.php file and change number "2" to anything from 1 to 5.

<?php $site->addCss(BASE_URL.LIBRARY_DIR.'js/colorbox/themes/2/colorbox.css'); ?>

Installation

To make theme installable from the "Administrator > Theme" tab with just one click it must contain /install/ folder with such files in it:

parameters.php - contains system parameters. Minimum the dimensions for all images.
theme.ini - defines version, title, and Doctype for the theme.
thumbnail.png - small screenshot (160px wide and 124px height) that will appear on theme selection page.
preview.png - optional. Should be full scale screenshot.

File - parameters.php

System file that contains all required parameters for the theme. If you add extra parameters that will be used only by this theme, put it in self defined parameter group (for example, the same as theme name).

Below is the example for adding translatable tagline for website (all 4 lines adds one parameter):

        $parameterTitle["standard"]["configuration"]["your_theme"]["tagline"] = "Tagline";
        $parameterValue["standard"]["configuration"]["your_theme"]["tagline"] = "Website tagline";
        $parameterAdmin["standard"]["configuration"]["your_theme"]["tagline"] = "0";
        $parameterType["standard"]["configuration"]["your_theme"]["tagline"] = "lang";

The minimum source should define the dimentions of images. It will tell the system upon installation how to recrop all image files. Those parameters are:

    // Widget: IpImage
    $parameterValue["standard"]["content_management"]["widget_image"]["width"] = "540"; // content
    $parameterValue["standard"]["content_management"]["widget_image"]["height"] = "342"; // content
    $parameterValue["standard"]["content_management"]["widget_image"]["big_width"] = "800"; // lightbox
    $parameterValue["standard"]["content_management"]["widget_image"]["big_height"] = "600"; // lightbox

    // Widget: IpImageGallery
    $parameterValue["standard"]["content_management"]["widget_image_gallery"]["width"] = "160"; // content
    $parameterValue["standard"]["content_management"]["widget_image_gallery"]["height"] = "100"; // content
    $parameterValue["standard"]["content_management"]["widget_image_gallery"]["big_width"] = "800"; // lightbox
    $parameterValue["standard"]["content_management"]["widget_image_gallery"]["big_height"] = "600"; // lightbox

    // Widget: IpLogoGallery
    $parameterValue["standard"]["content_management"]["widget_logo_gallery"]["width"] = "160";
    $parameterValue["standard"]["content_management"]["widget_logo_gallery"]["height"] = "160";

    // Widget: IpTextImage
    $parameterValue["standard"]["content_management"]["widget_text_image"]["width"] = "300"; // content
    $parameterValue["standard"]["content_management"]["widget_text_image"]["height"] = "600"; // content
    $parameterValue["standard"]["content_management"]["widget_text_image"]["big_width"] = "800"; // lightbox
    $parameterValue["standard"]["content_management"]["widget_text_image"]["big_height"] = "600"; // lightbox

Write a comment

You must be logged in to comment.

Documentation 2.x and 3.x