The basic
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:
becomes this:
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:
[insert whatever content you want here]
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
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.
Title:
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 --
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:
or
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:
[repeated content goes here]
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.
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:
[content to display if condition is true]
[content to display if condition is false]
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
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:
