Widget Tags for Layouts

Includes are most useful if you have a section of code that you want to re-use in several different places, or only include in certain circumstances.

To do this, write the content inside a b:includable, then use b:include wherever you want it to appear.

<b:includable id='main' var='thiswidget'>
  [insert whatever content you want here]
</b:includable>

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 piece of data to pass on to the includable section. This will become the value of the var attribute in the includable.
• cond (optional) An expression which causes the include to only execute when its result is true. This is the same as the cond attribute on a b:if.

Here's an example that shows how to use b:includable and b:include.

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 "p" and the included section references it as its var "post", then prints the title.

Note that the include only runs while the index is less than 10, so only a max of 10 posts would get rendered in this example (the index starts at 0).

 

<b:includable id='main'>
  <b:loop var='p' index='index' values='posts'>
    <b:include name='post' data='p' cond='index < 10'/>
  </b:loop>
</b:includable>
<b:includable id='post' var='post'>
  Title: <data:post.title/>
</b:includable>

The general format for using loops is this:

 

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

 

The 'identifier' (i) 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. 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 example, 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.

A loop tag allows you to iterate across an inclusive number range, such as ‘1 to 3', ‘-3 to -9', where the value of the variable takes the number's value. The following example would create an unordered list of 1, 2 and 3.

 

<b:loop var='i' values='1 to 3'>
  <li><data:i /></li>
</b:loop>

Loop tags also have an optional index attribute, which gives the zero-based index of the current iteration through the loop.

 

<ul>
  <b:loop var='number' index='index' values='9 to 7'>
    <li>Index: <data:index />, Number: <data:number /></li>
  </b:loop>
</ul>

 

This example would create an unordered list of:

• Index: 0, Number: 9
• Index: 1, Number: 8
• Index: 2, Number: 7

<b:if cond='condition'>
  [content to display if condition is true]
<b:elseif cond='another condition'/>
  [content to display if no previous if or elseif conditions have been true, and this elseif condition is true]
<b:else/>
  [content to display if no if or elseif conditions are met]
</b:if>

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:blog.pageType == "item" and data:post.showBacklinks'>
  True if the current page is an item page (post page) and the current post is set to show backlinks.
• <b:if cond='data:displayname != "Fred"'>
  True if this is not Fred's display name.
• <b:if cond='data:displayname == "Fred" or data:blog.pageType == "static_page"'>
  True if Fred is the display name, or the current page is a static page (not a post page).
• <b:if cond='data:post.numComments > 1'>
  True if the current post has more than one comment.
• <b:if cond='data:blog.pageType in {"static_page", "item"}'> OR <b:if cond='{"static_page", "item"} contains data:blog.pageType'>
  True if the current page is a specific post, or a page.

For a complicated style attribute based on data variables, you can compute it before the rest of the HTML output, so that the nested HTML is easier to read.

<b:with var='style'
       value='"background-image: url(\"" + data:sourceUrl "\"); "
           + " width: " + data:width + "px; " '>
 <div id='header-outer'>   
   <div id='header-inner' expr:style='data:style'>
     <h1>My Header</h1>
   </div>
 </div>
</b:with>

Note that the variable will only exist for the child nodes of the b:with tag.

In this widget, you can see example usages of the b:widget, b:includable (and b:include), b:if (and b:else), and b:loop tags.

 

<b:widget id='PageList1' locked='false' title='Pages' type='PageList'>
  <b:includable id='main'>
    <b:if cond='data:title != ""'>
      <h2><data:title/></h2>
    </b:if>
    <div class='widget-content'>
      <b:if cond='data:mobile'>
        <select expr:id='data:widget.instanceId + "_select"'>
        <b:loop values='data:links' var='link'>
          <b:if cond='data:link.isCurrentPage'>
            <option expr:value='data:link.href' selected='selected'><data:link.title/></option>
          <b:else/>
            <option expr:value='data:link.href'><data:link.title/></option> 
          </b:if>
        </b:loop>
        </select>
        <span class='pagelist-arrow'>&amp;#9660;</span>
      <b:else/>
        <ul>
        <b:loop values='data:links' var='link'>
          <b:if cond='data:link.isCurrentPage'>
            <li class='selected'>
              <a expr:href='data:link.href'><data:link.title/></a>
            </li>
          <b:else/>
            <li>
              <a expr:href='data:link.href'><data:link.title/></a>
            </li>
          </b:if>
        </b:loop>
        </ul>
      </b:if>
      <b:include name='quickedit'/>
    </div>
  </b:includable>
</b:widget>