Themes and Macros

 

Themes (From Version 1.8 Readme)

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 introduces 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.
Note, however that 99% of themes DO NOT use named assets, so chances our yours doesn’t either. So, the first time your theme loads, if there isn’t a theme.manifest we will generate one for you. If your theme looks funky or changes between 1.7 and 1.8, perhaps you need to include your named assets in the theme.manifest file that were previously expressed in your web.config.
<?xml version="1.0" encoding="utf-8" ?>
<theme name="discreetBlogBlue" title="Discreet Blog Blue" templateDirectory="themes/discreetBlogBlue"
            imageDirectory="themes/discreetBlogBlue">
    <image name="itemLink" fileName="images\bryanbell\discreetBlogBlue\bluePermaLink.gif" />
    <image name="dayLink" fileName="images\bryanbell\discreetBlogBlue\bluePermaLink.gif" />
</theme>

Again 99% of users won’t need to do a thing to get themes working in 1.8; they will just work.
Tip: Check your themes templates if you think something odd is happening. There may be hardcoded text in the HTML for disclaimers or links.

Most of the following information is the original Clemons Vasters Documention,  for versions (1.0 - 1.7) it is here for history and general information.

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 blog-website of dasBlog 1.1 you can 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, which are documented here in all their glory, 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 lit 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.

Registering Themes

In your site’s web.config file, you will find a section that looks, by default, like this:

    <newtelligence.DasBlog.Themes>

            <theme name="candidBlue"
                   title="Candid Blue"
                   templateDirectory="themes/candidBlue"

                   imageDirectory="themes/candidBlue" />

            <theme name="default"
                   title="Discreet Blog Blue"
                   templateDirectory="themes/discreetBlogBlue"

                   imageDirectory="themes/discreetBlogBlue">

               <image name="itemLink"
                      fileName="images\bryanbell\discreetBlogBlue\bluePermaLink.gif" />

               <image name="dayLink"
                      fileName="images\bryanbell\discreetBlogBlue\bluePermaLink.gif" />

            </theme>

            <theme name="movableRadioBlue"
                   title="Movable Radio Blue"
                   templateDirectory="themes/movableRadioBlue"

                   imageDirectory="themes/movableRadioBlue" />

            <theme name="movableRadioHeat"
                   title="Movable Radio Heat"
                   templateDirectory="themes/movableRadioHeat"

                   imageDirectory="themes/movableRadioHeat" />

            <theme name="soundWaves"
                   title="Sound Waves"
                   templateDirectory="themes/soundWaves"

                   imageDirectory="themes/soundWaves" />

            <theme name="justhtml"
                   title="Just Html"
                   templateDirectory="themes/justhtml"

                    imageDirectory="themes/justhtml" />
      </newtelligence.DasBlog.Themes>

This section contains the names, titles and the location for all of your themes. It’s important to note that the names must be unique within the template collection, otherwise dasBlog will simply fail to start up properly. The templateDirectory attribute 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>

If you want to add a theme, create a new directory somewhere below the site root, create a matching entry in this section and place your new files there.

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 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.

List of Macros available for use in templates!

<%macroname%>

Description

Output

 

CSS Styles

homeTemplate Macros

 

<%title%>

Weblog 'Title' as defined through the tag <Title> in the configuration file of the Web application.

Plain text

 

-

<%subtitle%>

Weblog 'SubTitle' as defined through the tag <Subtitle> in the configuration file of the Web application.

Plain text

 

-

<%radioBadge%>

Emits text 'newtelligence DasBlog (version)' and version number.

Plain text

 

-

<%rssLink%>

Hyperlink to the main RSS feed.

HTML hyperlinked HTML image

 

<a> tag, rssLinkStyle

<%atomLink%>

Hyperlink to the Atom feed.

HTML Hyperlink

 

<a> tag, atomLinkStyle

<%year%>

Current year.

Plain text

 

-

<%month%>

Current month.

Plain text

 

-

<%day%>

Current day.

Plain text

 

-

<%today%>

Current day formatted as short date.

Plain text

 

-

<%now%>

Current time (UTC).

Plain text

 

-

<%time%>

Current time formatted as short time.

Plain text

 

-

<%authorName%>

Copyright owner as defined through the tag <Copyright> in the configuration file of the Web application.

Plain text

 

-

<%bodytext%>

Placeholder for rendering page content.

HTML

 

bodyContentStyle

<%titleList%>

List of entry titles that are displayed on the current page.

HTML

 

Table <table>: titleListStyle;
Cells <td>: titleListCellStyle;
Hyperlinks <a>: titleListLinkStyle

<%frontPageTitleList%>

List of entry titles that appear on the current front page. Uses the same CSS classes as TitleList.

HTML

 

Table <table>: titleListStyle;
Cells <td>: titleListCellStyle;
Hyperlinks <a>: titleListLinkStyle

<%siteName%>

Weblog 'Title' as defined through the tag <Title> in the configuration file of the Web application. Same as <%title%>.

Plain text

 

-

<%description%>

Site description as defined through the tag <Description> in the configuration file of the Web application.

Plain text

 

-

<%navigatorLinks%>

Renders a list of user-definable hyperlinks.

HTML

 

Container <div>: navigatorLinksContainerStyle;
Table <table>: navigatorLinksTableStyle;
Cell <td>: navigatorLinksCellStyle;
Hyperlinks <a>: navigatorLinksLinkStyle

