Tutorial: Creating blocktype plugin for Mahara

I will show you, how to write a blocktype plugin for Mahara. The purpose of that plugin is, to add a Twitter Tweet button to any Mahara view. In this tutorial I will explain, what do you need to write a blocktype plugin for Mahara - what are the minimal required files, what is the folder structure, etc.

Let's begin with minimal set of needed files and folder structure. Let assume, we will call our plugin Tweety - the name of the plugin must be unique. So you'll need at least those files (placed in correct folders):

• /htdocs/blocktype/tweety/lib.php - the file that actually is your blocktype plugin. It contains all the logic for rendering content, etc.
• /htdocs/blocktype/tweety/thumb.png - the icon image, which will be shown at one of the categories (in which you placed your blocktype plugin). Think about the tabs on top, when creating/editing a Mahara view. All other icons/thumbs are 70×58 pixels, so I think yours should also be the same size.
• /htdocs/blocktype/tweety/version.php - the file, which contains the version of your blocktype plugin, usually in version and release format. E.g.: version = 2011051500 (YYYYMMDDNN), where Y is year, M is month, D is day and N is incrementing number, starting at 00; release = 1.0.0, for initial release.
• /htdocs/blocktype/tweety/lang/en.utf/blocktype.tweety.php - the file, which contains all the strings, used by your blocktype plugin in English language.
• /htdocs/blocktype/tweety/lang/xy.utf/blocktype.tweety.php - (optional) the file, which contains translated strings of xy language, where xy is an ISO 639-1 language code.

/htdocs/blocktype/tweety/thumb.png

An icon that will represent your blocktype plugin, so the users will know very quickly, what your blocktpye plugin is all about. Keep in mind, that it has to be 70×58 pixels. You can use the thumb from one of existing blocktypes as a start and change it... Example:

/htdocs/blocktype/tweety/version.php

<?php
/**
* Mahara: Electronic portfolio, weblog, resume builder and social networking
* Copyright (C) 2006-2009 Catalyst IT Ltd and others; see:
*                         http://wiki.mahara.org/Contributors
*
* This program is free software: you can redistribute it and/or modify
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program.  If not, see <http://www.gnu.org/licenses/>.
*
* @package    mahara
* @subpackage blocktype-tweety
* @author     Gregor Anzelj
* @copyright  (C) 2011 Gregor Anzelj, [email protected]
*
*/

defined('INTERNAL') || die();

$config = new StdClass;$config->version = 2011051500;
$string['description'] = 'Dodaj Twitter Tweet gumb'; ?>  The translation language file should contain at least title (the title of your blocktype plugin) and description (the description of your blocktype plugin) strings. You can also add @translaton in the above commented section... It is not necessary that the author and translator are the same person. /htdocs/blocktype/tweety/lib.php <?php /** * Mahara: Electronic portfolio, weblog, resume builder and social networking * Copyright (C) 2006-2009 Catalyst IT Ltd and others; see: * http://wiki.mahara.org/Contributors * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see <http://www.gnu.org/licenses/>. * * @package mahara * @subpackage blocktype-tweety * @author Gregor Anzelj * @license http://www.gnu.org/copyleft/gpl.html GNU GPL * @copyright (C) 2011 Gregor Anzelj, [email protected] * */ defined('INTERNAL') || die(); class PluginBlocktypeTweety extends SystemBlocktype { public static function single_only() { return true; } public static function get_title() { return get_string('title', 'blocktype.tweety'); } public static function get_description() { return get_string('description', 'blocktype.tweety'); } public static function get_categories() { return array('general'); } public static function render_instance(BlockInstance$instance, $editing=false) {$full_self_url = urlencode(get_full_script_path());
$result = '<a href="http://twitter.com/share?url=' .$full_self_url . '" class="twitter-share-button" data-count=none">Tweet</a>'


All you have to do after that point: you have to copy the basic code (obtained from Twitter Tweet button online generator form) and place $full_self_url to the right place (see the above code). Please note: This is a very basic example, which is meant to show you, how to write a basic blocktype plugin. For more complex example, which also includes instance_config_form so the user can set more options, please download and compare TwitterTweet blocktype plugin. function has_instance_config() This function can return true or false. If it returns true it means, that the blocktype plugin has an instance config form in which the user supplies additional data, parameters, etc. that will affect the blocktype appearance in Mahara view. If set to true than the function public static function instance_config_form($instance) must also be present. This function contains Pieform for rendering form in which the user will enter/select additional data, parameters, etc.

To understand how to use Pieforms and how Pieforms work, please see Pieforms documentation.

function default_copy_type()

This function returns what should be copied, when exporting this blocktype to LEAP2A.

Possible values are: full, shallow and nocopy.

Heinz Krettek 11 May 2011, 3:19 [Updated: 11 May 2011, 3:20]

Hi Gregor,

thanks for this cool tutorial I hope to find the time to translate it for the community. (maharacopy the view?!)

Cheers

Heinz

Gregor Anželj 11 May 2011, 3:36

Added the option to copy the view in Mahara. Were you asking me to do that Heinz?

Kristina Hoeppner 11 May 2011, 4:16

Hello Gregor,

That's a great tutorial. Now I only need to know how to code in order to follow it.

Sorry that the wiki doesn't work at the moment for you to publish it there.

Cheers

Kristina

Iñaki Arenaza 11 May 2011, 12:16

Hi Gregor,

there's a small typo in the name of the blocktype code file . It should be .../lib.php (not .../lib.png)

In addition to that, instead of constructing $full_self_url using$_SERVER[] values, you should probably use get_full_script_path(). It takes into account all the special cases for different webservers, php configurations, etc. Something like:

\$full_self_url = urlencode(get_full_script_path());


should do it.

Gregor Anželj 12 May 2011, 1:17

Thanks for pointing that out. Didn't know about get_full_script_path().

Kevin Rickis 13 June 2011, 6:04

Hi Gregor,

thank you for this very useful tutorial.

I have also spotted what I think is a little typo.

Should :

/htdocs/blocktype/tweety/lang/en.utf/blocktype.tweety.php

/htdocs/blocktype/tweety/lang/xy.utf/blocktype.tweety.php

Be :

/htdocs/blocktype/tweety/lang/en.utf8/blocktype.tweety.php

/htdocs/blocktype/tweety/lang/xy.utf8/blocktype.tweety.php

Kevin

Gregor Anželj 14 June 2011, 1:23

Yes. Thank you for that...