InterWorx Branding Guide

by InterWorx LLC

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.

1 Creating a custom theme

1.1 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.

1.2 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
figure images/icons/file_extension_css.png
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.
figure images/icons/sitemap_image.png
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.
figure images/icons/file_extension_tpl.png
Template Files
/nodeworx/*.tpl, /siteworx/*.tpl Framework of the theme.
figure images/icons/file_extension_txt.png
Manifest File
/nodeworx/manifest.txt Describes the theme and makes it recognizable to InterWorx.

1.3 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  ▷ Themes in the NodeWorx admin or Reseller interface. Once you select your base theme, you can move on to the next step.

1.4 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.

1.5 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.

1.6 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

2 Customize your theme

2.1 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.

2.2 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.

2.3 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.
figure images/branding/firebug.jpg
Figure 2.1 The Firefox plugin Firebug is Highly Recommended

2.3.1 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.

2.3.2 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
figure images/icons/file_extension_tpl.png
/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.
figure images/icons/file_extension_tpl.png
/nodeworx/index.tpl
/siteworx/index.tpl
These are the template files for the login screen and other misc areas of SiteWorx and NodeWorx.
figure images/icons/file_extension_tpl.png
/nodeworx/theme-assets.tpl
/siteworx/theme-assets.tpl
Here is where you add javascript and CSS files for inclusion in your theme. You can add them in the head of main-template.tpl instead, but they won’t be parsed and minified by Interworx. Make sure to read up on Adding Javascript below.
figure images/icons/folder.png
/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.
figure images/icons/parent.png
/widgets/
figure images/icons/file_extension_tpl.png
box-message.tpl
This file controls the various top-level error messages seen throughout Interworx Control Panel.
figure images/icons/parent.png
/widgets/
figure images/icons/file_extension_tpl.png
box-status.tpl
This file controls the various sub-level error messages seen throughout Interworx Control Panel.
figure images/icons/parent.png
/widgets/
figure images/icons/file_extension_tpl.png
link-action.tpl
This file controls the structure of most buttons seen throughout Interworx Control Panel.
figure images/icons/parent.png
/widgets/
figure images/icons/file_extension_tpl.png
link-quickhelp.tpl
This file controls the structure of any quickhelp link [?] seen throughout InterWorx Control Panel.
figure images/icons/parent.png
/widgets/
figure images/icons/file_extension_tpl.png
widget-graph.tpl
This file controls the structure of any graph seen throughout InterWorx Control Panel.

2.3.3 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].
figure images/branding/csstest.jpg
Figure 2.2 Using csstest.html to preview changes

2.4 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.
figure images/branding/thumbnail.jpg
Figure 2.3 Update the Thumbnail

3 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.

3.1 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.

3.2 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.
figure images/branding/upload.jpg
Figure 3.1 Upload Your Theme

3.3 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.

(C) 2017 by InterWorx LLC