使用 Mahara/写作插件/房间徽章

设置开发环境

在开始编写插件之前，您必须有一个正在运行的开发环境

开发环境设置

插件概述

在这里，我们将展示如何创建一个非常简单的 blocktype，它将为 Mahara 页面添加一个类签名。本教程假定您对 web 开发和 php 编程有一定的了解，但即使是从未接触过 Mahara 开发的人也可以学习（我在一周前开始探索 Mahara）。

在本教程中，我们将创建一个插件，允许用户在其页面上添加一个教室徽章

用户可以更改背景颜色和房间号。

创建新 blocktype 的最简单方法是复制现有 blocktype 并进行调整。选择一个功能与您要编写的插件尽可能相似的现有 blocktype，复制粘贴基本 blocktype 文件夹，然后开始对其进行调整。

在这里，我们将从一个名为creativecommons的 blocktype 的副本开始。复制后，将新文件夹重命名为更合适的名称。在这里我们将使用roombadge作为名称。

在这个阶段，您应该有一个名为

mahara/blocktype/roombadge

的第一件事是进行一些重命名，从 creativecommons 重命名为 roombadge。

让我们先重命名文件。

删除文件夹roombadge/js。我们的插件不需要任何 javascript。
重命名文件roombadge/lang/en.utf8/help/blocktype.creativecommons为roombadge/lang/en.utf8/help/blocktype.roombadge.
删除文件夹roombadge/lang/en.utf8/help.
删除文件夹roombadge/theme/raw/static.

最好尽早更改 thumb.png，最好用一个临时的替换文件。我已经提供了一个可以下载和编辑的 thumb 模板：

现在让我们替换一些文本内容。在mahara/blocktypes/roombadge中，打开lib.php在一个文本或代码编辑器中

class PluginBlocktypeCreativecommons extends SystemBlocktype {

将其替换为

class PluginBlocktypeRoomBadge extends SystemBlocktype {

插件的驼峰命名法必须与文件夹的小写名称匹配（RoomBadge 和 blocktype/roombadge）。

代码注释

编辑页面顶部的注释。

/*
 * @package    mahara
 * @subpackage blocktype-creativecommons
 * @author     Francois Marier <[email protected]>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
 * @copyright  (C) 2009 Catalyst IT Ltd
*/

将其替换为

/*
 * @package    mahara
 * @subpackage blocktype-roombadge
 * @author    My name <[email protected]>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
 * @copyright  (C) 2011 Myself
*/

完成注释编辑后，将它们复制粘贴到其他 php 代码文件中。

roombadge/lang/en.utf8/blocktype.roombadge.php
roombadge/version.php

插件常量

好的，现在让我们开始修改代码。这并不像听起来那么糟糕。让我们逐行检查，看看我们是否需要这些代码。

    // Standard Creative Commons naming scheme
    const noncommercial = 'nc';
    const noderivatives = 'nd';
    const sharealike    = 'sa';

限制颜色选项可能是一个好主意。让我们提供四种默认颜色。这些值实际上将保存在 Mahara 数据库中。名称越短越好。这里一个字母就足以区分四种颜色。

    // Standard Color scheme
    const orange    = '#D74300';
    const red       = '#9E0013';
    const blue      = '#006CC9';
    const green     = '#0F9400';

现在，single_only 函数。值为 true 表示每个页面上此类 block 的数量不超过一个。这对我们的房间徽章来说是有意义的。让我们保持原样。

    public static function single_only() {
        return true;
    }

插件元数据

get_title和get_description返回插件的标题和描述，如插件菜单中显示的那样，在页面的顶部，在编辑模式下。

    public static function get_title() {
        return get_string('title', 'blocktype.creativecommons');
    }
    public static function get_description() {
        return get_string('description', 'blocktype.creativecommons');
    }

我们需要将 creativecommons 更改为 roombadge

