ThemeTutorial

bitweaver Theming Tutorial

Created by: xing, Last modification: 30 Oct 2008 (17:12 UTC) by laetzer

This page provides information on how to create a theme for Bitweaver. For details on classes and IDs, see Bitweaver's CSS Schema. About themes and styles: a theme is how Bitweaver looks and feels. A theme consists mainly of a style, located in /yourbitweaver/themes/styles/yourstyle/, and also of a layout, an icon set, modules, and other details. The style consists of CSS files and template files (which override Bitweaver's default template files). Although a style is part of a theme, a style tends to dominate the look of a Bitweaver install. That is why theme and style are often used synonymously.

Getting started


Picking a style

To customize Bitweaver, you should pick a style that already exists and more or less looks like the one your wish to end up with - considering its layout, module positions, menu placements and so on. Bitweaver's themes use DIV-based layouts (40 presets called Layout Gala). Details, however, are controlled in your customized CSS files and templates.

All styles that are available on your site are located in /themes/styles/. The style called blank (its CSS file lists off all the most important classes and IDs), and the style cascader (its CSS contains only the most important layout definitions) are good starting points for theme development.

Browser

Use a state-of-the-art CSS and XHTML compliant browser for development, and take care of backwards compatibility to old browsers later. Consider opera which has the possibility to customise everything yourself and can be turned into an incredible designers tool, or Mozilla Firefox, which can be extended with extremely useful plugins for development like Web Developer, https://addons.mozilla.org/de/firefox/addon/271|ColorZilla] and Firebug, among others.

Applying Changes

