WIKINDX ~ Templates

Although we, the developers of WIKINDX, tried to supply some nice looking templates for your viewing pleasures sometimes that's just not enough for you. And that's where the WIKINDX template system comes into play. In this document you will find out how to use it.

At first we will introduce you to the files that make up a template. We will tell you what you can modify and we tell you what you should leave unchanged. Of course, there is information on installing templates as well.

There is a lot of HTML code that is generated and poured into the templates by WIKINDX which is not yours to change unless you want to reprogram the underlying php. Still you can influence those HTML parts with CSS, we will tell you how to do it. And for the advanced tempate makers out there we even show you where you can modify the php output. But let's start with the basics.

The Basics

WIKINDX uses a modified version of the php template system phemplate.While most of the contents of the template files (see below for information on the various files) is made out of plain HTML tags, some tags are part of the template syntax. Since those tags are very similar to normal HTML tags, you will not have to learn a whole new programming language just to make your own template. Here is a list of the special template tags used in WIKINDX:

Don't worry if you don't understand why and how these special tags are used. Important is just that you should leave those tags untouched in order to keep WIKINDX working. Of course, you may change any surrounding or enclosed tags. For example, it doesn't matter if you write <h1>{title}</h1>, <h4>{title}</h4>, or just {title} as long as '{title}' apears somewhere in the template file.

In the following section we will give examples and go through every template file.

The Minimal Template

A good starting point for creating your own template is the Minimal Template. It's not part of the general WIKINDX template package and therefore it cannot be chosen in the preferences after you've installed WIKINDX. The Minimal Template is located in the subfolder minimal in the folder docs/templates (your current position). As the name already suggests,this template uses only a minimum of HTML.

Each template (including the Minimal Template) consists of at least five files:

These files are mandatory and without them, WIKINDX will not function correctly. Additionally, a template might use images and CSS files (e.g. the default template) but those are optional. In the next few sections we will tell you about each mandatory template file and how you can modify it.

header.tpl

<!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" xml:lang="en" lang="en">
<!-- begin header template (+ 3 lines up!) -->
<head>
<title>{title}</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<!-- Javascript required for citation links when editing meta data of resources.-->
<script type="text/javascript" src="core/javascript/common.js"></script>
<!--
  Javascript hack to get IE working with CSS drop down menus
  -->
<script type="text/javascript" src="templates/default/menuShim.js"></script>
<script type="text/javascript"><!--//--><![CDATA[//><!--
sfHover = function()
{
  if (document.getElementById("nav"))
  { // does #nav element exist?
  	var sfEls = document.getElementById("nav").getElementsByTagName("LI");
  	for (var i=0; i<sfEls.length; i++)
	{
	  sfEls[i].onmouseover=function()
	  {
	  	this.className+=" sfhover";
	  }
  		sfEls[i].onmouseout=function()
		{
  			this.className=this.className.replace(new RegExp(" sfhover\\b"), "");
  		}
  	}
  }
}
  if (window.attachEvent) window.attachEvent("onload", sfHover);
  //--><!]]></script>
</head>
<!-- end header template -->

The header.tpl is the first file called by WIKINDX and contains all header information of the web page. The only template syntax used here is {title} which will be substituted by whatever the WIKINDX Administrator has entered as the title of the WIKINDX page. Apart from that we included all information for a correct XHTML web page. Although XHTML is not mandatory to WIKINDX we encourage you to write XHTML-conform web pages. Please note, the charset must be UTF-8 as above.

Since the title is not crucial to the functionality of WIKINDX you may change any part of this file. If you exchange the title variable with some custom text the WIKINDX Admin will not be able to change the page title through the WIKINDX Admin preferences.

The javascript that you will find in the WIKINDX template package folders in each header.tpl is there to ensure that CSS drop-down menus function on Internet Explorer for Windows.

body.tpl

<!-- begin body template -->
<body onload="init()"><h1>{headTitle}</h1>

<!-- end body template -->

