Structure of Custom Blogger Themes
The documentation for Blogger Themes is lacking and incorrect in many spots, making it really difficult to get started on your own. You could of course rip code segments from existing themes but that is hardly the best method to go about creating your own theme. This document will cover the basic structure of the Blogger theme. In future posts (linked at the end) I will cover more parts about Blogger Themes.
Blogger Themes are created using an XML Document (only one file). This single document specifies all cases of the website (index / archive / item) along with special styles for the “Widgets” you add to each section of your blog under the Layout section of Blogger Administration Panel. With all of this content in a single document, organization is key and understanding what everything does is even more important.
Basic Layout
Below is a very stripped down frame of the beginning layout of the XML document for a theme.
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html>
<html b:version="2" expr:dir="data:blog.languageDirection" xmlns="http://www.w3.org/1999/xhtml" xmlns:b="http://www.google.com/2005/gml/b" xmlns:data="http://www.google.com/2005/gml/data" xmlns:expr="http://www.google.com/2005/gml/expr">
<head>
<title><data:blog.pageTitle /></title>
<b:include data="blog" name="all-head-content" />
<b:include data="blog" name="google-analytics" />
</head>
<body>
</body>
</html>
For the most part, you will not need to change or remove anything that is displayed in the above code. The first line just creates the XML document and specifies it’s version and encoding. After that we just declare the DOCTYPE to html and set up the HTML namespaces.
The HTML namespaces required are for b, data and expr. The b
namespace is used for nearly every call to process various information.
As for the expr namespace, it’s use as “expression” to include data
inside of HTML attributes. And as you can probably guess, the data
namespace allows you to display dynamic and stored data onto the page.
In the HTML tag, you will also note the expr:dir. This creates a
normal dir attribute but Blogger handles the attribute as data from
Blogger instead of text because it’s prefix is expr:. The data
included is data:blog.languageDirection, which if you can’t guess is
LTR or RTL but in lowercase. If you would like to add plain text along
with data for an attribute, wrap your plain text in quotations and
include a plus symbol between the data and the string.
In the head tags, we set the title and include a data tag. These data
tags will pull data from the required resource in Blogger. The one
inside of the title tags is referencing the global blog resource
which stores various global information you will need (see other posts
at the bottom of the page for all data types).
After setting and escaping the data tag, we have two b:include tags
which will load the required resources we need. The attributes for
b:include are data which tells Blogger what data we should pass to
that b:includable along with name, which lists the includeable to
include at that location. An includable is a resource that can be
included. The two listed in the header are global and cannot be
modified. You will create an includable when customizing widgets for
your theme.
The rest of the document is laid out as a normal HTML template and acts just like one. Even when you add the following Blogger Tags in the HTML document, they will mostly turn into div’s or include another part of a template that will turn into div elements.
Working with b:section
Inside of your HTML body tag, you will have XML tags of b:section
These tags specify a section inside of the Layout for Blogger that
users can add widgets to. Section tags cannot contain HTML elements or
more sections, it can only contain b:widget tags. Below are the
attributes you can set for a section.
- id: (required) A unique identifier for the section. Will be added to the final HTML code for the ID attribute.
- class: (optional) A class attribute in the HTML Final Code. Using common class names, Blogger will attempt to transfer the correct widgets and gadgets to these sections when you switch themes later on. For example using “navbar”, “header”, “main”, “sidebar” and “footer” will successfully move the widgets to the correct locations.
- maxwidgets: (optional) The integer of the maximum widgets this section can contain. If no limit is specified of the attribute is omitted there will be no limit.
- showaddelement: (optional) A value of “yes” or “no” having “yes” as the default value. This determines if the section in the layout page will show a box to add new elements.
- growth: (optional) A value of “horizontal” or “vertical” with the value of “vertical” being the default. This value specifies how each widget will stack next to each other in a section.
<!-- Allow user to add more widgets / gadgets to this section with showaddelement -->
<b:section class="sidebar" id="sidebar" showaddelement="yes" growth="vertical">
<!-- Nothing can go here except b:widgets -->
</b:section>
<!-- Only have widgets here that the programmer defined since showaddelement is no -->
<b:section class="main" id="main" showaddelement="no" growth="vertical">
<!-- Nothing can go here except b:widgets -->
</b:section>
Working with b:widget
Widgets have to be placed inside of b:section tags and are used to
display content on your blog. A few examples of the widgets available
are “Blog”, “PageList”, “Header”, “Navbar” to list a few. Widgets
placed inside of sections are the default template widgets and can be
removed if not locked (check attributes below). You do not need to
modify widgets and can use them “as-is” by making the b:widget tag
close at the end of it’s declaration and not having any child elements.
Widgets that are customized are only customized to that section and for
that instance of the widget (as far as I can tell). Customized widgets
contain b:includable tags which tell Blogger how to display the
widget.
- id: (required) The ID for the widget. Has to be identical to the type plus trailing with a numeric value that is unique. Type Blog would have an id of Blog1 or Blog2.
- type: (required) The type of the widget. All types are listed under this attribute section.
- locked: (optional) A value of “yes” or “no” indicating if the widget can be moved or deleted from the specified section. The default value is “no”.
- title: (optional) The display title for the Widget. Will show up in the Widget Layout screen in Blogger. If omitted, will use the global Blogger titles for each widget.
- pageType: (optional) Declares what pages the widget should appear. Can have a value of “archive”, “main”, “item”, or “all”. With “all” being the default value. The widget will always appear in the Layout section of Blogger no matter what the pageType is set to.
- mobile: (optional) A value of “yes”, “no”, “default” or “only” declaring if the widget can appear on mobile devices. Only the Header, Blog, Profile, PageList, AdSense, Attribution will display on mobile devices when the value is set to default.
Widget Types
- Blog
- Feed
- Header
- HTML
- Image
- LinkList
- TextList
- BloggerButton
- BlogProfile
- Navbar
- VideoBar
- NewsBar
- PageList
- BlogList
- Text
- PopularPosts
- Stats
- PlusBadge
- PlusFollowers
- PlusOne
- Translate
- Label
- Poll
- Slideshow
- CustomSearch
- FollowByEmail
- BlogArchive
<b:section class="sidebar" id="sidebar" showaddelement="yes" growth="vertical">
<b:widget type="PageList" id="PageList" locked="no">
<!-- Have Includables here for custom widget layout and styles -->
</b:widget>
</b:section>
<b:section class="main" id="main" showaddelement="no" growth="vertical">
<!-- Have Blogger use the Default Layout for the widget since no children -->
<b:widget type="Blog" id="Blog1" locked="yes" />
</b:section>
Working with b:includable
This tag specifies how it should be handled if called upon to be
“included”. The tag has two attributes which can be id, a required
attribute and can be the same if exists inside of a different widget
tag. There has to be a includable with the id of “main” inside of each
b:widget. The main includable is what is called for the processing of
the widget. All other id’s can be named whatever they want since you
will manually code the call to them. The other attribute is var. This
attribute holds the data that is passed when you call b:include
with a data attribute. The var attribute is optional.
Inside the b:includable element, can be plain HTML along with calls
to include and data tags. Referencing a data tag while inside an
includable, will cause the reference of data to be changed to the
callers passed data (widget data). If the var is not set, the passed
data to the includable will be the root of data calls. If the var is
set, the root data will point to the widgets data instead and the var
will point to the passed data.
<b:section class="sidebar" id="sidebar" showaddelement="yes" growth="vertical">
<b:widget type="PageList" id="PageList" locked="no">
<b:includable id="main">
<ul>
<li>Page List Here, When I Know How To Loop</li>
</ul>
</b:includable>
</b:widget>
</b:section>
Working with b:loop
Looping in blogger is very important since a lot of data is in arrays, such as posts, labels, comments and lists. The loop will navigate through each of those elements in the array and give you a new data variable to reference that element.
The b:loop contains two attributes, one of which is values that
holds the full array of values you wish to loop through. Inside of the
Blog widget, you can loop through data:posts Since the b:loop element
isn’t plain HTML, you don’t have to call onto an expr to reference the
data.
The other attribute for b:loop is var The var will be a keyword you
will reference inside the loop to request the current element you are
on during the loop.
<b:section class="sidebar" id="sidebar" showaddelement="yes" growth="vertical">
<b:widget type="PageList" id="PageList" locked="no">
<b:includable id="main">
<ul>
<b:loop var="item" values="data:links">
<li>
<a expr:href="data:item.links.target"><data:item.title /></a>
</li>
</b:loop>
</ul>
</b:includable>
</b:widget>
</b:section>
<b:section class="main" id="main" showaddelement="no" growth="vertical">
<b:widget type="Blog" id="Blog1" locked="yes">
<b:includable id="main">
<b:loop var="item" values="data:posts">
<b:include name="post" data="item" />
</b:loop>
</b:includable>
<b:includable id="post" var="post">
<div>
Title: <data:post.title />
</div>
</b:includable>
</b:widget>
</b:section>
Working with b:if and b:else
You also are able to have if / else statements in Blogger Themes using
the XML tags of b:if and b:else. There is no else if statement so
you will have to create extra if tags to accomplish what you need. When
you use a b:else tag, make sure you escape it, since there is no
closing tag for it.
The b:if tag has one attribute of cond which is the if statement
query or condition. Inside of cond you can compare values using ==,
!=, >=, <=, >, and <. If you are comparing a data variable
with a string, the string has to be wrapped with double quotes. You
will often have to set the double quotes to the HTML Entities of a
quote instead of the ascii text of a quote. Also, the greater-than and
less-than symbols will need to be html encoded also since XML doesn’t
allow those symbols inside of attributes.
<b:if cond='data:blog.pageType == "item"'>
<div>Page Type: Item</div>
<b:else />
<div>Page Type: Else</div>
</b:if>
<b:if cond='data:blog.url != data:blog.homepageUrl'>
<div>Home Page: False</div>
<b:else />
<div>Home Page: True</div>
</b:if>
<b:if cond='data:blog.isMobileRequest'>
<div>Mobile: True</div>
<b:else />
<div>Mobile: False</div>
</b:if>
Working with b:skin
All of your styles and Advanced Variables will be defined in the
b:skin tag, located in the head tag of the document. The data
inside of b:skin has to be CDATA and cannot be a style tag like some
Google documentation mentions.
Inside of the CDATA you can place all of your CSS for the page. You can have external CSS loaded also by using a link tag outside of the skin tag, but then you won’t be able to reference the user defined styles and variables.
Before your CSS begins, but while still in the CDATA, you can create a
CSS comment /* comment */ that defines Variable’s that the user can
modify in the Blogger template editor. These variables will setup the
type of variable, the value, the default value, variable name, variable
description and the variants of that variable.
To setup variant color themes you need to have a variable that has the
name of “keycolor”. If you do not have this variable, the variants
will not appear under the “Background” customize tab in Blogger.
Variable Attributes
- name: The name of the attribute that at a later date will be used to reference the variables value. You can reference the name by adding
$(name)inside of your style declarations. - description: A description or headline of what the element will modify. Only appears inside the Blogger Advanced color settings.
- type: The type of variable to set. Can either be font or color. There are rumored to be more but there is no documentation or hidden codes to show otherwise.
- default: The default value for the variable. If the value isn’t set or the user resets all variables, this is what the color will end up becoming.
- value: The value of the variable. Should be omitted or set to the default value when releasing or publishing your theme so the end user will get the true value.
- variants: A comma separated list of the variants for different themes / color schemes.
Groups
Along with variables, you can also place the variables inside of
Group tags which will highlight a section of the page of where you
are editing and group multiple variables together. Groups have two
attributes, a description and a selector. The description is what
describes to the user what they are editing, such as Blog Titles or
Post Links. The selector will tell Blogger which section of the page to
highlight to give the user a visual representation of what they are
editing.
<b:skin>
<![CDATA[
/*
<Variable name="keycolor" description="Theme KeyColor" type="color" default="#eeeeee" variants="#ff0000,#00ff00" />
<Variable name="siteFont" description="Font Style" type="font" default="14px 'Open Sans',sans-serif" />
<Variable name="siteBackground" description="Background" type="color" default="#eeeeee" variants="#ff0000,#00ff00" />
<Group description="Navigation" selector="#navigation">
<Variable name="navigationBackground" description="Background" type="color" default="#c14545" />
<Variable name="navigationFont" description="Font Style" type="font" default="18px 'Open Sans',sans-serif" />
<Variable name="navigationFontColor" description="Font Color" type="color" default="#ffffff" />
</Group>
*/
* {
padding: 0px;
margin: 0px;
}
body {
background: $(siteBackground);
font: $(siteFont);
}
#navigation {
color: $(navigationFontColor);
font: $(navigationFont);
background: $(navigationBackground);
}
]]>
</b:skin>