Serendipity templates utilize a page structure that includes a main content pane and sidebar containers, often positioned left and/or right of the main content. But what if you want a top or bottom "sidebar"? How about more than two?
How do you code that information into your template, and present - and secure - it to other users of your custom serendipity templates if they are publically distributed? Template configuration and Smarty code can easily provide the solution for any of your custom serendipity templates.
Wednesday, September 24. 2008
Additional sidebars for Serendipity templates


Serendipity provides 3 default sidebars - left, hidden and right. The hidden sidebar is used for positioning plugins that you do not necessarily want to delete, but also do not want to display on the front end.

3 sidebars by default for templates that do not define custom sidebars.
Many templates are available with additional sidebars. A recent release by Carl Galloway is his port of Dream City. Dream City defines additional sidebars of "top" and "middle". From "configure plugins", the template user can then assign sidebar items to any of these sidebar positions:

Dream City's 5 sidebar plugins, including left, hidden, right, top and middle.
This additional sidebar definition occurs in a template's config.inc.php file. In Dream City, the code is this:
$template_config = array(
array(
'var' => 'sidebars',
'name' => SIDEBAR_TITLE,
'type' => 'string',
'default' => 'left,hide,right,top,middle,'
)
A template user also sees this definition in "manage styles" anytime the template's configuration is modified:

Dream City's sidebar definitions viewable from "manage styles".
There is a potential danger lurking there, and while not obvious in this screenshot, it is from a screenshot taken from a different template (note the ominous warning: "please DON'T edit this field"):

Allowing a template user to change sidebars could break a template.
So, what is the danger? The reason for this is seen in a template's use of the very specific sidebar names. In the Dream City template's index.tpl file, the "top" sidebar is emitted using the following code, which will not work if the sidebar name is changed from "top" to anything else:
{serendipity_printSidebar side="top"}
Fortunately, this one is easy to fix. Simply change the sidebar from 'type' => 'string' to 'type' => 'hidden'. Your custom sidebars still exist, but can no longer be viewed or edited from "manage styles". If an admin really wanted to modify them, just edit the template's config.inc.php file. Thanks to Judebert for that tip a very long time ago!
EDIT 11 Nov 08:One critical piece of information I failed to mention when this entry was first written: In addition to changing the type from 'string' to 'hidden', you must also change 'default' to 'value'. So, using the above example, the modification would look like this:
$template_config = array(
array(
'var' => 'sidebars',
'name' => SIDEBAR_TITLE,
'type' => 'hidden',
'value' => 'left,hide,right,top,middle,'
)
Conditional code for sidebar processing.
Many templates that use custom sidebars process the sidebar code regardless of whether or not any sidebar items exist for that specific sidebar column. But what if you wanted to save some of grandma's performance pennies, or perhaps didn't want to emit a certain html container if, for instance, your "top" sidebar had no items? Smarty to the rescue!
Serendipity already gives us Smarty variables for our left and right sidebars, which respectively, are $leftSidebarElements and $rightSidebarElements. So if we wanted to conditionally process a block of code only if there truly are left side bar items, we could so something like this in our smarty tpl file:
{if $leftSidebarElements > 0}
<div id="serendipityLeftSideBar">
{serendipity_printSidebar side="left"}
<div>
{/if}
We can create our own smarty variables to do exactly the same thing for our custom sidebars as well. Using the above example of a "top" sidebar, this is what we need to add in our config.inc.php file, which I tend to place at the very end of the file:
$topSidebarElements = serendipity_plugin_api::count_plugins('top');
$serendipity['smarty']->assign_by_ref('topSidebarElements', $topSidebarElements);
So, just like $leftSidebarElements and $rightSidebarElements, we now have $topSidebarElements, and can emit code only if sidebar items have actually been assigned to that custom sidebar. Thanks to Abdussamad for turning me onto that concept a long time ago!
So there you have it! Any number of sidebars for your template. It is worth noting that screen width does disappear quickly with a bunch of sidebars. Horizontal scrolling is usually something to be avoided, so only add additional sidebars where you truly need them, and not just because "you can".
If you enjoyed this article, please bookmark it at your favorite social bookmarking sites using the Bookmark button below so that others will enjoy it as well!
5 Comments
| No Trackbacks
Defined tags for this entry: Serendipity - Tutorials, serendipity themes
Carl
Homepage
09/24/2008 10:48PM
Abdussamad
Homepage
10/13/2008 12:11AM
On your test installation database truncate (delete all records) in the table serendipity_options. This table is used to store template options. Now try and select your theme and save its options from the manage styles page. You will find that the sidebar data is not saved. The reason it worked before is because you had saved the sidebar variable when type was set to text.
Don Chambers
Homepage
10/17/2008 10:02AM
The custom sidebar functioned perfectly. I was able to add new sidebar items, save my settings, and return to them just fine.
Perhaps it was a problem that has since been resolved. I have successfully tested this in both 1.3.1 and 1.4 alpha 1.
Jens
Homepage
11/10/2008 11:18PM
Don Chambers
Homepage
11/11/2008 11:27AM
I said change 'string' to 'hidden'. But there was another important piece of information I neglected to mention.
Instead of 'default' => 'left,hide,right,top,middle', that should be 'value' => 'left,hide,right,top,middle'.
Sorry about that. I have modified the entry to reflect this additional piece of info. Please let me know if that change does the trick, but I am fairly confident that it will.