Note

You are viewing the documentation for an older release of Interworx (6.x). To see documentation for the current generally available release of Interworx, click here: 7.13.

Branding Guide

Preface

This document is for web hosts, resellers, and anyone else that wants to customize the look and feel of the InterWorx web interface. Some knowledge of HTML and CSS are required for this guide to be helpful. This document will guide you step by step in creating a custom theme for your InterWorx installs. Custom themes can e used for re-branding the system for your customers, or just to create a custom look and feel.

Creating a Custom Theme

Overview

InterWorx ships with a handful of themes that you can choose to base your custom theme on. The main “InterWorx” theme is the master theme, and all other themes that InterWorx ships with are based on that theme. Since new versions of InterWorx can include new features, and therefore, new interfaces, we have designed the theme system to be “upgrade proof”. That is to say, properly created custom themes will require no updating when new versions of InterWorx are installed.

Creating a new theme involves the following steps:

  1. Choose which existing theme you will base your new theme on.

  2. Download the theme selected in step 1.

  3. Extract the downloaded theme.

  4. Edit the theme’s manifest.txt file (this is how you specify this is a new theme).

  5. Make your modifications to the images, CSS, and/or template files.

  6. Compress your new theme back into a .zip file.

  7. Upload your new theme.

  8. Test your customizations.

Theme Components

Every theme is comprised of several important elements. Customizing your new theme is simply a matter of changing some aspects of the following elements:

Element

Location

Role

CSS Files
/nodeworx/theme.css
/siteworx/theme.css

The NodeWorx CSS files is heart of your theme. Loaded after the base CSS, it’s the place to go to for creating a custom look. SiteWorx will loads both theme.css files therefore the /siteworx/theme.css can be empty.

Images
/nodeworx/images
/siteworx/images

Folders containing images. SiteWorx specific images may go in the SiteWorx images folder, but will have to be referenced from the SiteWorx theme.css.

