Themes (From Version 1.9 forward)

One of our goals is to make it easier to share Themes for use within DasBlog. However, earlier versions would require you to copy/unzip the theme into the themes folder AND include a bunch of information about the themes paths and assets within the web.config. Users and Theme Authors alike found this tedious. So, DasBlog 1.8 introduced the concept of “Theme Manifests” to promote xcopy installation and distribution of new themes.

Each theme directory needs a theme.manifest file that describes the name, title, and relative directory of that them, including any optional “named assets.” For example, this manifest includes custom images for the itemLink and dayLink.

<?xml version="1.0" encoding="utf-8" ?>
<theme name="dasblueblog" title="dasblueblog" templateDirectory="themes/dasblueblog" imageDirectory="themes/dasblueblog">
    <image name="dayLink" fileName="dayLink.gif" />
</theme>

How do themes’ and templates work?

Here’s a quick overview on how themes and templates work in dasBlog:

Whenever dasBlog renders an HTML page, it does so using templates from one of the configured themes, which are installed for the current dasBlog site. A theme is a set of templates and bitmaps that define the appearance of the pages in your blog.

Themes & Templates Basics

In any dasBlog website you will find, by default, a “themes” subdirectory that contains several subdirectories, named “candidBlue”, discreetBlogBlue”, “justHtml” and so on. In each directory you will find at least three files:

· homeTemplate.blogtemplate

· dayTemplate.blogtemplate

· itemTemplate.blogtemplate

If you look at these files in a text editor, you will find that all of them contain HTML fragments with a couple of strange tags which are enclosed in “<%” and “%>” marks. These are macros and we’ll get to them in a moment.

The homeTemplate.blogtemplate file contains the main template for all HTML pages rendered by the engine when using the theme. It contains a complete HTML page instrumented with macros that automatically render elements such as the title, the footer area, the calendar and all the other elements that are common for every page.

The dayTemplate.blogtemplate file contains the template for each “day”  that is rendered for the front page, the category pages and for the pages, you get to when you select a date from the calendar. The dayTemplate is rendered for each day for which blog entries are found. The populated fragments that result from processing the macros for a single day are rendered, directly following each other, as the replacement text for the <%bodytext%> macro of the homeTemplate.

The itemTemplate.blogtemplate file contains the blog template for every blog-entry rendered onto a page. All items for a particular day are rendered as a sequence of processed itemTemplates inside the <%items%> macro in the dayTemplate.

The macros, behave differently depending on the page and on whether you are logged in as administrator or are just a visitor. For all of the administration pages, the <%bodytext%> macro in the homeTemplate will not resolve into a list of items, but rather into the body of the administration page you want to work with. The same applies to the comment page, for instance.

In each theme directory you can create subdirectories that correspond to the names of the categories on your blog. If you have a category “My Dog” and create a subdirectory called “My Dog”, you can store a different set of templates there. This set will be used for the category page.

It’s important to note that the theme names be unique within the themes directorry, otherwise dasBlog will simply fail to start up properly. The templateDirectory attribute in the manifest contains a relative path from your site’s main directory to the directory where the *.blogtemplate files for a theme can be found. The imageDirectory attribute points to the directory where the images for that theme can be found. The Radio Userland compatible macro <%radio.macros.imageUrl(‘filename’)%> will properly resolve references to images inside your template to this location and the <%radio.macros.imageRef(‘filename’)%> macro will insert a complete <img> tag. The arguments to these macros are paths to filenames that are relative to the imageDirectory of a theme. So, if you use <%radio.macros.imageUrl(‘myphoto.jpg’)%> the macro will return an absolute URL to the file ‘myphoto.jpg’ in the current theme’s imageDirectory.

If you don’t like one or multiple of these themes, it’s safe to remove them, but you must have at least one theme and that theme must be defined as the default theme in the siteConfig/site.config file; so, for instance, like this: <Theme>default</Theme>

Adding themes:

If you want to add a theme, create a new directory in the themes directory with an appropriate manifest file and new supporting files.

A bit special are the <image> entries that you can find illustrated embedded in the entry for the “default” theme in the example above. DasBlog uses a set of standard images for rendering some of its elements, such as the “permalink” image (itemLink.gif) , the calendar day image () or the images for the administrator mode such as the edit ( editbutton.gif) or delete ( deletebutton.gif) images. All of these images can be replaced by a theme in two ways. The first, and simplest method, is to place a file with the same name as one of the standard files into your theme directory. In this case, the files must also be using the GIF format just as the default images. If you want to replace the files with files having a different name or file format, you can create an <image> entry as shown above. The <image> entry’s name must be the name of the image that should be overridden (without the file extension) and the fileName must be a file name relative to the theme’s imageDirectory.

You can select the current theme for your site simply on the configuration page or by modifying the <Theme> entry in the siteConfig/site.config directory.

Modifying or Creating Themes:

Modifying or creating new themes is quite easy if you know your HTML. All you need is an HTML editor that, preferably, knows a bit about style sheets, the "macro reference" below and with a bit of looking around in the existing themes.

One thing you will find is that dasBlog renders a couple of quite complex elements by itself that cannot be found in those templates. However, the appearance of all of these elements can be tightly controlled using cascading style sheets (CSS), because we defined CSS classes for almost all elements dasBlog renders. So if you want to tweak the look of the calendar or the blogroll, you can do so using style sheets in your homeTemplate.

The CSS class names are documented alongside the macros that render the elements in the macro reference.

The above is pretty much all you need to know about themes in dasBlog.