JoomlaXTC Template Framework Guide

Introduction

The XTC Framework provides simple yet powerful template creation tools that allows developers to rapidly build or change every aspect of template elements and its administration panel and provide final users with easy and familiar controls to configure the template.

Among its features are:

Multiple Layouts

Layouts define the overall location of elements in the template, they can have their own set of style, typography or any other CSS Parameter Groups. Also they can have their own custom parameters for added functionality such as custom code, Javascript calls, etc.

Support for one or multiple layouts each one with its own set of parameters. Switch your entire site look in two clicks!
Layouts can share the same module position names or have custom ones for increased flexibility.
Support mobile devices.
Creating a new layout is as easy as copying the current one into another folder!
PHP-based layout code allows any kind of customization or logic to be used
Intelligent Grid rendering with standard Joomla! jdoc calls is available for easy placement of content areas
The grid engine creates automatic CSS classes for easy styling: Need to edit the header of the bottom module in the first column of region3? CSS is as easy as: #region3 .firstcolumn .lastarea h3 {}
Use region-based layouts with selectable region display order
Easily switch column display order within a region
From simple to advanced template layouts, the choice is yours!

Style Groups

XTC delivers powerful CSS features to ease the styling of templates. For example, you can combine multiple CSS preset styles to obtain the right look for your site. XTC template CSS can be split in as many groups as needed, each one capable of sharing one or more template parameters to control what you want, and if you need more groups, creating new ones is really simple.

Use Parameters Groups to organize CSS in many ways: Colors and Graphics, Module suffixes, Typography, Menu styling, etc.
Use one CSS file with one or multiple Parameter Groups, or multiple CSS files for each group.
CSS files can be edited from template backend, or use the template.css file to override any other CSS.
Use standard Joomla! elements along with custom elements for easy XML customization
Use PHP code inside CSS files with full access to all parameters for custom styles.
Does not require multiple calls for CSS files to server
Making an extra sets of parameters is as easy as copying one file!

Easy Menus

Three menu modes included by default: Suckerfish, Two-column suckerfish and Drop line, each one selectable as a class in the mainmenu module!

Support list rendering
Automatic CSS classes added for easy styling
MooTools based for total compatibility

Framework Features

Fast, Joomla! API standard
Select which components to show or hide in the frontpage
Include all the CSS as part of the HTML document, as separate files or as a single file with the flip of a switch
Selectable CSS gzip compression for increased throughput
Mark any parameter as "public" to allow their values be set from URL calls
Public parameter values are independent by user/visitor
Customizable CSS for the administation panel
More features are being added!

User's Guide to XTC Framework

The XTC framework provides a flexible and powerful foundation to develop Joomla! frontend templates of any kind, this user guide will explain the basic concepts behind the framework and teach you how to use the administrator parameters available on the Joomla! Template Manager of an XTC template.

Before starting, it is strongly recommended for you to have some knowledge of how standard Joomla! templates work and how are they managed. A good place to start is the Joomla! site itself, click here for more information. Also, knowledge of HTML and CSS is strongly suggested.

One thing to consider is that the parameters can be different from template to template since they are ultimately decided by the template developer in first place, however there are simple rules that apply to all of them.

Layouts and Styles

Joomla! templates (and practically any webpage) are built using the HTML markup language and CSS formatting or styling language. There are several schools of web development but for practical purposes on Joomla! templates we will think of HTML as the way to define where to position the content ("Layout") and the CSS as the way to define how the content will visually look like ("Style").

Layouts

