SEARCH:
Documentation

Andromeda HTML Templates

An HTML template is the top level file (and associated files) that determines a site's overall look. It contains the main HTML file, links to framework JS and CSS files, and possibly some JS and CSS files of its own.

We use the term "HTML Template" to distinguish these from the Smarty Templates that are also supported as part of the androPage feature.

Joomla Compatibility

Andromeda's default theme, named "rt_pixel", was generously provided by http://www.rockettheme.com and is a Joomla 1.0 template.

Andromeda mimics a small set of the Joomla 1.0 API so that Joomla 1.0 templates can be dropped in and used for Andromeda sites, though they usually require a couple of hours of modifications to eliminate or handle calls to unsupported features.

File Locations and Name

A template should be placed into your application's "templates" directory. The name of the template is the name of the directory.

The only required file is "index.php" in the template's directory, such as ".../templates/my_example/index.php. Any other files can be created and named as you choose.

Be warned that the templates directory is publicly visible to the browser, all files in it can be viewed by the user. You can prevent access to individual files directly from the browser with this code: 

defined( '_VALID_MOS' ) 
    or die( 'Direct Access to this location is not allowed.' );

Selecting A Template

Andromeda will by default always choose the "rt_pixel" template if it is present.

To force a selection of your own template when the user first hits the site, put this code into your applib.php program. This works only on the very first hit to the site. 

$GLOBALS['AG']['template']='my_template';

To force a selection of a different template on all subsequent hits to the site, set the session variable: 

SessionSet('TEMPLATE','my_example');

Once a template has been selected it is used until you force a change by writing to the session TEMPLATE variable.

Structure of a Template

The minimum template is here:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <!-- NO TITLE! It is output in androHTMLHead.php-->
    
    <!-- This must be the last line in the HEAD section -->
    <?php include('androHTMLHead.php')?>
</head>
<body>

<?=mosMainBody()?>

</body>
<?php include('androHTMLFoot.php') ?>
</html>

There are a few rules to keep in mind:

  • Do not output a TITLE element
  • The androHTMLHead.php include should be the last line in the HEAD
  • Use "mosMainBody()" to output the main content of the page
  • Include androHTMLFoot.php at the very end

Adding CSS and JS Files

Template layout has evolved to keep pace with developments in web performance. In particular a template should assist in getting a good grade for the YSlow! utility.

With that in mind, Andromeda has a framework utility for outputting Javascript files, which is jsInclude(). Call this routine with the relative path of your javascript file, such as "jsInclude('appclib/myjsfile.js')" or "jsInclude('templates/my_template/js/templatejs.js')".

A similar routine is used for css files, such as "cssInclude('templates/my_template/my_template.css')".

Note that JS files are not actually put out in the HEAD section, they are output at the very bottom to improve performance and the user experience.

Note that CSS files are not output individually, but are combined and sent to the browser in a single file, to improve performance and the user experience.

If the system variable JS_CSS_DEBUG is set to 'Y', Javascript files and css files are sent individually, so you can look through them and debug them. If that variable does not exist or is 'N' then the CSS files are combined into one, and the JS files are minified and combined into a single file.

Both jsInclude() and cssInclude() accept a second parameter, which, if true, forces an immediate output of the file regardless of the setting of JS_CSS_DEBUG. This may be necessary for CSS files that specify background images with the URL() function, since the paths in those rules will get mangled and will not work in a combined file.