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
 * 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();

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

?>

Don't forget to change @subpackage, @author and @copyright in commented part on top. You also have to change version and release numbers (marked bold!)

/htdocs/blocktype/tweety/lang/en.utf8/blocktype.tweety.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();

$string['title'] = 'Twitter Tweet';
$string['description'] = 'Add Twitter Tweet button';

?>

The language file should contain at least title (the title of your blocktype plugin) and description (the description of your blocktype plugin) strings.

/htdocs/blocktype/tweety/lang/sl.utf8/blocktype.tweety.php - optional, translation to Slovenian language

<?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
 * @translator Gregor Anzelj
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
 * @copyright  (C) 2011 Gregor Anzelj, [email protected]
 *
 */

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

$string['title'] = 'Twitter Tweet';
$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>'
                . '<script type="text/javascript" src="http://platform.twitter.com/widgets.js"></script>';
        return $result;
    }

    public static function has_instance_config() {
        return false;
    }

    public static function default_copy_type() {
        return 'full';
    }

}

?>

Let's go over the functions in the PluginBlocktypeTweety class:

function single_only()

This function can return true or false. If it returns true it means, that the user can use only one instance of this blocktype on particular Mahara view.

function get_title()

This function returns the blocktype plugin title, as defined in blocktype.tweety.php language file. It returns the blocktype title in Mahara site defined language or in English, if the translation doesn't exists.

In our example this function would return 'Twitter Tweet', assuming that Mahara site defined language is English.

function get_description()

This function returns the blocktype plugin description, as defined in blocktype.tweety.php language file. It returns the blocktype description in Mahara site defined language or in English, if the translation doesn't exists.

In our example this function would return 'Add Twitter Tweet button', assuming that Mahara site defined language is English.

function get_categories()

This function returns the category (tab in Mahara view editing mode) in which the blocktype plugin is shown.

Possible values are: blog, feeds, fileimagevideo, general, internal and resume. These categories are defined in Mahara database, in blocktype_category table.

function render_instance(BlockInstance $instance, $editing=false)

This is the most important function, because it renders the content of the blocktype.

In our example, we wish to render Twitter Tweet button. There is a Twitter Tweet button online generator form, which can help you generate the appropriate Twitter Tweet button code. The basic code looks like this:

<a href="http://twitter.com/share?url=http://mahara.org%2fview%2fview.php%3fid%3d35645" class="twitter-share-button" data-count="none">Tweet</a>
<script type="text/javascript" src="http://platform.twitter.com/widgets.js"></script>

If we look at the code of this function, we see, that we need to provide/encode the URL of current Mahara view (web page) with all the arguments! This URL must be URL-encoded. This is achieved in the first line of code in this function:

$full_self_url = urlencode(get_full_script_path());

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.