Wiki theming

Modified on 2008/05/15 12:00 by Administrator — Categorized as: Uncategorized

In this page we present the documentation about the customization of the appearance of ScrewTurn Wiki.


1 - Introduction to Themes

ScrewTurn Wiki is able to use "style packages" called Themes. A Theme defines the aspect of the Wiki in fine detail. Physically, a Theme is a directory placed inside the Themes directory (for example http://www.mywiki.com/Themes/MyTheme).
The Theme's directory may contain any type of file, but it should contain at least a CSS file; for example, the Default Theme's directory is structured as described below:


Default/
   Screen_Styles.css
   Print_Styles.css
   Icon.ico
   Scripts.js (that's actually empty)
   Images/
      ... all the images of the Theme

1.1 - Cascading Style Sheets (CSS)

A Theme may include an arbitrary number of CSS files; they are always sent to the browser. These CSS files have anything special, they are just standard Cascading Style Sheets.

1.1.1 - CSS Naming Conventions

CSS Classes are always named with a full-lowercase name, for example a.imagelink.
CSS IDs are always names with a CamelCase name, for example MainDiv.

1.2 - CSS Media Types

The CSS standard defines different media types. Each one specify a different target device, such as a PC screen, a PDA or a printer.
ScrewTurn Wiki supports different media types through a special naming convention of CSS files. If you want to specify that a CSS file is intended for the screen media type, just prepend to its name the label screen_. A complete list of available media types is reported here (names are not case-sensitive):

1.3 - FavIcon and JavaScript

All the JavaScript files (*.js) are automatically included in every page of the Wiki. Please note that ScrewTurn Wiki already uses some JavaScript, but all the functions are named with a double underscore prefix, for example __ToggleImages(). This helps to prevent name conflicts with custom JavaScript.
It is possibe to set a FavIcon for the Wiki. To do that, just place a file in the Theme directory named Icon.ico, Icon.png or Icon.gif (names are case-unsensitive) and it will be set as FavIcon for every page of the Wiki.

2 - Theming pseudo-API

The Wiki is customizable in every aspect. Each block of the web interface has a specific CSS class and/or ID, therefore its properties can be entirely set using CSS files.

2.3 - CSS Classes and IDs

The Wiki defines a set of CSS classes and IDs that are used in every page.
First of all, the content of the Wiki pages uses no p tag, but the text is printed as-is, so it is rendered by the browser using the CSS styles available for the body of the page.
Small blocks of text, in some circumstances, are wrapped in p blocks.
The list of CSS classes used by the Wiki is described below (the list does not include page-specific classes, which are described in the next sections).

2.3.1 - Classes


2.3.1.1 - Page Discussion Classes

The following CSS classes are used only in Page Discussions.

2.3.2 - IDs

The following CSS IDs are used only in content Pages.

2.2 - Global Page Structure

The global structure is the same for every page of the Wiki, and it is represented below.
Note: the page includes other standard XHTML tags which are omitted for brevity.


<div id="HeaderDiv">
   <!-- Here is printed the content of the file Header.cs -->
</div>

<div id="ContainerDiv">

   <div id="SidebarDiv">

      <div id="SidebarHeaderDiv">
         <!-- Used for layouting purposes -->
      </div>
      <div id="SidebarContentDiv">
         <!-- Here is printed the content of the file Sidebar.cs -->
      </div>
      <div id="SidebarFooterDiv">
         <!-- Used for layouting purposes -->
      </div>

   </div>

   <div id="MainDiv">

      <div id="MainHeaderDiv">
         <!-- Used for layouting purposes -->
      </div>

      <div id="PageInternalHeaderDiv">
         <!-- Contains local header for content Pages - file PageHeader.cs
         This element can be omitted -->
      </div>

      <!--
         HERE IS PRINTED THE ACTUAL CONTENT OF THE PAGE, DIFFERENT IN
         "SYSTEM" (Admin.aspx, AllPages.aspx, ...) PAGES AND WIKI PAGES
      -->

      <div id="PageInternalFooterDiv">
         <!-- Contains local footer for content Pages - file PageFooter.cs
         This element can be omitted -->
      </div>

      <div id="MainFooterDiv">
         <!-- Used for layouting purposes -->
      </div>

   </div>

</div>

<div id="FooterDiv">
   <!-- Here is printed the content of the file Footer.cs -->
</div>

2.3 - Wiki Pages

The content of the Wiki Pages, which contain the actual content, is placed between the two DIVs named MainHeaderDiv and MainFooterDiv. The structure of the markup that is placed there is reported below.


<a id="PageTop"></a> <!-- Used as "page top" anchor -->

<div id="PageHeaderDiv">

   <!-- Contains header info of the Page, such as Title, date and user -->

   <div id="EditHistoryLinkDiv">
      <a id="EditLink">...</a> <!-- Link to the Edit page -->
      <a id="HistoryLink">...</a> <!-- Link to the page History -->
   </div>

   <h1 class="separator">Page Title</h1>

   <div id="PageLockedDiv">...</div>
   - or -
   <div id="PagePublicDiv">...</div>

   <div id="RssLinkDiv">
      <a id="RssLink">...</a> <!-- Link to the RSS feed -->
   </div>

   <div id="PageInfoDiv">
      <!-- Page info, such as date and time, user -->
   </div>

</div>

<div id="PageContentDiv">
   <!-- THE CONTENT OF THE PAGE -->
</div>

2.4 - System Pages

"System" Pages are all the non-content pages, such as Admin.aspx, Login.aspx, AllPages.aspx and so on. These pages, due to their particular purposes, have not a standard structure. Most of them have no need to be customized in detail, so there are not named elements or page-specific CSS classes. The pages that have customization possibilities are described in this section.

2.4.1 - Admin.aspx

In the page Admin.aspx the following CSS classes and IDs are used:

2.4.2 - AllPages.aspx

In the page AllPages.aspx the following CSS classes and IDs are used:

2.4.3 - Edit.aspx

In the page Edit.aspx the following CSS classes and IDs are used:

2.4.4 - History.aspx

In the page History.aspx the following CSS Classes and IDs are used.

2.4.5 - Search.aspx

In the page Search.aspx the following CSS Classes and IDs are used.

2.4.6 - Upload.aspx

In the page Upload.aspx the following CSS Classes and IDs are used.