Themes Documentation
Welcome to the Tweak themes documentation. You may also want to view and print our developer cheat sheet for quick reference. Our templating overview video is another helpful resource on this topic.
General Template Guidelines
A Quick Overview
The Tweak CMS allows designers and developers to create and import templates without learning a proprietary templating language or using a set of weird tags. Our system recognizes the CSS classes or IDs that you use instead. In this way, we’re making it possible to take valid XHTML templates (created either by hand or using a software tool) and import them into the CMS.
Creating a Theme to Upload
Tweak lets you upload your XHTML, CSS, JavaScript, and template-related images as a theme. This allows you to have more than design loaded for a single site and to switch between them by selecting the desired theme.
Uploading a theme simply involves creating a .zip file containing your XHTML, CSS, JavaScript, and images. The expected file/folder structure in your .zip file is as follows:
/ (root folder contains your .html files and theme_thumbnail.gif file)
--/cmsimages
--/cmscss
--/cmsjs
In either the root folder or the cmsimages folder of your theme you can include a screenshot of your theme called theme_thumbnail.gif. We recommend making the screenshot about 500px wide.
We recommend only including images that are part of the theme. Images that are used in the actual content should be uploaded into the image library so that they're available the user. Theme images are not shown in the user's image library.
Referencing Images and Other Resources
Tweak needs just a little bit of help knowing where your images, CSS files, and JS files are going to be located. We’re working on making the CMS more friendly to the folder names you already use, but in the meantime to make the import process smooth, use the following folder names:
Images - cmsimages/
CSS files - cmscss/
JS files - cmsjs/
For example, to reference an image in your HTML template you'd
set the src attribute like this:
<img src="cmsimages/myimage.jpg" />
Because the cmsimages folder and the
cmscss folders are siblings, to reference an image
from within your CSS file you'll need to set the image path like
this:
../cmsimages/myimage.jpg
Template Validation
Before uploading a template into the Tweak Content Management System, please ensure that the markup conforms to either the “XHTML transitional” or “XHTML strict” standard. While the transitional standard is adequate, we strongly encourage you to conform to the XTHML strict standard whenever possible.
The W3C provides a free markup validator at the following website. The validator will accept either a file upload or a URL.
In order to validate, your template will need to include one of the following DOCTYPE declaration statements. If you fail to provide a DOCTYPE declaration, the CMS will default to XHTML transitional.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
Nesting of Elements
Please note that the current version of the CMS does not support nesting of editable areas. For example, a navigation element cannot be nested inside of a main content area element.
Creating a Template
This section explains the actual code and tags that will make your templates work with Tweak CMS.
Metadata
The following metadata elements are supported in the
<head> section of your XHTML template.
Title
The following snippet shows an example title tag. Note that no text is required between the tags; any title text provided will be ignored because the CMS will insert the appropriate values for you on a page-by-page basis.
<title></title>
Content Type
The following snippet shows an example content-type meta tag.
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
Description
The following snippet shows an example description meta tag. Note that the content attribute is blank. On a page-by-page basis, the CMS will insert the appropriate value in this attribute.
<meta name="description" content="" />
Keywords
The following snippet shows an example keywords meta tag. Note that the content attribute is blank. On a page-by-page basis, the CMS will insert the appropriate value in this attribute.
<meta name="keywords" content="" />
CSS
The following sections outline suggestions for referencing and organizing your CSS files.
Referencing CSS Files
We recommend placing all styles in an external .css file or
files. There are two ways to reference your CSS files. We recommend
referencing them in the <head> section of your
markup using this syntax:
<style type="text/css" media="all">
@import url(cmscss/reset.css);
@import url(cmscss/fonts.css);
</style>
This allows "blocks" of style sheet imports based on media type. We also recommend that you provide styles for print media.
Alternatively, you can reference your CSS files in this more-commonly used method.
<link rel="stylesheet" href="cmscss/reset.css" type="text/css" />
We recommend using the reset.css and fonts.css from the YUI (Yahoo! User Interface library) and following the guidelines for using fonts.css provided by the YUI.
For more information on the YUI, visit: http://developer.yahoo.com/yui/
Controlling the CMS Editor Styles
The Tweak CMS uses a powerful JavaScript editor to facilitate WYSIWYG editing of web page content. The editor makes it possible for content contributors to create and edit pages without learning HTML.
The editor has access to the CSS files you upload and will apply your styles to the content being created by the end-user. There are instances, however, where you may want to define styles that are used only within the editor’s preview window.
You can define styles that are specific to the WYSIWYG editor in one of two ways.
-
During editing, an ID of "editor" is added to the body element, making this syntax possible for defining editor-specific styles:
body#editor. For example, these styles will set the editor background to white and the paragraph text to black, but will have no effect outside the editor:body#editor { background-color: #ffffff; } body#editor p { color: #000000; } -
Create a new style sheet and prefix the filename with
editor_likeeditor_styles.css. The editor first looks for any style sheets prefixed witheditor_and, if found, will ignore all other CSS files.
Navigation
Tweak is extremely flexible when it comes to creating custom navigation. The following sections show various methods for building navigation to support your design. Using the classes or ids listed below will allow Tweak to make your website's navigation completely dynamic which means users can add, modify, or remove pages in the CMS and the website will update accordingly.
Main Level Navigation
This navigation provides the top-most level of links. As an
example, this level of navigation is often shown across the top of
a webpage. This navigation is denoted by using a class or id with a
value of navtop or nav_level1.
The following code block illustrates markup for a standard main navigation with 4 links, one of which is the current page.
<ul id="navtop">
<li class="first"><a href="">Home</a></li>
<li><a href="">Products</a></li>
<li class="selected"><a href="">Services</a></li>
<li class="last"><a href="">About Us</a></li>
</ul>
Secondary Level Navigation
This navigation shows the links beneath a given main nav item or within a given section of the site. For example, if you want to show a left-hand navigation that contains subpages for the currently selected main navigation link, use this type of navigation.
This navigation is denoted by using a class or id with a value
of navsub or nav_level2.
Child Navigation
The navigation that is used to show the pages
“underneath” the current page. This navigation is
denoted by using a class or id with a value of
navchild.
Sibling Navigation
The navigation that is used to show links to the pages that
share the same parent page. This navigation is denoted by using a
class or id with a value of navsibling.
Next/Prev Navigation
This navigation is used to create links that move a user through
a sequence of pages, like in a “wizard” or a
“slideshow.” The anchor tag for the
“previous” link should be classed or ID’d with
previouspage and the anchor tag for the
“next” link should be classed with
nextpage.
Website navigation should be built using unordered lists where
possible. The class or id of the unordered list should be one of
the types above. To allow the CMS to properly recognize your
navigation, please include least 3 items in your list. The first
should have a class of first while the last should
have a class of last. The second item should be an
example of a “standard” item.
Note: Tweak requires that every “node” or element in your navigation have an actual <a href> element. Tweak doesn’t allow you to include a node that is purely for organizational benefit (like having the main button/link not active but a drop-down of options below it).
If you want to show an on-state or have a unique style for the
currently-selected pate, add a 4th item to your list and use a
class of selected should be used on the appropriate
list item.
Crumbtrail
Many sites feature a crumbtrail or breadcrumb navigation option. The crumbtrail provides the user with a way to navigate back toward the home page from the current page.
Creating crumbtrail navigation may include several of the following components.
Container
This required element identifies your crumbtrail navigation.
Style a <div> or a <span>
with a class or id value of crumbtrail to create your
container.
Label
This optional element defines the text which will precede the
actual crumbtrail links. Style a <span> with a
class or id value of crumbtrail to create your
container.
Previous Links
These required elements are the hyperlinks that allow the user
to navigate back toward the home page. Style an
<a> tag with a class value of
previous.
Separator
This required element defines the separator between each link.
Style a <span> tag with a class of
separator and include the separator character or code
between the open and closing <span></span>
tags.
Current Page
This optional element styles the text for the current page,
usually the last item in the crumbtrail, which indicates to the
user their position in the website relative to the previous links.
Style a <span> tag with a class value of
current.
An example website crumbtrail navigation might look something like:
Location: Home > Support > Contact Form
In this example, the "Location:" text would be considered the label while the links leading to the current location would be the "previous links." The ">" character is the separator and the "Contact Form" text is the current page.
The code to create the above example would look like:
<div id="crumbtrail">
<span class="label">Location: </span>
<a class="previous" href="">Home</a>
<span class="separator"> > </span>
<a class="previous" href="">Support</a>
<span class="separator"> > </span>
<span class="current">Contact Form</span>
</div>
Content
The content of a page is generally the body copy or the main
editable area of the page. Any block of content on a page should be
contained in a block level element like a <div>
or <p>. We currently support two types of
content areas within a template.
Page-specific content areas
For blocks of content that are specific to one page, the
containing block level element should have an id of
content for the first, content_2 for the
second, and content_3 for the third. Tweak allows you
to use as many editable content areas as needed.
Using more than one content area allows you to place several blocks of content within your layout and locate each block wherever desired. An example of two page-specific content areas stacked one above the other would be coded like this:
<div id="content">Lorem ipsum dolor sit amet.</div>
<div id="content_2">Proin pretium eros nec augue.</div>
When using multiple class values in a single class attribute, be sure to place the Tweak class first in the list like this:
<div id="content another_class_here">Lorem ipsum
dolor sit amet.</div>
Global Content Areas
If the block of content is something like a footer or another
piece of content that you wish to repeat across all pages using a
given template, the containing block level element should have an
id of globalcontent for the first,
globalcontent_2 for the second ... to
globalcontent_n.
We use the term "global" to indicate that one piece of content will be used globally across all pages using the template in question. It may be helpful to think of these like "includes" that are typically used in server-side programming to accomplish a similar objective of including one bit of code on many pages.
An example of a global content area would be coded like this:
<div id="globalcontent">Lorem ipsum dolor sit
amet.</div>
When using multiple class values in a single class attribute, be sure to place the Tweak class first in the list like this:
<div id="globalcontent another_class_here">Lorem
ipsum dolor sit amet.</div>
The system will attempt to import the content within the element
having an id of globalcontent and will automatically
create a content block with this content. If you create a
global-content block for a footer, for example, and insert some
copyright text, the copyright text will be used as the default
content block for that global-content area. Note that to
successfully import this content as the default content block the
content itself should be in a container element, as shown in the
example.
This allows the user to create and manage a block of content once and reuse it across many pages, rather than copy and paste the same content on every page. The Tweak CMS supports an unlimited number of global-content areas.
A global-content area differs from a standard content area in that a user doesn’t insert content on a page-by-page basis using the WYSIWYG editor. Instead, the user will choose a pre-made block of content to be used in the selected content area. The user can create new blocks of content or modify existing blocks. If a content block is edited, it will change every page that features that content block.
As additional explanation, a global-content area is a container defined within a template which accepts content blocks rather than just free-form content created by the user.
News Listings
Tweak allows you to create a news section in which the end-user can highlight certain pages on the website. The user can check a box on each page (using the Edit Page Properties feature) to indicate that the selected page should be included in the news items list. This is helpful for providing a list of links, on the home page for example, to full articles, news releases, press releases, etc. Although the feature was designed for news information, it can be used for a number of other things, such as:
- A “shortcuts” list on the home page which links to frequently used pages
- A “current jobs” listing where new job openings are highlighted
- A list of links to new press releases or other content that changes often
The outermost news element or container must have a class or id
ofnews. A single, repeatable element such as an
<li> or <div> should be
created and should contain an anchor and a summary. A class of
title must be on the anchor or its containing element.
There can be as many tags wrapped around the final summary element
as you want.
Example code for creating a list of news items is as follows:
<div id="news">
<div>
<a href="" class="title">First news title will go here</a>
<p class="summary">
This will be the summary for the first news item.
</p>
</div>
<div>
<a href="" class="title">Second news title will go here </a>
<p class="summary">
This will be the summary for the second news item.
</p>
</div>
</div>
Alternatively, news items could be coded with an unordered list
as shown in this example. Note that the title class
can be placed on either the anchor or its containing element.
<ul id="news">
<li>
<p class="title">
<a href="">First news title will go here</a>
</p>
<div class="summary">
This will be the summary for the first news item.
</div>
</li>
<li>
<p class="title">
<a href="">Second news title will go here</a>
</p>
<div class="summary">
This will be the summary for the second news item.
</div>
</li>
</ul>
Other Elements
Several other user-editable elements are currently supported by the CMS.
Page title
To have the CMS insert the current page's title (as set by the
user in the CMS), create an element with a class or ID of
pagetitle. The page title can be edited by the user in
the "page properties" screen for any page in the CMS.
Site name
To have the CMS insert the name of the website (as set by the
user in the CMS), create an element with a class or ID of
sitename. The site title can be edited by the user in
the "site preferences" screen in the CMS.
Page description
To have the CMS insert the page description (as set by the user
in the CMS), create an element with a class or ID of
description. The page description can be edited by the
user in the "page properties" screen for any page in the CMS.
Page Image
To have the CMS insert the page image (as set by the user in the
CMS), create a container element with a class or ID of
pageimage that contains an image tag/element inside.
The image source and alt text will be automatically filled in by
the CMS.
Using CDATA Blocks
Because Tweak leverages XML, there are a few situations in which you'll need to use a CDATA section to make sure your template gets processed correctly. If you're unfamiliar with using CDATA, you can read more at the W3 Schools page on CDATA.
- Any comments in your code will be stripped out during import
unless you wrap them in a CDATA section.
- JavaScript
<script>blocks that wrap content in comments will have content stripped out - Any PHP/ASP/JSP or other server-side code should be wrapped in a CDATA section.
Here is an example of how to use a CDATA section to preserve a JavaScript block that contains old-school comments:
<![CDATA[
<script type="text/javascript">
<!-- old school comment
myfunction()
{
alert("Hello World!");
}
//-->
</script>
]]>
Appendix
Support
For further assistance please post a question in our online support forum. Our templating overview video is also a helpful way to learn about creating templates and themes.
Suggestions
We welcome any and all suggestions, feedback, etc. Please don’t hesitate to call or contact us with comments or suggestions!