Actions

Difference between revisions of "Developer Area/Sideblocks API"

From Mahara Wiki

< Developer Area
 
(9 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
Blocks and Sideblocks are not the same thing in Mahara.
 
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.
+
'''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 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.
+
'''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. This includes your user profile info that you see when logged in, and the login form that you see when logged out.
+
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 ===
 
=== 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 the array a sub-array with four items:
+
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
 
* name: The name of the sideblock. This '''must''' match the name of a template file, templates/sideblocks/{name}.tpl
Line 19: Line 19:
  
 
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.
 
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 ===
 
=== Anatomy of a sideblock ===
Line 24: Line 26:
 
So, a sideblock really only needs two things:
 
So, a sideblock really only needs two things:
  
# A template file, under templates/sideblocks/{name}.tpl
+
# A template file, under templates/sideblocks/{name}.tpl . This can access the "data" that you pass in via the smarty variable "sbdata".
# It must be added to $SIDEBLOCKS in smarty(), in one of two ways:
+
# It must be added to $sideblocks in smarty(), in one of these ways:
 
## A patch to the smarty() function, which adds the sideblock under certain conditions
 
## A patch to the smarty() function, which adds the sideblock under certain conditions
 
## Adding an invocation of the sideblock via the "extraconfig" param when invoking the smarty() function on one or more pages
 
## Adding an invocation of the sideblock via the "extraconfig" param when invoking the smarty() function on one or more pages
 +
## Via the local_sideblocks_update() method in local/lib.php
  
 
=== Third-party sideblocks ===
 
=== 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.
 
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.

Latest revision as of 12:32, 13 October 2014

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.