Understanding the Blogger Template - 2 Jan 26, 2009

The blogger template is a xhtml document which is rendered based on variables. These tutorials aims at helping to understand the blogger template and hence to experiment, learn and change it. Blogger template has mainly three types of variables one which controls the flow of the code, one which pulls data from the databases behind and the third are expressions. This variables are then distinguished with the help of following xml namespaces.

This is second in the series of the three tutorial for Blogger Template and deals mainly with the explanation of the data: namespace and understanding how to access its vars.

1. Blogger Template Explanation - Sections, widgets, includables, includes. b: namespace
   


2. Blogger Template Explanation - Data access. data: namespace elements.
   


3. Blogger Template Explanation - How to use expr: namespace - customize links.
   

Data namespace contains the most important tags as this is the way you access your data. Maybe I would write a separate blog for this one, but the basics are here. The namespace is basically a way to identify and maintain uniqueness in when large number of elements are present. The expression for identifying a element uniquely in xml documents is as in [namespace-identifier]:[the-tag]. The data here is the namespace identifier and have further unique elements. A namespace basically helps in identifying or giving a variable unqiue name.

There are many types of data variables. Some of them are available globally. By globally I mean they can be accessed anywhere whereas the certain tags/identifiers can only be accessed from certain widgets. That is how it works.

The Globally available data in Blogger template

This data is available everywhere in your page. So use it wherever you like. These are referenced as part of the "blog" data, i.e., to be used as blog.title for referring for the title of the blog. Don't forget to include the namespace data in the begining. This code listing will explain the usage.

