documentation/developer/themes.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   2 <html  xmlns="http://www.w3.org/1999/xhtml" lang="en">
   3 <head>
   4         <title>ATutor Theme Designer Documentation</title>
   5         <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   6         <meta name="author" content="Greg Gay" />
   7         <meta name="description" content="ATutor Theme Designer Documentation" />
   8 <style type="text/css">
   9
  10 h1 {
  11         background-color: #CCCCCC;
  12         padding-left: 20px;
  13         padding-right: 20px;
  14         margin-bottom: 10px;
  15         text-align: right;
  16 }
  17
  18 h2 {
  19         background-color: #DDDDDD;
  20         padding-left: 10px;
  21         margin-bottom: 0px;
  22 }
  23 h3 {
  24         background-color: #EFEFEF;
  25         padding-left: 20px;
  26         margin-bottom: 0px;
  27 }
  28 h4  { margin-bottom: 0px; }
  29 p   { margin-top: 0px;    }
  30 dl  { margin-top: 0px;    }
  31 kbd {
  32         padding: 0px 1px 0px 1px;
  33         border-width: 1px 2px 2px 1px;
  34         border-style: solid;
  35         border-color: #edd #baa #baa #eed;
  36         white-space: pre;
  37 }
  38 kbd em {
  39         font-weight: bold;
  40         background-color: #efefef;
  41 }
  42 blockquote { font-style: italic; }
  43 pre.code {
  44         background-color: #EEEEFF;
  45         padding: 5px;
  46         margin-left: 20px;
  47         color:#761596;
  48     margin-top: 0px;
  49 }
  50 .top {
  51         float: right;
  52         color: green;
  53         padding-top: 2px;
  54         padding-right: 5px;
  55 }
  56 pre {
  57         background-color: #EEEEFF;
  58         font-family: Courier, monospace;
  59         border-left: 1px solid #761596;
  60         padding: 0px 0px 0px 10px;
  61         color: #333;
  62         margin: 0px 0px 10px 20px;
  63         font-size: 88%;
  64         line-height: 1.2em;
  65 }
  66 @media print {
  67         h2 {
  68                 page-break-after: avoid;
  69                 border-bottom: solid 1px black;
  70         }
  71         h3 {
  72                 page-break-after: avoid;
  73                 border-bottom: solid 1px black;
  74                 width: 75%;
  75         }
  76         .top {
  77                 display: none;
  78         }
  79
  80         pre.code {
  81                 page-break-inside: avoid;
  82         }
  83 }
  84 }
  85 acronym {
  86         cursor: help;
  87 }
  88 </style>
  89
  90 </head>
  91 <body>
  92 <div>
  93 <h1>Theme Designer Documentation</h1>
  94 <ul>
  95
  96 <li><a href="#intro">Introduction</a></li>
  97 <li><a href="#install">Installing a New Theme</a></li>
  98 <li><a href="#structure">File &amp; Directory Structure</a></li>
  99 <li><a href="#config">Theme Configuration File</a></li>
 100 <li><a href="#create">Creating a Theme</a></li>
 101 <li><a href="#variables">Theme Variables</a></li>
 102 <li><a href="#testing">Testing a theme</a></li>
 103 <li><a href="#updating">Updating an old theme for a newer version of ATutor</a></li>
 104 </ul>
 105
 106 <p><a name="intro"></a></p>
 107
 108 <h2>Introduction</h2>
 109         <p>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.</p>
 110
 111         <p>ATutor themes are based on Savant2 templating system. Visit the Savant site for full documentation:
 112         <a href="http://phpsavant.com/yawiki/index.php?area=Savant2;page=SavantDocs">Savant</a></p>
 113
 114 <a name="install"></a>
 115 <h2>Installing a New Theme</h2>
 116         <h3>Importing a Theme (automatic install)</h3>
 117         <p>Access the Theme Manager area of ATutor in the Administrator tools. Before importing a theme, the ATutor theme directory will need to be 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.</p>
 118         <h3>FTP a Theme (automatic install)</h3>
 119         <p>If you are planning to modify the theme to create a custom version, you will want to install the theme using the FTP method.</p>
 120
 121         <p>To avoid loosing the ability to edit theme files, you should upload the theme's zip file into the <kbd>themes/</kbd> 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.</p>
 122
 123         <p>Or, run an SQL statement like the following. </p>
 124
 125
 126         <pre>
 127         INSERT INTO `AT_themes`
 128         (`title`, `version`, `dir_name`, `last_updated`, `extra_info`, `status`)
 129         VALUES
 130         ('My Theme Name', '1.6.1', 'my_theme_dir', NOW(), 'This is a customized theme based on the default theme.', 1);
 131         </pre>
 132
 133         <p>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 system's default theme. This value should be set using the Theme Manager.</p>
 134 <a name="structure"></a>
 135 <h2>File &amp; Directory Structure</h2>
 136
 137 <p>All theme specific files are located in <kbd>/themes/[theme_name]/</kbd>, 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.</p>
 138
 139 <p>The Default theme contains the following files:</p>
 140
 141 <pre>
 142 # confirmmessage.tmpl.php
 143 # content.tmpl.php
 144 # directory.tmpl.php
 145 # errormessage.tmpl.php
 146 # feedbackmessage.tmpl.php
 147 # forms.css
 148 # images/
 149 #- arrow_ltr.gif
 150 #- back.gif
 151 #- error-large.gif
 152 #- guide.gif
 153 #- instructor.gif
 154 #- next.gif
 155 #- pen.gif
 156 #- pen2.gif
 157 #- pencils.jpg
 158 #- previous.gif
 159 #- resume.gif
 160 #- side_arrow.gif
 161 #- sort.gif
 162 #- user-star.gif
 163 #- user.gif
 164 # include/
 165 #- box.tmpl.php
 166 #- fm_footer.tmpl.php
 167 #- fm_header.tmpl.php
 168 #- footer.tmpl.php
 169 #- header.tmpl.php
 170 # index.tmpl.php
 171 # infomessage.tmpl.php
 172 # login.tmpl.php
 173 # password_change.tmpl.php
 174 # password_reminder.tmpl.php
 175 # password_reminder_feedback.tmpl.php
 176 # print.css
 177 # profile.tmpl.php
 178 # readme.txt
 179 # registration.tmpl.php
 180 # rtl.css
 181 # screenshot.gif
 182 # styles.css
 183 # theme.cfg.php
 184 # theme_info.xml
 185 # test_questions/
 186 #- likert.tmpl.php
 187 #- likert_qti_1p2.tmpl.php
 188 #- likert_qti_2p1.tmpl.php
 189 #- likert_result.tmpl.php
 190 #- likert_stats.tmpl.php
 191 #- long.tmpl.php
 192 #- long_qti_1p2.tmpl.php
 193 #- long_qti_2p1.tmpl.php
 194 #- long_result.tmpl.php
 195 #- long_stats.tmpl.php
 196 #- manifest_qti_1p2.tmpl.php
 197 #- manifest_qti_2p1.tmpl.php
 198 #- matching.tmpl.php
 199 #- matching_qti_1p2.tmpl.php
 200 #- matching_qti_2p1.tmpl.php
 201 #- matching_result.tmpl.php
 202 #- matching_stats.tmpl.php
 203 #- matchingdd.tmpl.php
 204 #- matchingdd_qti_1p2.tmpl.php
 205 #- matchingdd_qti_2p1.tmpl.php
 206 #- matchingdd_result.tmpl.php
 207 #- matchingdd_stats.tmpl.php
 208 #- multianswer.tmpl.php
 209 #- multianswer_qti_1p2.tmpl.php
 210 #- multianswer_qti_2p1.tmpl.php
 211 #- multianswer_result.tmpl.php
 212 #- multianswer_stats.tmpl.php
 213 #- multichoice.tmpl.php
 214 #- multichoice_qti_1p2.tmpl.php
 215 #- multichoice_qti_2p1.tmpl.php
 216 #- multichoice_result.tmpl.php
 217 #- multichoice_stats.tmpl.php
 218 #- ordering.tmpl.php
 219 #- ordering_qti_1p2.tmpl.php
 220 #- ordering_qti_2p1.tmpl.php
 221 #- ordering_result.tmpl.php
 222 #- ordering_stats.tmpl.php
 223 #- truefalse.tmpl.php
 224 #- truefalse_qti_1p2.tmpl.php
 225 #- truefalse_qti_2p1.tmpl.php
 226 #- truefalse_result.tmpl.php
 227 #- truefalse_stats.tmpl.php
 228 #- wrapper.tmpl.php
 229 # users/
 230 #- browse.tmpl.php
 231 #- email_change.tmpl.php
 232 #- index.tmpl.php
 233 #- password_change.tmpl.php
 234 #- preferences.tmpl.php
 235 #- profile.tmpl.php
 236 # warningmessage.tmpl.php
 237 </pre>
 238
 239 <a name="config"></a>
 240 <h3>Theme Configuration File - theme.cfg.php</h3>
 241         <p>Each theme must have a configuration file named <kbd>theme.cfg.php</kbd>. 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.</p>
 242
 243 <a name="create"></a>
 244 <h2>Creating a Theme</h2>
 245 <p>Here are a couple ways to create a new theme:</p>
 246 <ol>
 247 <li> One way to create a theme, and for many <strong>the preferred way</strong>, is to copy the <strong>Primary Theme Files</strong> 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. <br /><br />
 248
 249 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 <kbd>/[theme_name]/include/</kbd> directory, then edit those files. You will probably need to create the <kbd>include/</kbd> directory first.<br /><br />
 250
 251 These files are generally all that are required to create a new theme:<br /><br />
 252
 253 <strong>Primary Theme Files</strong><br />
 254 <ol>
 255    <li> styles.css</li>
 256    <li> theme.cfg.php</li>
 257    <li> theme_info.xml</li>
 258    <li> screenshot.jpg</li>
 259    <li> include/
 260         <ul>
 261           <li> header.tmpl.php</li>
 262           <li>footer.tmpl.php</li>
 263         </ul>
 264     </li>
 265 </ol><br /><br />
 266 </li>
 267
 268 <li> 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.</li>
 269 </ol>
 270
 271 <p>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 <a href="http://www.php.net">php.net</a>.</p>
 272
 273 <p>The theme files contain variables which look like <kbd>$this->[something]</kbd> mixed in among HTML markup. Those variables get set by ATutor and may contain simple text or in some cases arrays of values.</p>
 274
 275 <p>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.</p>
 276
 277 <p>The fields in the themes table are as follows:</p>
 278 <pre>
 279 `title` (the name of the theme, any text string)
 280 `version` (the version of ATutor the theme is intended for)
 281 `dir_name` (the name of the directory the theme will be located in, alphabetic string, no spaces)
 282 `type` (the type of the theme, "Desktop" or "Mobile)
 283 `last_updated` (The last date the theme was modified, use "NOW()")
 284 `extra_info` (A description of the theme etc. )
 285 `status` (theme's enable status, 0:disabled, 1:enabled, 2:set as default theme)
 286 </pre>
 287 <p>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 "<kbd>AT_</kbd>" prefix if you are using the SQL statement, to match the prefix you are using in your ATutor installation. <strong>Be careful when setting the value for the status field</strong>. If you set the status to "set as default" ( 2 ) and your theme is broken, you may find you can no longer access ATutor.</p>
 288
 289 <pre>
 290 INSERT INTO `AT_themes`
 291      (`title`, `version`, `dir_name`, `type`, `last_updated`, `extra_info`, `status`)
 292 VALUES
 293      ('Blueberry Cheesecake', '1.6.1', 'bb_cc', `Desktop`, NOW(), 'This is a blue theme.', 1);
 294 </pre>
 295
 296 <p>ATutor detects the type of the devices where the requests are from. If the request is from a desktop computer, the default desktop theme is automatically applied. Otherwise, if the request is from a mobile device, the default mobile is applied.</p>
 297
 298 <a name="variables"></a>
 299 <h2>Theme Variables</h2>
 300 <p>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 <a href="guidelines.html">Developer Documentation</a> for details about using the <kbd>debug()</kbd> function to print out a list of the values to help while you are designing a theme.</p>
 301
 302 <pre>
 303 * $this->lang_code                      the ISO language code
 304 * SITE_NAME                             the site name from the config file
 305 * $this->page_title             the name of this page to use in the &lt;title&gt;
 306 * $this->lang_charset           the ISO language character set
 307 * $this->content_base_href      the &lt;base href&gt; to use for this page
 308 * $this->base_path                      the absolute path to this atutor installation
 309 * $this->rtl_css                        if set, the path to the RTL style sheet
 310 * $this->banner_style{-}deprecated-
 311 * $this->theme                          the directory name of the current theme
 312 * $this->base_href                      the full url to this atutor installation
 313 * $this->onload                 javascript onload() calls
 314 * $this->img                            the absolute path to this theme's images/ directory
 315 * $this->sequence_links associative array of 'previous', 'next', and/or 'resume' links
 316 * $this->path                           associative array of path to this page: aka bread crumbs
 317 * $this->rel_url                        the relative url from the installation root to this page
 318 * $this->nav_courses            associative array of this user's enrolled courses
 319 * $this->section_title          the title of this section (course, public, admin, my start page)
 320 * $this->top_level_pages        associative array of the top level navigation
 321 * $this->current_top_level_page the full path to the current top level page with file name
 322 * $this->sub_level_pages        associate array of sub level navigation
 323 * $this->back_to_page           ithe path and file name to the part of this page (if parent is not a top level nav)
 324 * $this->current_sub_level_page the full path to the current sub level page with file name
 325 * $this->guide                          the full path and file name to the guide page
 326 * $this->icon the path to a course icon *(new from 1.6)*
 327 * ======================================
 328 * top_level_pages           array(array('url', 'title'))     the top level pages. ATutor default creates tabs.
 329 * section_title string the name of the current section. either name of the course, administration, my start page, etc.
 330 * page_title                string                           the title of the current page.
 331 * path                      array(array('url', 'title'))     the path to the current page.
 332 * back_to_page              array('url', 'title')     the link back to the part of the current page, if needed.
 333 * current_top_level_page    string                    full url to the current top level page in "top_leve_pages"
 334 * current_sub_level_page    string                    full url to the current sub level page in the "sub_level_pages"
 335 * sub_level_pages           array(array('url', 'title'))     the sub level pages.
 336 * is_mobile_device          true or false                    the request is from a mobile device or a desktop device
 337 * mobile_device_type        One of the values: ipod, blackberry, android, unknown, ipad
 338 </pre>
 339 <a name="testing"></a>
 340 <h2>Testing A Theme</h2>
 341 <p>To make ATutor use your theme, login as an ATutor user, go to "Preferences" page, "ATutor Settings" tab. Depending on the theme type, your theme will be displayed either in "Desktop Theme" or in "Mobile Theme". Find and select your theme name and save. ATutor will automatically switch to the saved theme. Note that if your theme is defined as a mobile theme, it will only be applied when you access ATutor via a mobile device. Vice versas for destop theme.</p>
 342
 343 <a name="updating"></a>
 344 <h2>Updating an Old Theme</h2>
 345
 346 <p>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 <a href="http://wiki.atutor.ca/display/atutorwiki/Theme+Change+Log">Theme Change Log</a>.</p>
 347
 348 <p><strong>NOTE:</strong> There is not a direct upgrade path from the 1.6 series themes to the 2.0 series themes. We suggest you start as you would creating a new theme, copying the files from the 2.0 default theme, then copy the stylesheet from the old theme into the stylesheet for the new theme, as well as copying any images from the old to the new.</p>
 349
 350 <h2>Sharing Themes</h2>
 351 <p>Once you've perfected your theme, consider contributing it to the ATutor community so others can use it. Visit the Themes section of ATutor.ca to contribute a theme. Login with your atutor.ca user account, then submit your theme to receive credit for your work. Contributing a theme will automatically raise your ATutor contributor status to the Bronze level. Or, if you're not interested in being credited, just send the theme to the ATutor team (info//AT//atutor.ca), or post it to one of the forums, and the ATutor team will submit the theme for you.</p>
 352
 353 <p><a href="http://www.atutor.ca/atutor/themes/submit_theme.php">Submit a Theme</a></p>
 354
 355 </div>
 356 </body>
 357 </html>