This file pretty much explains itself. The {headTitle} will display the same information as {title} in header.tpl.Again, if you exchange this tag with something else, the Administrator will not be able to change the heading from theWIKINDX admin preferences. The onload="init()" in the body tag is required to load various javascript classes and methods.

bodyPopUp.tpl

<!-- used for javascript pop-ups for e.g. citation - so no images, title etc. -->
<!-- begin body template -->
<body>
<!-- end body template -->

This is used solely for javascript pop up windows that have no menu system or table structure. Currently used only for the cite hyperlink when adding/editing resource meta data such as quotes, paraphrases etc.

menu.tpl

<!-- begin menu template -->
<ul><loop name="nav">
  <li><a href="{nav.link}">{nav.title}</a>
          <ul><loop name="nav.submenu">
            <li><a href="{nav.submenu.link}">{nav.submenu.title}</a></li></loop 
name="nav.submenu">          </ul>
  </li></loop name="nav">
</ul>
<!-- end menu template -->

Next is the template for WIKINDX's navigation. It's short but evolves into long code because it uses two loops. The outerloop ('nav') contains the data for the inner loop ('nav.submenu'). If you're not familiar with loops, think of them as the instruction to do a repetitive job: you have a spreadsheet with columns of links, titles as well as subtitles and sublinks associated with the top link and title. From this data you need to construct something like this:

1 Link - 1 Title
	1.1 Link - 1.1 Title
         1.2 Link - 1.2 Title
2 Link - 2 Title
	2.1 Link - 2.1 Title
3 Link - 3 Title
	3.1 Link - 3.1 Title
         3.2 Link - 3.2 Title
         3.3 Link - 3.3 Title
You write down the first link and title, then all its sublinks and subtitles. After that you write the next link and title along with its sublinks and subtitles. The loop will do just that for you. If you are still confused as to what the output looks like take a look at the sourcecode of any WIKINDX page in your web browser. You will notice the structure of the menu.

To make a template that retains minimal functionality you need to include the 'nav' loop but may leave out the 'nav.submenu' loop. In that case all the links in the submenu will be displayed in the main content template (see below).

content.tpl

<!-- begin content template -->
<!-- optional form start tag allows a form to span several tables and still be xhtml-compatible -->
<opt name="formStart">
{formStart}
</opt name="formStart">
<table class="mainTable" border="0" cellspacing="0" cellpadding="0" align="center">

<!-- Main content -->
<tr class="" align="left" valign="top">
<td class="" align="left" valign="top">
<h3>{heading}</h3>
</td>
</tr>

<!-- submenu links for browsers unable to use CSS drop-down menus -->
<opt name="noMenu">
<tr class="" align="left" valign="top">
<td class="" align="" valign="top">
{noMenu}<br /><br />
</td>
</tr>
</opt name="noMenu">
<opt name="body">
<tr class="" align="left" valign="top">
<td class="" align="left" valign="top">
{body}
</td>
</tr>
</opt name="body">

<!-- Paging system links for lists of resources -->
<opt name="paging">
<tr class="" align="left" valign="top">
<td class="" align="left" valign="top">
<hr />
</td>
</tr>
<tr class="" align="left" valign="top">
<td class="small" align="center" valign="top">
{paging}
</td>
</tr>
</opt name="paging">

<!-- contact email for front page -->
<opt name="contact">
<tr class="" align="right" valign="top">
<td class="" align="right" valign="top">
{contact}
</td>
</tr>
</opt name="contact">
</table>
<!-- optional form end tag allows a form to span several tables and still be xhtml-compatible -->
<opt name="formEnd">
{formEnd}
</opt name="formEnd">
<!-- end content template -->

The content template will display the largest amount of HTML and will give you the least amount of control (well, if you put your design decisions against the amount of output, that is).

It is important to note, that WIKINDX, in its internals, will output TABLE rows for its main content therefore it is vital that the TABLE elements above be left unchanged (although you are free to change alignment, class etc.). Furthermore, several WIKINDX user input pages require one form to span many TABLE elements; for XHTML compatibility, it is important that the formStart and formEnd tags remain in place and outside any TABLE.

