Skip to end of metadata
Go to start of metadata

ATutor Themes Documentation

Introduction

An ATutor theme is a set of template files with images and a stylesheet that change the overall look and feel of an ATutor installation. An installation may have one or more themes installed at one time; a user is given the ability of selecting a single theme to be used while they are logged-in.

ATutor themes are based on Savant2 templating system. Visit the Savant site for full documentation:
Savant

Installing a New Theme

Importing A Theme (automatic install)

Access the Theme Manager area of ATutor in the Administrator tools. Before importing a theme you will need to make the themes directory writable by the Web server. If the directory is not writable, you will see a message explaining how to make the directory writable, in place of the theme import tool. Note that themes imported this way will be owned by the Web server user, thus once imported, you will not be able to modify the files in the theme.

FTP A Theme (manual install)

If you are planning to modify the theme to create a custom version, you will want to install the theme using the FTP method.

To avoid loosing the ability to edit theme files, you should upload the theme's zip file into the themes/ directory using an FTP application, and unzipping the file yourself once it has been uploaded to the server. You may be able to unzip the files using your FTP client, or through applications like CPanel, or other common ISP provided site management tools. Once the theme is uploaded and unzipped, manually add an entry to the themes table in the ATutor database to make the theme available to the ATutor Theme Manager. If you are using a tool like phpMyAdmin to access your database, you can create a new row in the themes table, and enter the information manually.

Or, run an SQL statement like the following.

Be sure the last value for "status" is set to "1" to begin with, which means the theme is installed and enabled, but is not the default theme. Once your theme has been finalized, this value can be changed to "2" to make it the systems default theme. This value should be set using the Theme Manager.

File & Directory Structure

All theme specific files are located in /themes/[theme_name]/, where `[theme_name]` is the directory name (dir_name) of the theme. The `[theme_name] need not be the exact name of the theme (i.e. a theme titled `Blueberry Cheesecake` may exist in a directory called `bb_cc` etc.). The actual name of the theme is specified in that theme's configuration file.

The Default theme contains the following files:

Theme Configuration File - theme.cfg.php

Each theme must have a configuration file named 'theme.cfg.php'. If the theme.cfg.php file cannot be found in the theme's directory then the theme will not be made available to use. The fields in the theme.cfg.php file are documented in the file; they describe such things as the name of the theme, its author, and the version of ATutor the theme should be installed with.

Creating a Theme

Here are a couple ways to create a new theme:

1. One way to create a theme, and for many the preferred way, is to copy the Primary Theme Files from the default theme into a new theme directory. You can copy these files from other themes that may look closer to the style you want to create, but the default theme will always be most up to date. In many cases it is only necessary to modify the stylesheet (styles.css) to adjust colours, fonts, and some layout styles etc, to create a new theme. A theme can be made up of a single stylesheet file and a theme.cfg.php file. Most other templates used to layout various tool screens, table displays, test items etc. you probably won't need to include in your theme. If templates are not found in the new theme, they will be inherited from the default theme.

In some cases you may want to make more significant changes to the layout than can be done with stylesheet adjustments alone, so in such a case you can copy the header and footer files from the default theme into the new theme's /theme_name/include/ directory, then edit those files. You will probably need to create the include/ directory first.

These files are generally all that are required to create a new theme:

Primary Theme Files

  1. styles.css
  2. theme.cfg.php
  3. theme_info.xml
  4. screenshot.jpg
  5. include/
    • header.tmpl.php
    • footer.tmpl.php

2. If you have limited access to the ATutor files on the server, export one of the themes displayed in the administrator's Theme Manager. The theme is exported onto your computer as a '.zip' file. Unzip the file, then make changes to theme files it contains. Be sure to edit the theme_info.xml file to give your theme a new name. Once you've made your changes, zip the files together again and import the file back into ATutor with the Theme Manager. The name of the zip file you create should closely represent the name you want to give your theme, substituting '_' for spaces.


The theme files described above are basically HTML files with some PHP mixed in. You do not need to know much about PHP to create a theme; most of the syntax is straight forward and uses basic if-statements to control if some feature displays or not, and foreach-loops to display repetitive or tabular information. For additional information on PHP see php.net.

The theme files contain variables which look like $this->[something] mixed in among HTML markup. Those variables get set by ATutor and may contain simple text or in some cases arrays of values.

You will probably want to add the developing theme to the ATutor database "themes" table while you are working on it, so you can see the changes you're making as they occur. The following are the fields in the "themes" table.

The fields in the themes table are as follows:
`title` (the name of the theme, any text string)
`version` (the version of ATutor the theme is intended for)
`dir_name` (the name of the directory the theme will be located in, alphabetic string, no spaces)
`last_updated` (The last date the theme was modified, use "NOW()")
`extra_info` (A description of the theme etc. )
`status` (theme's enable status, 0:disabled, 1:enabled, 2:set as default theme)

Below is an example of the SQL used to create an entry in the themes table for a new theme. You can also use a tool like phpMyAdmin to add a new entry to the "themes" table. Be sure to adjust the "AT_" prefix if you are using the SQL statement, to match the prefix you are using in your ATutor installation. Be careful when setting the value for the status field. If you set the status to "set as default" ( 2 ) and your theme is broken, you may find you can no longer access ATutor.

Themes API

The following is a complete list of variables that can be used in themes as of 1.6.2. These variables contain various data from the ATutor application, that when inserted into a theme template, display some value, or values. The most up to date list of theme variables can be found in the include/header.tmpl.php file of the default theme for the version of ATutor you are using. See the ATutor Developer Documentation for details about using the debug() function to print out a list of the values to help while you are designing a theme.

Updating an Old Theme

Occasionally new features are added to themes, and adjustments are needed to allow older themes to work with newer versions of ATutor, or to add new functionality to themes that was not available in older versions. For a list of theme changes, see the Themes Change Log.

Themes Change Log.

Contents
  • No labels