XTC Framework

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

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

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

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

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

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

    tag has the "menu" and "suckerfish" classes added to it. Also, the options within each menu level have extra classes describing their place in the menu structure: "first", "center" and "last" (or "single" if there is only one option). They are also assigned a numbered "order" class indicating their position. Lastly, the classes "active" and "parent" further identify the currently active menu option and options containing child submenus respectively.

    With this structure in mind, you can now look at the following CSS code as an example of styling:

    /* 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

    XTC templates are very similar in structure to a standard Joomla! template on purpose, this means you will be very familiar with the file elements of XTC framework in just a moment.

    As any other Joomla! template, XTC templates are stored in a directory within the "/templates" folder of your system. The main program of a Joomla! template is called "index.php" and for XTC templates, this file is in charge of initializing the XTC framework, loading the different parameters and calling a layout file to render the template and contents.

    Layouts

    A layout contains the HTML code to create the overall template layout, they include standard Joomla! "jdoc" calls for content areas as well as the XTC function calls required for the Style Group files that compose the CSS code for formatting. It can also include any other HTML code necessary for the template to work properly. Layouts are stored on their own directory inside the "layouts" folder of the template, this is an example of the file structure for layouts:

    XTC Layout

    As you can see, each layout is composed of at least two files:

    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

    As mentioned before, the visual styling of the template is done with CSS formatting and the XTC framework follows the same "Cascade" concept to apply stylings. In order to achieve this, several files located in the "css" folder of the template are called in the following order:

    1. default.css - This file contains most of the styling code for the template
    2. "Style groups" - The files corresponding to each Style Group will be called in sequence
    3. system.css - Joomla! default system styling
    4. general.css - Joomla! default styling
    5. 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.

    Conclusion

    Thank you for reading this guide. As you can see, the XTC framework offers efficient and powerful features that ease template customization while maintaining full compatibility with standard Joomla! template features. Your current knowledge of Joomla! templates is still valid and empowered with the XTC extensions! If you are a Template Developer, there is still more useful information available for you in the Developer's guide.

    The XTC framework will be enriched with more real-world useful features in the future. This document will be updated whenever needed to reflect any changes or additions.


    Copyright 2010 Monev Software LLC
    www.joomlaxtc.com

background images