Using Mahara/Writing Plugins/Room Badge

Setting up a Development Environment
Before you start writing a plugin, you must have a development environment running:
 * Development Environment Setup

Plugin Overview
Here, we show how to create a very simple blocktype that will add a class signature to a Mahara page. The tutorial assumes some knowledge of web development and php programming but is okay for persons with no prior experience developing for Mahara (I started exploring Mahara a week ago).

In this tutorial, we will produce a plugin that let the user add a classroom badge on its page:



The user can change the background color and the rooom number.

The easiest way to create a new blocktype is to copy an existing one and adapt it. Go for an existing blocktype that is as similar as possible in functionality to the plugin you want to write, copy and paste the base blocktype folder and start adapting it.

Here, we will start with a copy of the creativecommons blocktype. Once copied, rename the new new folder to something appropriate. Here we will use roombadge as name.

At this stage, you should have a folder: mahara/blocktype/roombadge

First thing to do is run some renaming, from creativecommons to roombadge.

Let's rename the files first.
 * 1) Get rid of the folder roombadge/js. Our plugin doesn't require any javascript.
 * 2) Rename the file  roombadge/lang/en.utf8/help/blocktype.creativecommons to roombadge/lang/en.utf8/help/blocktype.roombadge.
 * 3) Delete the folder  roombadge/lang/en.utf8/help.
 * 4) Delete the folder  roombadge/theme/raw/static.

It's best to change thumb.png early on, possibly with a temporary replacement one. I have provided a thumb template that you can download and edit:

Let's now replace some textual content. In mahara/blocktypes/roombadge, open <tt>lib.php</tt> in a text or code editor replace it with: The camel case name for the plugin must match the lowercase name of the folder (RoomBadge and blocktype/roombadge). --

Code Comments
Edit the comments at the top of the page.

Replace it with:

As you have finished editing the comments, copy and paste them to other php code files.
 * 1) <tt>roombadge/lang/en.utf8/blocktype.roombadge.php</tt>
 * 2) <tt>roombadge/version.php</tt>

Plugin Constants
Okay, let's start modifying the code now. This is not as bad as it sound. Let's go line by line and decide whether we are likely to need that bit of code or not.

It may be a good idea to limit the color options. Let's provide four default colours. These values will in fact be saved in the Mahara database. The shorter the name, the better. Here a single letter is enough to differentiate the four colours.

Now, the function single_only. A value of true means that there should be no more than one such block per page. That makes sense for our room badge. Let's keep it like that.

---

Plugin Metadata
<tt>get_title</tt> and <tt>get_description</tt> return the title and description of the plugin, as displayed in the plugin menu, at the top of the page, when in edit mode. We need to change creativecommons to roombadge

As we are at it, let's make a general search and replace on that page. Search for <tt>'blocktype.creativecommons'</tt> and replace all with <tt>blocktype.roombadge</tt>.

But we also need to make sure that the value being returned are appropriate. Let's open the file <tt>roombadge/lang/en.utf8/blocktype.roombadge.php</tt> and let's look for the title and description tags:

We need to edit these string tags.

---

Plugin Category
<tt>get_categories</tt> defines the tab under which the plugin appears, in the plugin menu at the top of the page, in view (page in Mahara1.4) edit mode.

---

HTML render
<tt>render_instance</tt> defines who the block will appear to the user in normal view mode.

Let's change the rendering to the one of a badge. It would be better to keep the CSS separate, but here that's not too much of an issue as the badge can be added once only on the page. Let's keep it this way for the sake of simplicity.

---

Form Instance
Now let's take care of the form that is displayed to the user when the plugin is dragged and dropped into the view, in edit mode. Let's have a look at what the code that was in use for creative commons, limiting it the bare skeleton.
 * <tt>has_instance_config</tt> defines whether the user has the option to customize the plugin content by editing a form. Keep it to true. We want the user to be able to edit the color and the label.
 * <tt>instance_config_form</tt> defines the look and feel of the form that will be shown to the user.
 * <tt> instance_config_save</tt> defines how the data that have been specified in the form get saved in the Mahara database. $values holds the data provided by the user when editing the form.

becomes:

We need to add any string used in the config form the language file <tt>roombadge/lang/en.utf8/help/blocktype.roombadge</tt>

---

Testing the plugin
Navigate with your browser to the Mahara website, in your development sandbox http://localhost/mahara/

If there is any error, correct it. You should have some message telling you about the file and the line number at the origin of the error.

For instance, I inserted this error Parse error: syntax error, unexpected T_STRING in /Applications/XAMPP/xamppfiles/htdocs/mahara/blocktype/roombadge/lib.php on line 28

If all is well, put your mouse over the little arrow next the Mahara logo, at the top of the page. Select <tt>Site Administration</tt>. You should end up at http://localhost/mahara/admin/ Click on the tab <tt>Extensions</tt> The name of your login should appear, with install next to it. roombadge (Install) Click install. All should go well. Navigate back to one of your user views, using the tab <tt>Return to Site</tt>. Select a view: http://localhost/mahara/view/view.php?id=1 Click <tt>Edit Content</tt> at the top right of the page. Select the tab General as we opted for category 'general' in our lib file. Select <tt>Classroom Badge</tt> and drop it into your view. Click on the form icon to configure.

---

Readme and version files
Don't forget to change the file <tt>roombadge/README.txt</tt>. I went for this

Room Badge Blocktype for Mahara Copyright (C) 2011 Widged Author: Marielle Lange This block allows Mahara users to add a room badge on their views.

Double check the file <tt>roombadge/version.php</tt> and edit if necessary.

$config = new StdClass; $config->version = 2011051200; $config->release = '1.0.0';

Result
Direct link to the files content on github
 * lib.php
 * lang/en.utf8/blocktype.roombadge.php
 * version.php
 * README.txt