Developer Area/Sideblocks API

Of Blocks and Sideblocks

Blocks and Sideblocks are not the same thing in Mahara.

Blocks are one of the basic Plugin types of Mahara, designed to be easily extensible by third parties. A Block is, basically, an element that a user can put into a Page.

Sideblocks are one of the basic design elements of Mahara itself. They're data that floats off to the side of the page (hence the name). As such, they're not really a plugin type, but more like a component of Mahara's templating system. Sideblocks are not easily extensible by third parties; most of them are hard-coded into htdocs/lib/mahara.php.

Some very important parts of Mahara are implemented as sideblocks. This includes your user profile info that you see when logged in, and the login form that you see when logged out.

How sideblocks work

In the function smarty() in htdocs/lib/web.php, there is an array, $SIDEBLOCKS. (Note that despite being in ALL CAPS, this is NOT a global variable!) There is a section of the code where it examines the state of the logged in user and various configuration settings, and from this it determines which sideblocks should be displayed on the page. For each of them, it inserts into $SIDEBLOCKS a sub-array with four items:

• name: The name of the sideblock. This must match the name of a template file, templates/sideblocks/{name}.tpl
• id (optional): If present, this will be the ID of the div surrounding the sideblock.
• weight: Determines what order the sideblocks are shown in. A lower weight makes the sideblock display higher up on the page. Weights can go negative; the user profile block has a weight of -20.
• data: An array of data that will be passed to the sideblock's template file. This is usually generated by a function specific to that sideblock.

Additional sideblocks are then added from $extraconfig['sideblocks'], which means they can be added by the Mahara page which is calling smarty(). Several Mahara pages make use of this, for instance many of the Content pages show the user's file upload quota in a sideblock.

The $SIDEBLOCKS array is then assigned to the SIDEBLOCKS smarty variable. The template "sidebar.tpl" then reads SIDEBLOCKS, and includes the appropriate sideblock template file for each entry, passing in the data for that entry as "sbdata".

Anatomy of a sideblock

So, a sideblock really only needs two things:

1. A template file, under templates/sideblocks/{name}.tpl
2. It must be added to $SIDEBLOCKS in smarty(), in one of two ways:
   1. A patch to the smarty() function, which adds the sideblock under certain conditions
   2. Adding an invocation of the sideblock via the "extraconfig" param when invoking the smarty() function on one or more pages

Third-party sideblocks

In theory we could add a third-party plugin type for sideblocks. If anyone is interested in that, please file a launchpad wishlist bug. The tricky thing would be providing a good system to determine what pages the sideblock should be displayed on. Perhaps part of the Sideblock Plugin type, would be a function that could be called for that Sideblock to determine whether it should be displayed.