The first tag that you should leave intact is {heading} because it will contain the heading for each WIKINDX page. If you take this one out the user will not know on what page she currently is.

Next are a couple of optional areas. They will only be displayed if the enclosed variable is needed. For example, if the user needs the submenu listing (because she clicked on a top navigation link instead of a sublink or because you got rid of the submenus altogether), everything enclosed by <opt name="noMenu"> will be shown. The same goes for paging or contact information as well as the body which will contain most of the WIKINDX output information.

While you may change the surrounding tags of each area (e.g. putting them into differently colored tables) you cannot change the content of these areas. At least not unless you want to dig deep into the WIKINDX php code. Although we decided to give our users the possibility to adapt the look and feel of WIKINDX to the individual's needs we didn't want to make things too complicated which is why you have only so little control of this part of the HTML.

As pointed out already, you can still control some aspects of the output. You can use Cascading Style Sheets (CSS) to make the output look the way you need it to (more on this later). This will get you a long way because we made sure that a lot of the layout can be altered through the use of CSS. Also, you can take a look at the HTML classes in the WIKINDX project and find out where you need to make your changes but php programming knowledge is needed and should only be done if abolutely necessary. Please refer to the appropriate documentation.

footer.tpl

<!-- begin footer template -->
<p>
         <a class="link" href="{wkx_link}" 
target="_blank">{wkx_title}</a>&nbsp;         {wkx_version} {copyright}
         |
         Total Resources: {totalResources}
         |
         {db_queries_title}: {db_queries}
         |
         {script_exe_title}: {script_exe_time}
</p>
</body>
<!-- end footer template (+ 1 line down!) -->
</html>

Finally, there is the footer template. As its name suggests it closes up the web page. Also it will display some statistics about WIKINDX. There is nothing new here that you haven't seen in the previous files. Any information may be moved around or deleted altogether. It would be nice though if you'd keep at least the line containing the link to our project page:
<a class="link" href="{wkx_link}" target="_blank">{wkx_title}</a>&nbsp;

Installing templates

First you need to copy the template files to a folder in the WIKINDX template folder. Here you will find at least the folders default, classic, chocolate, and blue which are all in the WIKINDX template package. If you want to install the Minimal Template, copy the folder minimal from the folder docs/templates/ to the top level templates/ folder.

Now you only need to tell WIKINDX that you've provided a new template. Create a file templates/minimal/description.txt and enter the one line text Minimal Style. This text will be displayed to the user when selecting templates in their preferences.

These are the steps you need when installing new templates. Of course, instead of using the Minimal Template you may use any other template folder, copy and rename it and use it as your new template that you later modify.

CSS

If you wish to have a Cascading StyleSheet, you must place the css file (we're assuming it's called minimal.css) in the same folder as your template files and add the following to the header.tpl file under the meta tag:
	<link rel="stylesheet" href="templates/minimal/minimal.css" type="text/css" />

We suggest you copy the included minimal.css located in docs/templates/minimal/ as a starting point and follow the instructions and comments provided there.

Various classes are important to the WIKINDX template package files. It is strongly recommended that you keep linkCite and linkCiteHidden unchanged -- these display or hide the 'cite' link depending on the status of javascript in the web browser. Once you are happy with basic templating operations, we suggest you study one of the supplied template folders to see how CSS is used. In particular, the table classes such as titleTable (used in body.tpl), menuTable (used in menu.tpl), mainTable (used in content.tpl) and footerTable (used in footer.tpl).

Other CSS classes you may be interested in (and which can be found in /templates/default/default.css) are:

error and success -- display for various system messages
hint -- display for hints (helpful text usually used for form input)
alternate1 and alternate2 -- alternating display of each resource in a bibliographic list
highlight -- highlight words/phrases in resources after a search

Icons

If you wish to use icons for viewing and editing resources instead of the default text hyperlinks, the following are required:

If any of the above are missing, WIKINDX will display the default text as a hyperlink. WIKINDX will display a hyperlink around an icon using the imgLink CSS class instead of the standard link class.

WIKINDX home      WIKINDX usage      WIKINDX classes