Developer Area/Sideblocks API

Of Blocks and Sideblocks

Blocks and Sideblocks are not the same thing in Mahara.

Blocks are the items that users can drag onto a View (aka a user-created portfolio Page). There is a Block Plugin type which allows third parties to easily develop new Block types and users to install them.

Sideblocks are a component of Mahara's page layout (i.e. system pages, not user-created portfolio Pages). They're little bits of HTML that get displayed in a column along the side of a page. 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, including 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. (Prior to Mahara 1.10 this was $SIDEBLOCKS, but despite being in ALL CAPS, it is NOT a global variable!) One of the things smarty() does, is a series of if-else statements which examine the state of the user and the page being viewed, 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 . This can access the "data" that you pass in via the smarty variable "sbdata".
2. It must be added to $sideblocks in smarty(), in one of these 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
   3. Via the local_sideblocks_update() method in local/lib.php

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.

As of Mahara 1.10, there is a /local hook to add custom sideblocks to core pages. Add a function called local_sideblocks_update() in local/lib.php, and the sideblocks array will be sent to it by reference on each pageload. There you can, in theory, perform checks against various global variables to determine which custom sideblocks to show on that page, and add them to the sideblocks array.