Welcome to the Tweak template documentation. This resource was created to help you develop your own website templates and import them into the Tweak Content Management System. You may also want to view and print our cheat sheet for quick reference.
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.
Referencing Images and Other Resources
Tweak needs just a little bit of help knowing where you're 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 template you'd set the src attribute like this:
<img src="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 the 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/
Organizing Your CSS
Feel free to organize your style sheets however you'd like. We've included a recommendation in the appendix based upon our experience if you're looking for ideas. If you have any feedback on our suggested method, feel free to contact us.
Controlling the CMS Editor Styles
The Tweak CMS uses a powerful Java applet to facilitate WYSIWYG editing of web page content. We refer to this applet as "the editor." 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.
1. Add style definitions to any of the style sheets that are prefixed with body#elj. For example, these styles will set the editor background to white and the paragraph text to black:
body#elj { background-color: #ffffff; }
body#elj p { color: #000000; }
2. Create a new style sheet and prefix the filename with "elj_" like "elj_styles.css." When this is done the editor will only use style sheets prefixed with "elj_" and will ignore all other CSS files.
Note that the editor doesn't allow shorthand notation for hex colors (#fff), but requires normal 6-character notation (#ffffff).
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. 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. The Tweak CMS currently supports up to 3 page-specific content areas per page.
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>
Reusable-content areas
If the block of content is something like a footer or quote that shows up on several or all of the pages of the website, the containing block level element should have an id of reusablecontentarea for the first, reusablecontentarea_2 for the second ... to reusablecontentarea_n.
An example of a reusable-content area would be coded like this:
<div id="reusablecontentarea"><p>Lorem ipsum dolor sit amet.</p></div>
The system will attempt to import the content within the element having an id of reusablecontentarea and will automatically create a content block with this content. If you create a reusable-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 reusable-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 reusable-content areas.
A reusable-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 reusable-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 of news. 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.
Appendix
Support
For further assistance please call Agency Fusion at (801) 303-1591 or contact us online.
Suggestions
We welcome any and all suggestions, feedback, etc. Please don't hesitate to call or contact us with comments or suggestions!
Recommended CSS-Organization
In addition to using the YUI reset.css and fonts.css, we suggest a 4-file method for organizing your CSS info.
Base.css
This is a CSS file that describes how all standard tags should behave by default. Anything that requires a special class or ID should be placed in a separate file. Visit http://www.tweakcms.com/samples/css/base.css for an example base.css file. The following elements should be styled in your base.css file:
- body
- h1, h2, h3
- p
- a, a:hover
- ul, li
- hr
- div
- input
- select
Layout.css
This is a CSS file that describes how the pieces of the layout should be positioned and displayed. Think of this file as the place to define where the building blocks of your site go or all of your positioning stuff.
Nav.css
This is a CSS file that defines navigational styles. Since there are usually a fair number of styles needed to define a site's navigation, we've found it helpful to split them out into a separate file.
Content.css
This is a CSS file that defines pretty much everything else you need. We typically reference this style sheet last so that it can inherit from the other style sheets, especially from the base.css file and override when necessary.
On large, complicated sites, we'll often break the content.css file into smaller pieces. For example, a site with a heavily-styled press section might have a press.css file that contains styles specific to press releases.
The main objective here is to establish a convention that you'll follow on every website you build. We've found that this approach gives us some organizational benefits and allows our developers to easily work on projects for which they weren't the original coder.