    public static function get_title() {
        return get_string('title', 'blocktype.roombadge');
    }
    public static function get_description() {
        return get_string('description', 'blocktype.roombadge');
    }

既然我们已经做到了这一点，让我们在这个页面上进行一个通用的搜索和替换。搜索'blocktype.creativecommons'并将所有内容替换为blocktype.roombadge.

但我们还需要确保返回的值是合适的。让我们打开文件roombadge/lang/en.utf8/blocktype.roombadge.php让我们查找标题和描述标签

$string['title'] = 'Creative Commons License';
$string['description'] = 'Attach a Creative Commons license to your view';
$string['blockcontent'] = 'Block Content';

$string['alttext'] = 'Creative Commons License';
$string['licensestatement'] = "This work is licensed under a <a rel=\"license\" href=\"%s\">Creative Commons %s 3.0 Unported License</a>.";
$string['sealalttext'] = 'This license is acceptable for Free Cultural Works.';

$string['config:noncommercial'] = 'Allow commercial uses of your work?';
$string['config:noderivatives'] = 'Allow modifications of your work?';
$string['config:sharealike'] = 'Yes, as long as others share alike';

$string['by'] = 'Attribution';
$string['by-sa'] = 'Attribution-Share Alike';
$string['by-nd'] = 'Attribution-No Derivative Works';
$string['by-nc'] = 'Attribution-Noncommercial';
$string['by-nc-sa'] = 'Attribution-Noncommercial-Share Alike';
$string['by-nc-nd'] = 'Attribution-Noncommercial-No Derivative Works';

我们需要编辑这些字符串标签。

$string['title'] = 'Classroom Badge';
$string['description'] = 'Attach a Room badge to your view';
$string['blockcontent'] = 'Block Content';

$string['alttext'] = 'Classroom Badge';
$string['defaultlabel'] = 'Room 1';

$string['R'] = 'red';
$string['O'] = 'orange';
$string['B'] = 'blue';
$string['G'] = 'green';

插件类别

get_categories定义插件在插件菜单中出现的选项卡，该菜单位于页面的顶部，在视图（Mahara1.4 中的页面）编辑模式下。

    public static function get_categories() {
        return array('general');
    }

HTML 渲染

render_instance定义在普通视图模式下 block 将如何显示给用户。

    public static function render_instance(BlockInstance $instance, $editing=false) {
        global $THEME;
        $configdata = $instance->get('configdata');
        if (!isset($configdata['license'])) {
            return '';
        }

        $licensetype = $configdata['license'];
        $licenseurl = "http://creativecommons.org/licenses/$licensetype/3.0/";
        $licensename = get_string($licensetype, 'blocktype.roombadge');

        $html = '<div class="licensedesc"><a class="fl" rel="license" href="http://creativecommons.org/licenses/'.$licensetype.'/3.0/"><img alt="'.
            get_string('alttext', 'blocktype.roombadge').
            '" style="border-width:0" src="'.
            $THEME->get_url('images/' . $licensetype . '-3_0.png', false, 'blocktype/creativecommons') . '" /></a>';
        $html .= '<div>';
        $html .= get_string('licensestatement', 'blocktype.roombadge', $licenseurl, $licensename);
        $html .= '</div></div>';
        return $html;
    }

让我们将渲染更改为徽章的渲染。最好将 CSS 分开，但这里这不是什么大问题，因为徽章只能在页面上添加一次。为了简单起见，让我们保持这种方式。

    public static function render_instance(BlockInstance $instance, $editing=false) {
        $configdata = $instance->get('configdata');

        // Display the badge only if both color and label are defined. The tags color and label are defined in instance_config_form
        if (!isset($configdata['color']) || !isset($configdata['label'])) {
            return '';
        }
        
        $badgecolor = $configdata['color'];
        $badgelabel = $configdata['label'];

        $html = '<div style=";border:1px solid '.$badgecolor.';width:85px;">';
        $html .= '	<div style="background:#363636;border:1px solid #FFFFFF;padding:1px 2px;font-size:10px;font-family:Verdana,sans-serif;float:left;color:#FFFFFF;">';
        $html .= '»';
        $html .= '	</div>';
        $html .= '	<div style="background:'.$badgecolor.';border:1px solid #FFFFFF;padding:1px 6px;font-size:10px;font-family:Verdana,sans-serif;color:#FFFFFF;">';
        $html .= '&nbsp;&nbsp;'.$badgelabel;
        $html .= '	</div>';
        $html .= '</div>';
        return $html;
    }

表单实例

现在让我们处理在编辑模式下将插件拖放到视图中时显示给用户的表单。让我们看一下 creativecommons 使用的代码，将其限制为基本的骨架。

has_instance_config定义用户是否可以选择通过编辑表单来自定义插件内容。保持为 true。我们希望用户能够编辑颜色和标签。
instance_config_form定义将显示给用户的表单的外观和风格。
instance_config_save定义从表单中指定的数据如何保存到 Mahara 数据库中。$values 包含用户编辑表单时提供的数据。