If your environment for theme development is set up correctly, ss soon as you've made changes in your style's CSS file, they will be visible in your browser after you have reloaded the page. If the changes don't appear
  • make sure you don't have any spelling mistakes (syntax highlighting helps)
  • make sure you are addressing the correct class or id (check the source of the page if the class or id exists)
  • make sure you are using the correct selectors (a.external is not the same as .external a)
  • use more specific selectors (a.external is better than .external for many reasons)
  • try using !important in your definition (e.g., border:1px solid #000 !important;) for testing

Readable source code

Bitweaver uses the Smarty templating engine. The {strip} tag is applied to most templates to remove excess whitespace characters. This reduces the download size of the HTML pages and, more importantly, makes sure that browsers don't interprete white space as extra pixels to add to the layout. As a result, the source code of any Bitweaver page is very difficult to read without applying some kind of clean up. Use plugins like View formatted source according to your browser.

To make the source code readable without any extra plugin, you can change the following in your Bitweaver install (and clear the system cache):

/util/smarty/libs/Smarty_Compiler.class.php


<?php
335
// from:
336$text_blocks[$j] = preg_replace('![\t ]*[\r\n]+[\t ]*!'''$text_blocks[$j]);
337// to:
338$text_blocks[$j] = preg_replace('![\t ]*[\r\n]+[\t ]*!'"\n"$text_blocks[$j]);
?>


Creating a new Style

Make a copy of the folder called blank (or any other) and rename the folder to the name of your new style. Within the newly named folder, find the original CSS file blank.css (foldername.css) and rename it to name of your new style as well:

copy and rename one style folder and one CSS file


<?php
// from:

/themes/styles/blank/
/
themes/styles/blank/blank.css
// to:
/themes/styles/yourstyle/
/
themes/styles/yourstyle/yourstyle.css
?>


Templates

Template hierarchy

The general process of modifying a template is to copy it from its location in bitweaver/package/templates/template.tpl to your style's directory: bitweaver/themes/styles/yourstyle/package/template.tpl. Now the upgrade process to new versions of Bitweaver is quick and easy. The following is the order in which locations are checked for a given template. If Bitweaver doesn't find the template wiki/templates/editpage.tpl in the first location, themes/force/wiki/editpage.tpl, it moves on to look for it in the second location, and so on:

order in which locations are checked for a given template


1. themes/force/package/
2. themes/force/
3. themes/styles/style/package/
4. themes/styles/style/
5. package/templates/


This means, placing a file in themes/force will override any template found in any style folder. For example, you can create a footer containing copyright information which will be applied to any style used on your site, without having to modify all the footer files of all available styles.

Most of the templates have the same name as "their" PHP file, only with .tpl as the extension. Some specific .tpl files are only used as an inclusion and can't be used on their own. These are marked with an additional _inc at the end of the filename.

Force templates

If you would like to force the use of a given template for all styles but don't want to edit all source files, you can create a directory called bitweaver/themes/force/. Any template found here, will override any other template unconditionally. This is an excellent technique for creating a single top_bar for your site if you use multiple themes.

The CSS

Because Bitweaver's CSS tree of classes and ID is so efficient, its CSS files are quite small and not many classes are used. This makes your styles flexible and powerful. Moreover, it's easy to customise particular sections exactly the way you need them.

Please Note: There is a file called base.css which is called by some styles using @import. This CSS contains some definitions which make theming easier due to it's generic settings for Javascript tabs, Suckerfush CSS dropdown menus, and others.

For details on actually editing CSS files, cascading selectors, and hacking around browser bugs, please consult the appropriate online guides or books.

Slideshows

Slideshows are a feature of Bitweaver's WikiPacakage and allow you to display a wiki page in a particular way without any excess information such as columns or banners. The slides are set up in a similar way as the wiki page and use the same classes. You can pick a theme that will be used when displaying wiki pages as a slideshow.

To use your own theme as the style for slideshows but would like something like 'larger text', you can create slideshow.css in your theme directory and add all your definitions in there. This file will be loaded in addition to your regular CSS and you can thus override any settings made above. Also, there is a folder called slideshows. It contains sample slideshow.css files, which you can copy (and rename) to your theme dir to use as blueprints.

So, the easiest method to enlarge your slideshow text, is to create a file called 'slideshow.css' in your theme directory and then copy and paste the content of 'slideshows/enlargetext.css' to that file and save - voila!

To illustrate, here is the content of enlargetext.css:

h1,.title {
  font-size: 2.4em;
  line-height: 120%;
}
.content {
  font-size: 1.3em;
  line-height: 120%;
}


Icons

In Bitweaver it is possible to use your own set of icons to give your site the ultimate in customisation and theming flexibility. Associate any icon with a given theme by creating an icon in the folder /themes/styles/style/icons/package/

The extension of the icon has to be: jpg, gif, png. Icons in the above location will override the original Bitweaver icon. This allows you to integrate icons without having to touch the source code.

Style Information

Create a folder called style_info in your style directory. In there, add a file called description.htm, which should contain a brief description of your theme in HTML format. Then, add a small preview thumbnail for the style named preview.ext (the extension doesn't matter).

This info is displayed to the admin of a Bitweaver install when he picks a style in Admin » Themes » Themes Manager'. It is also displayed then you upload your custom style to bitweaver.org so that others can download it.

Debugging help

If you create a style from scratch, here is a list of all CSS files present in /blank/ to aid you, see /themes/styles/blank/readme.css:
  • blank.css
    • main css file with all globally used classes and more
  • customisation.css
    • contains a list of classes that can be utilised to further customise the site
  • debugwithoutline.css
    • contains a set of classes and definitions that allow you to visualise all structures used on your site
  • showdiv.css
    • if included will visualise all divs used on the site including their classes and ids
    • (works well with debugwithoutline.css)
  • showstructure.css
    • like showdiv.css but it will show you all classes and structures appart from divs
    • (works well with showdiv.css and/or debugwithoutline.css
  • showsitelayout.css
    • visualises the layout of the main bit ids used by surrounding them with coloured lines
  • showpagelayout.css
    • draws coloured borders on one side of certain elements
    • to allow you to view the classes used without messing with your layout

To include one of these files in your own style for debugging purposes, insert
@import url("include.css"); at the top of your CSS file. Note that @import only works when it's before any definitions and that some more sophisticated debugging methods only work with advanced browsers.

Comments

Icons

by fire, 04 Apr 2005 (01:37 UTC)
Great Tutorial Xing!!

Can you elaborate on the icons? What is the best way to include your own icons?

Also, if I want an image rollover for the css menus... does bitweaver have any fancy way of pre-loading the required images?

Re: Icons

by dspt, 11 Feb 2006 (14:20 UTC)
a nice way to pre-load rollover images is not to pre-load the at all. I guess I first saw this method described at AListApart or somewhere...
the rollover images are stacked in single background file vertically, and on :hover the vertical position of background is changed in CSS

Re: Icons

by xing, 16 Apr 2005 (21:29 UTC)
sorry about the late reply....

anyway, i added some lines about the icons. it is quite easy to override the original icons and i have done this with the chemokine theme as an example. it's not a great theme, but it illustrates the fact that it's easy to use your own icons.

rollover images in the css menus is really quite difficult. i have created the olfactory theme as an example of a very simple rollover effect. i'm sure, this could be greatly enhanced and improved on, with some effort.

xing

Costume module settings???

by mj, 28 May 2009 (04:49 UTC)
Can anyone tell me more about the configure:custome modules? Also whats the easiest way to... say I download any ol css template how can I make it work with bitweaver fairly easily?

bitweaver/package/templates/

by Matt, 20 Oct 2009 (05:18 UTC)
There's no "package" directory in my install - do you mean the "kernel" directory in R2? (That's where I found some templates)
  Page 1 of 1  1