dayTemplate Macros

Available for the dayTemplate and itemTemplate only

<%archiveLink%>

Hyperlink to archived entries. Works hand in hand with <%longDate%>

HTML hyperlinked HTML image

 

Hyperlink <a>: archiveLinkStyle
Image: archiveLinkImageStyle

<%longDate%>

Protected field DayMacros.day formatted as long date. Works hand in hand with <%archiveLink%>

Plain text

 

-

<%items%>

Placeholder for rendering weblog entries.

HTML

 

Controlled by the itemTemplate file.

itemTemplate Macros

 Available for itemTemplate only

 

<%itemText%>

The text of a single weblog entry.

Plain text

 

-

<%itemTitle%>

The title of a single weblog entry.

Plain text

 

-

<%itemDescription%>

The Description of a single weblog entry.

Plain text

 

-

<%when%>

The DateTime (formatted like in GMT) the entry was created.

Plain text

 

-

<%permaLink%>

A placeholder for rendering a permanent hyperlink for the current weblog entry.

HTML

 

Hyperlink <a>: permalinkStyle
Image: permalinkImageStyle

<%commentLink%>

An HTML hyperlink to view comments on weblog entries.

HTML

 

commentLinkStyle

<%trackbackLink%>

An HTML hyperlink to the Trackback endpoint.

HTML hyperlink

 

trackbackLinkStyle

<%trackbackList%>

A placeholder to render a list of hyperlinks with referrers, trackbacks and pingbacks.

HTML hyperlinks

 

trackbackLinkStyle

<%categoryLinks%>

Renders a list of links to the categories this item belongs to.

HTML

 

categoryLinkStyle

<%editButton%>

A placeholder for accessing the edit and delete buttons when logged in.

HTML

 

Hyperlink <a>: editLinkStyle
Image: editLinkImageStyle
Hyperlink <a>: deleteLinkStyle
Image: deleteLinkImageStyle

Radio Userland compatible Macros

<%radio.macros.imageUrl(relativeUrl)%>

Returns an absolute URL to an image based on a partial URL contained in a design template.

Plain text

 

-

<%radio.macros.imageRef(relativeUrl)%>

Returns an absolute URL to an image based on a partial URL relative to the Radio system path. Renders one <img> tag.

HTML image

 

simpleImageStyle

<%radio.macros.headlinks()%>

This macro renders a set of <link> and <meta> tags for including in the <head> section of the page.

HTML

 

 

<%radio.macros.blogroll(opmlFileUrl)%>

This macro renders an OPML outline. The outline is displayed as an hierarchical list.

HTML

 

Outermost container (<div>): blogRollContainerStyle
Contained table (<table>):  blogRollTableStyle
Table cells (<td>):  blogRollCellStyle
RSS Hyperlink (<a>):  blogRollXmlLinkStyle
Text Hyperlink (<div>): blogRollLinkStyle
Nested outline header table (<table>):  blogRollNestedOutlineHeaderTableStyle
Collapsed nested outline (<div>): blogRollCollapsed
Expanded nested outline (<div>): blogRollExpanded
Nested outline header image cell (<td>): blogRollNestedOutlineBadgeCellStyle
Nested outline header text cell (<td>): blogRollNestedOutlineTitleCellStyle
Nested outline header image link (<a>): blogRollNestedOutlineBadgeStyle
Nested outline header image link (<a>): blogRollNestedOutlineTitleStyle
Nested outline header image cell (<td>): blogRollNestedOutlineBadgeStyle
Nested outline body table (<table>): blogRollNestedOutlineBodyTableStyle

<%radio.macros.weblogUrl()%>

The URL of this weblog.

Plain text

 

-

<%radio.macros.editThisPageButton()%>

Ignored in this version.

Nothing

 

-

<%radio.macros.editorsOnlyMenu()%>

Renders the administrator bar (AdminNavBar.ascx), if the user is logged and is member of the "admin" role.

HTML

 

adminNavbarStyle

<%radio.macros.xmlCoffeeMug()%>

Generates a text link to the (equivalent of) the Radio coffee mug.

HTML hyperlink

 

xmlCoffeeMugStyle

<%radio.macros.mailTo()%>

Generates a link to the author's email address or some page providing feedback capability. Renders one <a> tag with the CSS class "mailToStyle" and an embedded <img> tage with the CSS class "mailToImageStyle".

HTML

 

Hyperlink <a>: mailToStyle
Image: mailToImageStyle

<%radio.macros.getLastUpdate()%>

Renders the time of the last site update, expressed in GMT.

-

 

-

<%radio.macros.staticSiteStatsImage()%>

Not used in this version.

-

 

-

<%radio.macros.googleIt(expression)%>

Renders a search hyperlink, pointing to Google.com. The search expression is the title as passed the macro.

HTML hyperlink

 

 

<%radio.macros.weblogEditBox()%>

Renders (Placeholder) the EditEntryBox control.

HTML

 

Container (div): bodyContentStyle
topic: pageTopic

<%radio.macros.weblogRecentPosts()%>

Creates an empty placeholder (?)

-

 

-

<%DrawTagCloud()%>

Renders plain text: 'cloud links'.

Plain text

 

-<%radio.macros.cloudLinks()%> (