    public static function has_instance_config() {
        return true;
    }

    public static function instance_config_save($values) {
        $configdata = array();
        return $configdata;
    }

    public static function instance_config_form($instance) {
        // provides a shortcut to the folder <tt>roombadge/theme/raw</tt>
        global $THEME;

       // read the config data that have been saved by the user and parse them if necessary. 
       $configdata = $instance->get('configdata');

       // return a configuration file for the form. 
        return array();
    }

变为

     public static function has_instance_config() {
        return true;
    }

    public static function instance_config_save($values) {
       switch($values['colorIdx'])
       {
          case 0:
            $color = self::orange;
            break;
         case 1:
            $color = self::red;
            break;
         case 2:
           $color = self::blue;
            break;
         case 3:
           $color = self::green;
            break;
       }       
       
        $configdata = array('title' => get_string('title', 'blocktype.roombadge'),
                            'label' => $values['title'],
                            'color' => $color,
        );
        return $configdata;
    }

    public static function instance_config_form($instance) {
        global $THEME;
        $configdata = $instance->get('configdata');

        // defaults to use
        $color   = 'O';
        $label   = get_string('defaultlabel', 'blocktype.roombadge');

        // if the user previously speficied some value, use the user values instead of the defaults
        if (isset($configdata['label'])) {
            $label = $configdata['label'];
        }

        if (isset($configdata['color'])) {
            $color = $configdata['color'];
        }
        
        // Convert the one letter color name into the index value of the radio group. 
        switch($color)
        {
           case self::orange:
             $colorIdx = 0;
             break;
          case self::red:
             $colorIdx = 1;
             break;
          case self::blue:
             $colorIdx = 2;
             break;
          case self::green:
             $colorIdx = 3;
             break;
        }

        

        return array(
            'title' => array(
                'type' => 'text',
                'value' => $label,
            ),

            'colorIdx' => array(
                'type' => 'radio',
                'title' => get_string('config:selectcolor', 'blocktype.roombadge'),
                'options' => array(
                                   0 => get_string('O', 'blocktype.roombadge'),
                                   1 => get_string('R', 'blocktype.roombadge'),
                                   2 => get_string('B', 'blocktype.roombadge'),
                                   3 => get_string('G', 'blocktype.roombadge')
                                   ),
                'defaultvalue' => $colorIdx,
                'separator' => '<br>',
                'help' => true,
                'rules' => array('required'    => true),
            ),
        );
    }

我们需要将配置表单中使用的任何字符串添加到语言文件中roombadge/lang/en.utf8/help/blocktype.roombadge

$string['config:selectcolor'] = 'Choose a badge color';

测试插件

使用浏览器导航到您的开发沙箱中的 Mahara 网站

https://127.0.0.1/mahara/

如果有任何错误，请更正。您应该看到一条消息，告诉您错误的来源文件和行号。

例如，我插入了这个错误

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

如果一切正常，将鼠标悬停在页面顶部 Mahara 徽标旁边的小箭头上。选择网站管理。您应该会转到

https://127.0.0.1/mahara/admin/

点击选项卡扩展您的登录名称应该会显示出来，旁边是安装按钮。

roombadge (Install)

单击安装。一切应该顺利。使用选项卡导航回您的一个用户视图返回网站。选择一个视图

https://127.0.0.1/mahara/view/view.php?id=1

单击编辑内容在页面的右上角。选择“常规”选项卡，因为我们在 lib 文件中选择了“常规”类别。选择教室徽章并将它拖放到您的视图中。单击表单图标进行配置。

自述文件和版本文件

不要忘记更改文件roombadge/README.txt。我选择了这个

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.

仔细检查文件roombadge/version.php并在必要时编辑。

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

结果

指向github上文件内容的直接链接