<!--[The blog's title.]-->
<data:blog.title/> 

<!--[
The type of the current page. One of 'item', 'archive', or 'index'.
This var is quite useful for selectively showing content on 
different type of pages. Put an if and check if its index page or 
item page and then display selective content
]-->
<data:blog.pageType/>

<!--  [The URL of the current page.]  -->
<data:blog.url/>

<!--  [The homepage of the blog.]  -->
<data:blog.homepageUrl/>

<!--[
The title of the current page. This is often the blog title, 
but may contain additional information on archive or post pages.
]-->
<data:blog.pageTitle/> 

<!--  [The encoding to use for the blog, e.g. UTF-8.]  -->
<data:blog.encoding/> 

<!--[
Either "ltr" or "rtl" for left-to-right 
and right-to-left languages, respectively.
]-->
<data:blog.languageDirection/> 

<!--  [The autodiscovery feed links for the page header.]  -->
<data:blog.feedLinks/> 

Apart from the data available globally there is data specific to specific widget types. Following is the list of widget types. For each of this widget there are different tags available and locally for each one.

1. Page Header


2. Blog Archives


3. Profile


4. Text / HTML / JavaScript


5. Feed


6. Picture


7. Labels


8. List


9. Link List


10. Logo


11. Blog Posts

Page Header widgets in Blogger template

This is basically used in the header section of your blog entry. Where the title and the description of the blog is given. This widget is a very simple one and has only two types of data variables for access. Note these don't require the usage as blog.identifier as in case of globally available data. This can be referenced directly in the Page Header type widget.

<!--[The blog's title. ]-->
<data:title/> 

<!-- [ The blog's description. ]-->
<data:description/>

Blog Archives in Blogger template

There are three types of display formats of blog archives- Menu, Flat and Hierarchy. If you're designing a new version, it's easiest to use 'FLAT' as the style, and then manipulate the rest of the data as desired. The key data are title, style and data . Data containing: the name of the archive duration; url of the posts; and post-counts in the duration.

1. title The title of the widget.


2. style One of 'MENU', 'FLAT', or 'HIERARCHY'.


3. data A list of each archive unit, each of which contains:




1. name: The name of this archive interval or period.


2. url: The link to the page containing posts from this interval.


3. post-count: How many posts there are in this interval.

Usage: Check the includable for flat. This can then be included as include in the main includable for display.

<!--[ Simple usage of title ]-->
<b:if cond='data:title'>
 <h2><data:title/></h2>
</b:if>

<!--[ For a includable flat type ]-->
<b:includable id='flat' var='data'>
 <ul>
  <b:loop values='data:data' var='i'>
   <li class='archivedate'>
    <a expr:href='data:i.url'>
     <data:i.name/>
    </a>
    (<data:i.post-count/>)
   </li>
  </b:loop>
 </ul>
</b:includable>

Profile Widget in Blogger template

This is the profile of the author. There can be one author of a blog or maybe the blog has a team of authors. For a blog with a single author, the profile widget contains the following information.

1. title The title of the widget.


2. userUrl The author's profile URL.


3. location The location from the author's profile.


4. aboutme The "About Me" information from the profile.


5. displayname The author's display name.


6. photo The user's profile photo, made up of the following:




1. url: The photo URL.


2. width: The photo's width, in pixels.


3. height: The photo's height, in pixels.


4. alt: The "alt" text for the photo.

Team blog widgets contain less information compare to single blog widgets. The tags are:

1. title: The title of the widget.


2. authors: The list of all authors, each of which contains the following:




1. displayname: The author's display name.


2. userURL: The author's profile URL.

If you want to design your template to handle both single- and multiple-author blogs, you can use the data:team variable to distinguish between the two cases as shown below.

<b:if cond='data:team=="true"'> 
 <!--[display multiple authors] -->
</b:if>

Text / HTML / JavaScript Widget in Blogger template

HTML / Javascript and Text widgets are very simple widgets and contain only two data elements.

1. title: The widget's title.


2. content: The content of the widget.

Usage of title and content is similar in all widgets (refer Archives code usage above).

Feed Widget in Blogger template

Feed widget like any other widget has tags for accessing its own information and along with that has feedData. This feedData contains all items in the feed. items being like title, published date, author, summary etc. So basically this feedData is a set of data. You may now have remembered the loop tag (check the previous tut in the series), we have to use that to access each item from the set of items.

1. title: The widget's title.


2. feedUrl: The URL of the feed.


3. feedData: The items in the feed, each of which contains:




1. title: the item title.


2. str_published: When the item was published (nicely formatted in blog's timezone).


3. published: When the item was published (in seconds since epoch).


4. str_updated: When the item was last updated (nicely formatted in blog's timezone).


5. updated: When the item was last updated (in seconds since epoch).


6. author: The item's author.


7. summary: A snippet from the item, if available.


8. alternate: Where to get more information about this item, which contains:




1. href: The permalink of this item.


2. type: The content-type of this item.

Picture Widget in Blogger template

A picture widget contains a single image, and provides all the relevant data for that image.

1. title: The title of the widget.


2. sourceUrl: The URL of the image.


3. width: The image's width, in pixels.


4. height: The image's height, in pixels.


5. caption: The image caption.

Labels Widget in Blogger template

The labels widget includes a list of all labels that are in use on the blog.

1. title: The widget title.


2. labels: The list of labels, each of which contains:




1. name: The text of the label.


2. count: How many posts have this label.


3. url: A link to a page displaying posts with this label.

List Widget in Blogger template

The simplest form of a list. Each item is just a single piece of text, without any different types of data within it.

1. title: The widget title.


2. items: The list of items.

Usage: Similar to link list below.

Link List Widget in Blogger template

A slightly fancier list, where each item has two parts to it: the text and the link.

1. title: The widget title.


2. links: The list of links, each of which contains:




1. name: The link's text.


2. target: The link's URL.

Usage:

<!--[Check the complete implementaion of the linklist widget. ]-->
<b:widget id='LinkList1' locked='false' title='More Blogs' type='LinkList'>
 <b:includable id='main'>
  <b:if cond='data:title'>
   <h2><data:title/></h2>
  </b:if>
  <div class='widget-content'>
   <ul>
    <b:loop values='data:links' var='link'>
     <li>
      <a expr:href='data:link.target'>
       <data:link.name/>
      </a>
     </li>
    </b:loop>
   </ul>
   <b:include name='quickedit'/>
  </div>
 </b:includable>
</b:widget>

Logo in Blogger template

It doesn't get any simpler than this one. Just one piece of data here.

1. fullButton: The URL of the Blogger button you've selected.

Blog Post Widget in Blogger template

This is the central part of any blog, and the most complex. You should definitely consider simply making modifications to one of the default templates before writing a blog posts widget from scratch. But however you want to do it, here's all the data available in this widget.

1. feedLinks: A list of feeds for this page. On the main page, this will contain the main blog feeds; on item pages, this will also contain comments feeds. The blog post widget has a includable created as feedlinks, which in turn uses another includable feedlinksbody. Each item in this list contains the following:




1. url: The feed URL.


2. name: The feed name (i.e. 'Posts' or 'Comments').


3. feedType: The type of feed (Atom or RSS).


4. mimeType: The mime type of the feed.




2. olderPageUrl: If there are older posts than the ones on the current page, this is a URL to those posts. Context-sensitive for page type. (Not all pages will have this link. use if)


3. olderPageTitle: Title of the link to the older page of posts.


4. newerPageUrl: The newer equivalent of olderPageUrl.


5. newerPageTitle: The newer equivalent of olderPageTitle.


6. commentLabel: The phrase to use to show the number of comments, e.g. "comments."


7. authorLabel: The phrase to use to indicate who wrote the post, e.g. "posted by."


8. timestampLabel: The phrase to use to indicate when the post was written, e.g. "posted at."


9. postLabelsLabel: Phrase to introduce the list of post labels, e.g. "labels for this post."


10. backlinksLabel: Phrase to describe backlinks to this post, e.g. "links to this post."


11. posts: A list of all posts for this page. Each post contains the following:




1. dateHeader: The date of this post, only present if this is the first post in the list that was posted on this day.


2. id: The numeric post ID.


3. title: The post's title.


4. body: The content of the post.


5. author: The display name of the post author.


6. url: The permalink of this post.


7. timestamp: The post's timestamp. Unlike dateHeader, this exists for every post.


8. labels: The list of the post's labels. Each label contains the following:




1. name: The label text.


2. url: The URL of the page that lists all posts in this blog with this label.


3. isLast: True or false. Whether this label is the last one in the list (useful for placing commas).




9. allowComments: 'True' if this post allows comments.


10. numComments: The number of comments on this post.


11. showBacklinks: Whether to show backlinks for this post.


12. numBacklinks: Number of backlinks for this post.


13. addCommentUrl: The URL of the 'add a comment' form for this post.


14. emailPostUrl: The URL of the 'email this post' form for this post.


15. editUrl: The URL of the edit form for this post.


16. feedLinks: A list of feeds specific to this post. (This is different from the overall blog feedLinks, as it may contain a feed for the post's comments, for instance.) Each contains the following:




1. url: The feed URL.


2. name: The feed name (e.g. 'Posts' or 'Comments').


3. feedType: The type of feed (Atom or RSS).


4. mimeType: The mime type of the feed.




17. comments: A list of all comments for this post (on item pages only). Each contains the following:




1. id: The numeric ID of the comment.


2. body: The body of the comment.


3. timestamp: The time the comment was created.


4. author: The display name of the comment's author, or 'Anonymous'.


5. authorUrl: URL of the comment author's profile, if the comment is not anonymous.


6. deleteUrl: The URL for deleting this comment.


7. isDeleted: Whether this comment has been deleted. (The text of deleted comments is replaced with a placeholder.)

<!-- [Using feedlinks ]-->
<!-- [feedlinks for the blog can be used displayed using the elements in this way. ]-->
<data:feedlinks.url/>
<!-- [whereas feedlinks for a post which include e.g. comments can be shown this way. ]-->
<data:post.feedlinks.url/>


<!--[
if inside a includable and a var is assigned to it while using the include 
then use it in this manner
]-->
<b:include data='post.feedLinks' name='feedLinksBody'/>
<b:includable id='feedLinksBody' var='links'>
 <b:loop values='data:links' var='f'>
  <a class='feed-link' expr:href='data:f.url' expr:type='data:f.mimeType'>
   <data:f.name/> (<data:f.feedType/>)
  </a>
 </b:loop>
</b:includable>

So from the above list the data elements which are in the main list can be accesed directly like in case of blog feedlinks above. The sub-lists to the main can be accessed using the dot operator i.e., similar to object oriented programming where the [classNameVar].[objectVar] gives you access to the object variable of a class. So to access variables deeper in the list keep using dot operators.

<!--[
For accessing the comment id you will have to use either the 
includable method shown previously or use this one.
]-->
<data:post.comments.id/>
<!-- [but you should use includable as they are cool :) ]-->

Sometimes when you try to use this data elements directly it gives error. Either your widget / section won't work or something like that would happen. One of the reasons is that you can't use this expressions directly. You have to use the expression namespace which I have introduced you in the previous tutorial. As the tutorail on data namespace has already got to big. I will continue the expr:[vars] namespace in the next tutorial. Althought I guess that won't be this big :).

I have tried to explain a lot of things here. But if you want or have a better explanation add it up in comments. If you have any doubts put them here would answer them if I know :). Let me know thy feedback.