An XTC template can have a choice of multiple Layouts, these can vary in the number of module positions, content areas or any other aspect. Some layouts can be automatically used for specific devices such as mobile phones (read the Developer's Guide for more information). Layout files are stored on their own directory inside the "/layouts" folder of the template.

Styles

Style files contain any CSS required by the Layouts to be properly displayed in a user's browser. Like Layouts, a template may have one or more Style options to choose from, each one intended to control one aspect of the layout formatting. By combining the different Styles available, you can easily customize the appearance of your site with just a few clicks. Styles are composed of two file types: A CSS file stored in the "css" folder and a XML file stored in the "parameters" folder.

Read below for more information about the file structure of the template.

Parameter Groups

The XTC framework provides facilities for both Layouts and Styles to utilize user-managed parameters to enhance their functionality, these parameters are available in the Template Manager of the Joomla! administrator page. In the case of XTC templates, you will have access not only to the regular parameters of the template but also to "Parameter Groups" that control the XTC framework as well. These Parameter Groups carry an identification label on the left side and an arrow icon and title on the right side. You can click on the right side to slide-open each group and see the parameters within (the images shown on this guide are taken from a sample template and do not necessarily reflect the parameters on your template).

Template Manager

There are two types of Parameter Groups: Layout parameter groups and Style parameter groups. An XTC template has only one Layout group that contains the parameters for each layout, however there could be one or more Style parameter groups. The different Style groups help not only to ease the management of parameters but also provide increased flexibility by allowing you to combine them.

This is the hierarchy of parameters in an XTC template:

XTC Hierarchy

There is no limit to the number of layouts or style groups available on an XTC template. In the example shown in the first image, the Layout group has two layouts: Default layout and Mobile layout. Each layout can be configured independently from each other. Notice that the parameters allow you to choose which style to use from each style group below. The hability to configure each Style group individually and being able to choose from them in the layout allows you to change your entire website design with just a few clicks.

The XTC framework uses standard Joomla! parameters for most of the configuration options and although some of them may look similar, their usage can be different depending on their purpose. For example, on some cases you are expected to enter a number while on others you may have to enter a text legend. Please pay attention to the information on parameter tooltips. Move your mouse over the parameter label to see them.

Besides the standard parameters, XTC includes a few additional types that are explained here:

Text Parameter

This parameter can have multiple purposes as it allows you to enter text or number values. Read the instructions on the parameter tooltip to learn if there is any particular format you have to follow when entering information on it.

Column Order

One of the features of XTC Framework is the hability to render Joomla! content in Grids containing one or more columns. This parameter allows you to choose the render order (from left to right) of each column within a given Grid. The parameter displays a list of all the possible options however a column might not be rendered in the template if there is no content for it. For more information on XTC Grids please read the Developer's Guide.

Combobox Parameter

Combines the ease of preset values from a regular drop-down parameter with the ability to type custom values if needed. This parameter also can have multiple purposes as it allows you to enter text or number values. Read the instructions on the parameter tooltip to learn if there is any particular format you have to follow when entering information on it.

Image Selector

Most templates require image files, this parameter allows you to disable or choose from a list of available images. If you place your mouse over the left side of the parameter a tooltip will appear displaying the folder name where the images are located. This folder is placed inside the "/images" folder of your template.

Color Picker

This parameter used for color selection accepts a color input in any valid CSS format, some examples are (without quotes): "#FEB028", "Red", "transparent", "rgb(100%, 0%, 0%)" etc. Also, if you click on the small square at the right of the input field, a graphic color-picker will appear that lets you choose or edit the color value directly. Click on the small dot at the lower-right corner when done.

Framework Parameters

This is a special group of parameters that may or may not be available in your template, their purpose is to control the framework internal system. Read below for a description of each option.

Color Picker

CSS Mode

This controls how the CSS code will be generated for the template:

Single File: All the CSS code will be generated on a single file, this reduces the number of HTTP requests to the server thus reducing the page load time. It is the recommended setting.
Separate Files: CSS code will be generated in files per Style Group. This causes multiple HTTP requests to the server but also helps the debug process during template development as you can see the CSS source code for each individual Style Group.
Head Embedding: The CSS code will be embedded in the HEAD element of the template. This avoids HTTP requests for template CSS however the page source code will be much bigger.

CSS Compression

This parameter enables or disables GZip compression of the CSS code reducing transmission time at the expense of minimal server load. Most modern browsers are capable of using this feature. CSS compression is only available in "Single File" and "Separate Files" CSS modes.

Component Display

On certain scenarios, you might want to control the display of Joomla! components in the frontpage of your site. This parameter allows you to decide which of the installed components will be allowed to be shown in the frontpage. Select the "ALL COMPONENTS" option to enable any component, or choose one or more components from the list (press the CTRL key for multiple selection).

Menu Effects and Styling

By default XTC framework provides special styling enhancements and sliding animation effects support for three menu types: Suckerfish, Two-column Suckerfish and Dropline. To apply these effects to any menu in your system you just have to change a few parameters in the "mod_mainmenu" module assigned to render the menu. For example, the image below shows the parameters of a "mod_mainmenu" module that will display the options from the "mainmenu" menu in the module position identified as "top":

Menu Module

To use the animation and styling enhancements, the settings of the module should be as follows:

"Menu Style" = List
"Always show sub-menu Items" = Yes
Menu Class Suffix: Choose from " suckerfish", " dualfish" or " dropline" options. Enter the value with no quotes and a leading space.
Module Class Suffix: This is an optional CSS class of your choice applied to the module HTML and could be useful for styling

After the changes are done, click on the Save or Apply buttons. The module will now start to behave as desired.

Styling the menus

In order to change the visual appearance of a menu you must first get familiar with their structure. The "List" menu style will render the menu structure using a common "nested list" format. For example, the HTML code for a menu with three main options and a submenu with another three options will look like this:

<ul>
   <li>
      <a href="#">Menu option 1</a>
   </li>
   <li>
      <a href="#">Menu option 2</a>
      <ul>
        <li><a href="#">Submenu option 1</a></li>
        <li><a href="#">Submenu option 2</a></li>
        <li><a href="#">Submenu option 3</a></li>
      </ul>
   </li>
   <li>
      <a href="#">Menu option 3</a>
   </li>
</ul>

Besides this basic structure, List menus on XTC have aditional HTML code and CSS classes added to facilitate custom styling, the complete HTML code for a Suckerfish menu is similar to this:

<ul class="menu suckerfish">
   <li class=" first order1">
      <a><span>Menu option 1</span></a>
   </li>
   <li class="parent center order2">
      <a><span>Menu option 2</span></a>
      <ul>
         <li class=" first order1">
            <a><span>Submenu option 1</span></a>
         </li>
         <li class=" center order2">
            <a><span>Submenu option 2</span></a>
         </li>
         <li class=" last order3">
            <a><span>Submenu option 3</span></a>
         </li>
      </ul>
   </li>
   <li class=" active last order3">
      <a><span>Menu option 3</span></a>
   </li>
</ul>

Notice how the main

/* Top Level */
ul.menu > li.active > a { background:#ffffff;color:#999999; }
ul.menu > li > a { font-weight:normal; background:#ffffff; color:#999999; }
ul.menu > li > a:hover { background:#ffffff; color:#bbbbbb; }

/* Drop Levels */
ul.menu li.parent > ul { background:#5399b7; }
ul.menu li.parent > ul > li { background:#000000; }
ul.menu li.parent > ul > li > a { border-bottom: 1px solid #65a3be; font-size:11px; color:#bad6e2; }
ul.menu li.parent > ul > li.active > a { color:#bad6e2; }
ul.menu li.parent > ul > li > a:hover { font-size:11px; color:#ffffff; }

As you can see, styling is separated in two main groups, the first group has the visual formatting of the options show in the first level of options, while the second group defines the appearance of any option in a submenu. The code above contains only appearance formatting and most of the time it is what you will be interested in (the necessary code for the menu structure is already built for you on the template "default.css" file and does not need to be changed).

Of course, you are free to use any CSS formatting code you desire. As a best-practice, the recommended place to store all your custom CSS code is the "template.css" file located in the "css" folder. This file is available for editing from the Template Manager screen by cliking on the "Edit CSS" button at the top. Please continue reading for a detailed description of the files included in an XTC template.

XTC File Structure

Layouts

config.xml: This file contains the layout parameters visible on the Template Manager
layout.php: This is the main layout program containing the necessary HTML markup and Joomla! "jdoc" calls for content areas

Note: Layouts can contain more folders or files depending on their functionality.

XTC supports an unlimited number of layouts per template. The easiest way to create a new layout is to make a copy of an existing layout folder with a different name. You can then edit the php and xml file to suit your needs or leave them unchanged. The XTC framework will recognize the new layout automatically and will keep separate sets of parameters for both. Read the Developer's Guide for more information on how to construct a Layout from scratch.

Styles

default.css - This file contains most of the styling code for the template
"Style groups" - The files corresponding to each Style Group will be called in sequence
system.css - Joomla! default system styling
general.css - Joomla! default styling
template.css - The default Joomla! CSS file for a template will be called last, it can contain any user-made override of previous stylings.

Each Style Group has a short prefix assigned in the template parameters, and all files related to the group must be named using the same prefix. This being said, it is important to understand how Style parameters groups work. In the next examples, we will use a Style Group identified with the prefix "theme" that is intended to control the overall color appearance of our template.

Style Groups are composed of at least one CSS file and one or more XML files. Our example group has the "theme" prefix assigned, so there will be a "theme.css" file (the formatting code) in the "css" folder and a "theme.xml" file (the parameters code) in the "parameters" folder. Just like in Layouts, the Style parameters are available in the Template Manager.

The nature of Style Groups allows you to expand the configuration options even more: since the files are named after a common suffix, it is possible to have a single theme.css file and multiple xml files, for example:

css/theme.css: This contains the CSS code
parameters/theme_blue.xml: This XML contains parameters with color values set for a Blue appearance
parameters/theme_green.xml: This XML contains parameters with color values set for a Green appearance
parameters/theme_red.xml: This XML contains parameters with color values set for a Red appearance

If the CSS base code is essentially the same, having multipe xml files allows you to have multiple sets of parameter values for a single group. The xml parameter files of a single group will be shown together like in the following image:

Multiple Styles

Of course, they can all be adjusted individually. XTC will keep a separate copy of the values for each set and will automatically select the correct one depending on the option selected in the layout.

Furthermore, the combinations can be expanded even more if you create multiple CSS files for a single group. For example:

css/theme.css: This contains the CSS code
css/theme_green.css: This contains the CSS code
parameters/theme_blue.xml: This XML contains parameters with color values set for a Blue appearance
parameters/theme_green.xml: This XML contains parameters with color values set for a Green appearance
parameters/theme_red.xml: This XML contains parameters with color values set for a Red appearance

In this example, the Blue and Red themes will share a single css file ("theme.css") while the Green theme will use its own css file, permiting it to have a different set of parameters altogether. Just like Layouts, the easiest way to create a new xml or css file is to simply copy an existing one with a filename using the same preffix. You can then edit the css or xml files to change the style name and/or description.