print page  |  view normal version 

Section 3.4 - Working with the sidebars

Enano's sidebar was designed around being extremely flexible; it could even be said that the sidebar is the most versatile tool in Enano.

Concepts

Currently Enano allows for two sidebars, which are simply labeled left and right. It's entirely possible to develop themes that only use one sidebar for guests, and have the other one shown in addition to or in replacement of the first if the user's logged in. You could create two totally different-looking sidebars (so long as they use the same HTML - use CSS to spice it up), or combine them into a single bar on one side, which is done in St. Patty. The possibilities are literally endless!

Each sidebar is organized into blocks, with each block having a title (which can have variables in it, see below), and content. The content is usually stored in the database and parsed in one of four ways: with the normal Wiki formatting processor, with a separate engine designed specifically for sidebar use, as raw HTML, and as PHP. There can also be blocks that consist only of a link to a plug-in, which uses the Enano API to insert custom code. The advantages and disadvantages of each are outlined below.

Types of blocks

Wiki formatted

This type uses the same parser that is used for pages. You're best off using it if you need a block with information rather than a list of links and you're not familiar with HTML. Themes that indent paragraphs, including Oxygen, can make wiki-formatted blocks look odd.

Template-formatted

This type of block is actually rather mis-named - it doesn't use the same parser as is used on template files. Rather, it uses a parser similar to the one used for wiki formatting, with some unnecessary portions (like paragraphing) removed and additions to support template variables and logic. The template formatting parser is also used on block titles, so you can use variables and conditions in titles.

You can use basic logic and variables in these blocks. Variables are in the format of $VAR_NAME$. Why two sigils? When there are sigils at the start and end of a variable, it can be used inside of other strings easily. Logic (checking for certain conditions) works as follows:

  • All logic will be in the format of {if condition [&& condition...]}
  • You can use the following boolean operators:
    • && or AND
    • || or OR
  • You can put an exclamation point ("!") in front of a condition to negate it. So text wrapped with the following would be shown only to guests: {if !user_logged_in}
  • You can use parentheses to force that certain parts of your expression be processed first: {if user_logged_in && ( auth_admin || enable_uploads )}
  • Close a conditional block with {/if}. All blocks must be closed.
  • You can use {else} to indicate what should be shown if the condition isn't true: {if user_logged_in} Hello, $USERNAME$! {else} Welcome, guest! {/if}

Make sure that your parentheses are matched, meaning that for each left, there should be a matching right. Syntax errors will result in messy parser errors. HTML can be used nearly unrestricted in template-formatted blocks. You can also use internal links and embedded images, with several exceptions:

  • Internal links will be set to follow the pattern set by the variable "sidebar_button" in the current theme's elements.tpl.
  • Images CANNOT take any parameters. They are treated as if they have the "raw" flag.

Raw HTML

This will cause the block to simply be printed out - no processing whatsoever. Recommended if you're good with HTML.

Embedded PHP

This allows you to use real PHP code in your block. This option is recommended for highly advanced users only and is provided only for those who have enough experience to understand the potential repercussions if the code you embed is unsafe. You are given a stern warning when you select the PHP option. Don't ignore it. Also, make sure that you import any Enano globals you need and avoid using PHP's output buffering functions.

Using code from a plugin

This will ask a plugin to generate its own HTML at run-time and output that HTML into the block. You can still use a custom title.

Organizing blocks

Each block has four buttons next to it: Enable/disable, edit, delete, and move. Enable/disable will allow you to turn off a block while you're editing it. Edit allows you to change the contents of the block. Delete will permanently remove the block from your database, and move will toggle which sidebar the block is shown on. You can drag-and-drop to rearrange blocks.

Known limitations

  • Enano 1.0.x requires you to click the "Move" button to toggle which sidebar a block shows under. In Enano 1.2, this is resolved: blocks can be dragged and dropped between sidebars.
Previous Section 3.4 - Working with the sidebars Next
Building a fancy portal Up one level Categorizing pages
© 2007 Contributors. All content is under the GNU Free Documentation License.
Powered by Enano | Valid XHTML 1.1 | Valid CSS | Time: 0.07s