<p>It's time for part 2 of the LnBlog themes tutorial series. In this episode,
we'll cover modifying your sidebar. This will include a brief discussion of how
theme templates work as well as an introduction to the plugin system. In the
process, we will also create a very simple
and extremely unimpressive plugin. Note that in this tutorial, unlike the last
one, I will assume that you have a basic knowledge of HTML and CSS. This
tutorial will also include some PHP code, although I will nto assume a working
knowledge of PHP (although if you have one, it will help).</p>

<p>As you may recall from last time, LnBlog's theme system has a concept of
paths. This applies not only to images and style sheets, as we saw before, but
also to template. In other words, LnBlog will look for a given template first
in your blog's templates directory, second in the templates directory of your
current theme, and lastly in the templates for the default theme. This means
that you can easily modify the templates for each of your blogs individually or
for all of them at a time.</p>

<h4>Modifying the template</h4>
<p>Let's start by making a copy of your
<code>LnBlog/themes/default/templates/include_sidebar.php</code> file and saving
it on your local hard drive so we can play with it. If you open up the file in
a text editor, you'll notice that there's almost nothing in it. It should just
look like this:
<code style="white-space: pre">
<?php
global $EVENT_REGISTER;
$EVENT_REGISTER->activateEventFull($tmp=false, "sidebar", "OnOutput");
$EVENT_REGISTER->activateEventFull($tmp=false, "sidebar", "OutputComplete");
?>
</code>
Of course, if you don't know PHP, that's probably doesn't mean anything to you.
In fact, it probably doesn't mean much even if you <em>do</em> know PHP.
That's because this code is part of LnBlog's event system</p>

<p>As you may already know, the default page banner, menubar, and sidebar in
LnBlog are all implemented as plugins. If you open up your
<code>include_banner.php</code> or <code>include_menubar.php</code>, they'll
contain similar code. Basically, this code raises an <em>event</em>, i.e. it
tells LnBlog's event manager that something interesting is happening and any
plugin that's interested in this event better get it's act together. The event
manager them checks a list of plugins that signed up to be notified when this
event happens and tells them to do their thing.</p>

<p>Now, since this is a template, we can actually ad HTML code right into it.
For illustrative purposes, I'll add some of my favorite links to the sidebar.
Here's what the resulting code looks like:
<code style="white-space:pre">
&lt;?php
global $EVENT_REGISTER;
$EVENT_REGISTER-&gt;activateEventFull($tmp=false, "sidebar", "OnOutput");
?&gt;
&lt;h3&gt;Recommended Links&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href="http://blogs.msdn.com/oldnewthing/"&gt;The Old New Thing&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="http://www.securityfocus.com/"&gt;Security Focus&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="http://www.larkware.com/"&gt;The Daily Grind&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;?php
$EVENT_REGISTER-&gt;activateEventFull($tmp=false, "sidebar", "OutputComplete");
?&gt;
</code>
Notice that I broke the PHP code into two blocks and put the HTML in between
them. Since tempaltes are actually PHP files, anything inside the &lt;?php ?&gt;
tags is treated as PHP code, and anything outside them is treated as HTML.
If you're sharp, you probably noticed that I did this because of the event code:
I put my markup between the OnOutput and OutputComplete events.</p>

<p>If you save this file and upload it to your blog's templates directory,
you'll see your list of links in the sidebar. However, you'll notice that the
links are at the <em>bottom</em> of the sidebar. That's because all the plugins
are loaded by the OnOutput event. If you move the HTML code above that event,
then all your links will end up at the <em>top</em> of the sidebar. But what if
you want your links in the <em>middle</em> somewhere? Maybe you want your links
between your articles and your RSS feeds. Well, that's why this isn't the
recommended way to add to the sidebar.</p>

<h4>A simple sidebar plugin</h4>
<p>However, there is good news. Writing a simple plugin to display some links
in the sidebar is easy. Really easy. In fact, it's about a dozen lines of
boiler-plate PHP code with your HTML inserted in the middle. And once you have the
plugin written, it will be detected by the plugin manager and you will be able
to change where it appears in the sidebar by changing its load order in the
plugin loading configuration page.</p>

<p>Here's a plugin version of the links in the example above:
<code style="white-space:pre">
&lt;?php
class MyLinks extends Plugin {
   function MyLinks() {
      $this-&gt;plugin_desc = "Shows my favorite links in the sidebar";
      $this-&gt;plugin_version = "0.1.0";
   }

   function show_links() {
?&gt;
&lt;h3&gt;Recommended Links&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href="http://blogs.msdn.com/oldnewthing/"&gt;The Old New Thing&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="http://www.securityfocus.com/"&gt;Security Focus&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="http://www.larkware.com/"&gt;The Daily Grind&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;?php
   }
}

$plug = new MyLinks();
$plug-&gt;registerEventHandler("sidebar", "OnOutput", "show_links");
?&gt;
</code>
This is about the simplest plugin you can have. It is a simple PHP class with a
constructor that defines the version number and a short description, and a
single method that dumps some HTML output to the screen. Note at the bottom
that you have to create an instance of the class and register the method with
the event manager.</p>

<p>Now is probably a good time to mention that plugins use a path mechanism too.
In other words, you can have plugins that apply only to a single blog, just like
you can with theme template and style sheet. Just make a "plugins" directory in
the blog's directory and put the plugins there. They will be treated just like
a regular plugin, but no other blog will be able to see them.</p>

<p>So, now let's install your new plugin. Copy the above code and paste it into
a new file named <code>sidebar_mylinks.php</code>. Note that it is <em>very
important</em> that you not have any blank lines or spaces outside the PHP
&lt;?php >&gt; tags, as this will cause error messages due to the way PHP handles
output. Now, create that plugins directory in you blog's directory on the
server and upload the <code>sidebar_mylinks.php</code> file into it. If you
open up your blog in a web browser, you should see the new links. If you change
the load order of your sidebar_mylinks plugin from the plugin loading page, then
the link section will move in the sidebar.</p>

<p>If you want to have several independant sidebar sections, you can make copies
of this plugin to achieve that. Just change the HTML code, the plugin_desc on
the fourth line, and change all three instances of the name MyLinks to
MyOtherLinks, or something like that (the exact name doesn't matter, so long as
no two plugins have the same name). If you're feeling adventurous, you can also
adapt this to add markup to the banner or menubar by changing the "sidebar"
parameter in the registerEventHandler line to "banner" or "menubar".</p>

<p>You can download files for this tutorial <a
href="tutorial2_files.zip">here</a>. In the next installment, we'll go into
theming the content areas of a page, including templates for blog
entries. We'll also cover modifying the associated style sheets and possibly
adding some images.</p>

You can reply to this entry by leaving a comment below. You can send TrackBack pings to this URL. This entry accepts Pingbacks from other blogs. You can follow comments on this entry by subscribing to the RSS feed.

Add your comments #

A comment body is required. No HTML code allowed. URLs starting with http:// or ftp:// will be automatically converted to hyperlinks.