Template Files
/nodeworx/*.tpl
/siteworx/*.tpl

Framework of the theme.

Manifest File

/nodeworx/manifest.txt

Describe the theme and makes it recognizable to InterWorx.

Choosing a “base theme” for your new theme

In order you decide which theme you’ll base your new theme on, you’ll want to look at the existing themes, and decide which one looks like a good starting point for your customizations. You can preview the installed themes by navigating to NodeWorx SpecialChar menuseparatorThemes in the NodeWorx admin or Reseller interface. Once you select your base theme, you can move on to the next step.

Download the base theme

Downloading the base theme is as simple as navigating to NodeWorx > Themes, and clicking the “Download” link next to the theme you want to grab. Your browser will initiate the theme download process. The downloaded file will be a .zip compressed file.

Extract the downloaded theme

Once the theme archive has been downloaded, you need to extract it, using your OS’s supported “unzipping” method. Extract the file to an easy to access location, like your Desktop. When you extract the file, you will see two folders, one named nodeworx, and the other siteworx.

Edit the manifest.txt file

Inside the nodeworx directory of the extracted theme archive, you will find a file named manifest.txt. This is the file that contains the data about the theme, and in order to start making your new theme, you need to edit it, using a text editor of your choice. The table below details the various parts of the manifest.txt file.

Directive

Purpose

Required?

[vanillaice]

This is the “system name” of your theme. This must be unique to the system, alphanumeric, and contain no punctuation or spaces. You should change this value.

YES

name

This is the display name shown on the Themes page and in the dropdowns for selecting themes. You should change this value.

YES

author

This is the person who created the Theme, obviously in this case it would be you. You should change this value.

NO

hd_left_url

Link used when clicking on the logo image at the top left.

YES

hd_right_url

Link used when clicking on the logo image at the top right.

YES

help_url

Link used when clicking the Help link.

YES

base_theme

This is the system name of the theme that your theme is based on. This is not in the InterWorx theme, since it is the root theme for all others. If you are basing your theme on the InterWorx theme, you MUST add this section to the manifest.

YES

branding_interworx

The content of this optional parameter will be used to replace the word InterWorx in the HTML output for your theme.

NO

branding_siteworx

The content of this optional parameter will be used to replace the word SiteWorx in the HTML output for your theme.

NO

branding_nodeworx

The content of this optional parameter will be used to replace the word NodeWorx in the HTML output of your theme.

NO

version=2

This is a required parameter. It instructs InterWorx to use the new theme format after themes were changed in an older InterWorx version. DO NOT DELETE THIS LINE OR CHANGE THE VERSION.

YES

Here is the contents of /nodeworx/manifest.txt from the Heliotrope theme.

[heliotrope]
name=Heliotrope
author=InterWorx L.L.C.
base_theme=interworx
hd_left_url=http://www.interworx.com
hd_right_url=http://www.interworx.com
help_url=support.php
description=The original purple theme.
type=public
version=2

Customize Your Theme

Changing the Logo images (simple version)

The simplest form of customization is to replace the InterWorx logo and SiteWorx/NodeWorx logos with your own. In each theme, there are two images for NodeWorx and two for SiteWorx that are the logos used in the headers. These are hd_left.gif and hd_right.gif. Simply edit or replace these images with your own (must be .gif format) and edit the manifest file before uploading your new theme.

Changing the Logo images (advanced version)

Another possibility is to use a different file entirely, and not convert to .gif. This lets you use higher-resolution images, such as PNG or JPG.

  1. Put your new image in /nodeworx/images

  2. Open /nodeworx/header.tpl

  3. Find hd_left.gif or hd_right.gif

  4. Replace with your new image name

  5. Repeat for SiteWorx, if desired

Note that the header and footer are not rendered as part of the csstest.html (see below) file included with the download. You’ll need to complete your theme and upload it before you’ll be able to see the differences.

Changing the Colors and Graphics

All colors and graphics other than the header logos are assigned and positioned using CSS. Use of the Firefox plugin Firebug is highly recommended, since it makes testing CSS changes instantly preview-able. To customize your theme, the best place to start is the NodeWorx theme.css. Any changes to SiteWorx specifically should be made in the SiteWorx theme.css.
The Firefox plugin Firebug is Highly Recommended

The Firefox plugin Firebug is Highly Recommended

Modifying CSS

If you’re not looking to spend too much time working on your theme, modifying the CSS is the way to go. Pop open /nodeworx/theme.css and start editing. If you’re looking to see your CSS changes in action, open csstest.html in a browser.

Modifying template files

InterWorx is built on top of Smarty Template Framework. If you choose not to include some of these theme files in your theme, InterWorx will automatically fall back to the base theme’s files. Moving {smarty} tags around in your .tpl files will give you more control over what elements should go where.

Template File Name

Purpose
/nodeworx/main-template.tpl
/siteworx/main-template.tpl

These are the main template files for both NodeWorx and SiteWorx for when a user is logged in.
/nodeworx/index.tpl
/siteworx/index.tpl

These are the template files for the login screen and other misc areas of SiteWorx and NodeWorx.
/nodeworx/theme-assests.tpl
/siteworx/theme-assests.tpl

Here is where you add javascript and CSS files for inclusion in your theme. You can add them in the had of tthe main-tempalte.tpl instead, but they won’t be parsed and minified by InterWorx. Make sure to read up on Adding Javascript below.
/nodeworx/widgets/
/siteworx/widgets/

Various elements that are used throughout the control panel have been added to the respective widget folder. These elements will fall-back to the .tpl files located in the base theme.

/widgets/box-message.tpl

This file controls the various top-level error messages seen through InterWorx control panel.

/widgets/box-status.tpl

This file controls the various sub-level error messages seen throughout InterWorx Control Panel.

/widgets/link-action.tpl

This file controls the structure of most buttons seen throughout InterWorx Control Panel.

/widgets/link-quickhelp.tpl

This file controls the structure of any quickhelp link [?] seen throughout InterWorx Control Panel.

/widgets/graph.tpl

This file controls the structure of any graph seen throughout InterWorx Control Panel.

Using csstest.html to preview changes

In the /nodeworx/ folder of the download, you’ll find an html file called csstest.html. This file has been specifically altered to work from your local machine, so that you can test some base elements of your custom theme without the trouble of zipping up your changes and uploading them repeatedly. You can also access csstest.html after your theme has been uploaded by pressing [Preview].
Using csstest.html to preview changes

Using csstest.html to preview changes

Update the Thumbnail

In the /nodeworx/images/ folder, there is an image called thumbnail.jpg. This image is used to show a preview of your theme on the Theme Management page. The image will ultimately be displayed at 320x262 (roughly 25% of 1280x1024) so that’s the best size for the least distortion. Also included in the nodeworx directory is a file named “csstest.html”, which you can use with a web browser to preview your customizations.

Update the Thumbnail

Update the Thumbnail

Finalizing and Uploading Your New Theme

Now, you’ve edited the style sheet and the images according to your preference. For the most part, you’re finished making your theme. Now you need to zip the folders up and upload them.

Zip Your Theme

  1. Select the siteworx and nodeworx folders on your desktop.

  2. Right click on one of them and you should see the option “Send To”. Select this option and then you should see “Compressed (zipped) folder”. Select this option and in a couple seconds, you should see a file on your desktop called siteworx.zip or nodeworx.zip depending on which one you right clicked on.

  3. Rename this file to whatever you named your theme.

Upload Your Theme

  1. Click the NodeWorx menu item if it is not already open.

  2. Click the Themes menu item.

  3. A list of themes is shown.

  4. Click the [Add Theme] link. You will be redirected to a page with an upload box.

  5. Click the button to locate the zip file on your computer.

  6. Click the button to begin the upload of your theme.

  7. You will see the following message at the top of the screen: Theme Added Successfully.

Upload Your Theme

Upload Your Theme

Select Your Theme

  1. Click the Icon NodeWorx menu item if it is not already open.

  2. Click the Icon User Accounts menu item.

  3. A list of users is shown.

  4. Click the [Edit] link for the current user (you).

  5. Use the Theme: dropdown to choose the theme for the user.

  6. Click the [Save] button to save the change.

  7. InterWorx Control Panel will refresh and you will see your chosen theme.

That’s it! Assuming you’re happy with how the theme looks, it is now ready for use on an InterWorx server you install it on.