Widget Tags for Layouts

The basic <b:widget> tags for creating widgets are described in Page Element Tags for Layouts. If you just want to use the Page Elements tab to work with everything, then that's all you need to know. However, if you want more fine-grained control, this article describes what you can put inside a widget, if you're working in the "Expand Widget Templates" mode of the Edit HTML page. 

The first thing to do is to add a closing tag. So this:

<b:widget [...attributes...] />

becomes this:
<b:widget [...attributes...]>
</b:widget>
Now with that out of the way, let's talk about what you can put between those tags.

Includes

Widget content is contained in "includable" sections, which have this format:
<b:includable id='main' var='thiswidget'>
    [insert whatever content you want here]
</b:includable>

The attributes are as follows:

·         id: (Required) A unique identifier made up of letters and numbers.

·         var: (Optional) An identifier made up of letters and numbers, for referencing data within this section. (See the data section below.)

Each widget must have one includable with id='main'. This will usually contain most or all of the content that will display for this widget, and in many cases it will be all you need.

If you make more includables with different IDs, they will not be displayed automatically. However, if you make an includable with id='new', then you can reference it in your main includable with <b:include name='new' /> and it will display that way.


The attributes for the b:include tag are as follows:

·         name: (Required) An identifier made up of letters and numbers. It must match the ID of an existing b:includable in the same widget.

·         data: (Optional) An expression or peice of data to pass on to the includable section. This will become the value of the var attribute in the includable.

Here is a simple example demonstrating the use of b:includable and b:include. Loops and data are described later in this article. The main thing to understand here is how the "main" section includes the "post" section within it. It passes along a post that it calls "i" and the included section references it as its var "p", then prints the title.

<b:includable id='main'>
   <b:loop var='i' values='posts'>
      <b:include name='post' data='i'/>
   </b:loop>
</b:includable>

<b:includable id='post' var='p'>
   Title: <data:p.title/>
</b:includable>

Includes are most useful if you have a section of code that you want to repeat multiple times in different places. You can just write the code once, put it inside a b:includable, then use b:include wherever you want it to appear. If you don't need to do that, then you can just stick with the single main includable and not worry about the rest. (Note that the main includable is included automically -- <b:include name='main'/> is unnecessary.)

Data

The data: tag is arguably one of the most important ones, since it's the avenue that brings in all of your actual content. Some examples of this tag are:

<data:title/>
or
<data:photo.url/>

The first example is simplest, and will work in most widgets, since most widgets have titles. All it does is print out the title of the widget. The second example shows a more complex variable, from which we select a particular component. A photo, say in the context of a profile widget, may have components such as url, height, and width. Using the "." notation indicates that we want the URL for this photo, rather than a URL from something else.

There is a great deal of data that you can access with the data: tag, and it varies depending on which widget you're working with. We've got a comprehensive list to help you find the data you need.

Loops

The b:loop tag lets you repeat a section of content multiple times. This is most commonly used for printing out each post in a list of posts for a given page, or each comment, or each label, etc. The general format for using loops is this:

<b:loop var='identifier' values='set-of-data'>
   [repeated content goes here]
</b:loop>

The 'identifier' part can be any name you choose, and will be used to stand in for each new item in the list, each time through the loop. A common convention is to simply call this "i". The set of data you specify for the values can be any piece of data described in the data tags article as being a list of items. For instance, in the blog posts widget, posts is a list. Code like the following will loop through each post, printing out the title for each one, with header tags around it.

<b:loop var='i' values='data:posts'>
   <h2><data:i.title/></h2>
</b:loop>
Notice how "i" takes on the value of each post in turn, so you can get the title from each one.

If / Else

You can use the b:if and b:else tags to display content in some places but not others. The general format is this:
<b:if cond='condition'>
   [content to display if condition is true]
<b:else/>
   [content to display if condition is false]
</b:if>

The b:else tag is optional. Without it, the result will be either the content listed in the b:if section or nothing. The closing </b:if> is required in each case, however. 

For "condition" you can put in anything that evaluates to either true or false. Some data tags are simply true/false values on their own, e.g. allowComments on a post. With other pieces of data, you can compare them with specific values to get a true or false. Here are some examples:

·         <b:if cond='data:post.showBacklinks'> True if the current post is set to show backlinks.

·         <b:if cond='data:blog.pageType == "item"'> True if the current page is an item page (post page).

·         <b:if cond='data:displayname != "Fred"'> True if this is not Fred's display name.

·         <b:if cond='data:post.numComments > 1'> True if the current post has more than one comment.