使用 Mahara/寫作外掛/房間徽章

設定開發環境

在開始編寫外掛之前，您必須有一個正在執行的開發環境

• 開發環境設定

外掛概述

在這裡，我們將展示如何建立一個非常簡單的 blocktype，它將為 Mahara 頁面新增一個類簽名。本教程假定您對 web 開發和 php 程式設計有一定的瞭解，但即使是從未接觸過 Mahara 開發的人也可以學習（我在一週前開始探索 Mahara）。

在本教程中，我們將建立一個外掛，允許使用者在其頁面上新增一個教室徽章

使用者可以更改背景顏色和房間號。

建立新 blocktype 的最簡單方法是複製現有 blocktype 並進行調整。選擇一個功能與您要編寫的外掛儘可能相似的現有 blocktype，複製貼上基本 blocktype 資料夾，然後開始對其進行調整。

在這裡，我們將從一個名為creativecommons的 blocktype 的副本開始。複製後，將新資料夾重新命名為更合適的名稱。在這裡我們將使用roombadge作為名稱。

在這個階段，您應該有一個名為

mahara/blocktype/roombadge

的第一件事是進行一些重新命名，從 creativecommons 重新命名為 roombadge。

讓我們先重新命名檔案。

1. 刪除資料夾roombadge/js。我們的外掛不需要任何 javascript。
2. 重新命名檔案roombadge/lang/en.utf8/help/blocktype.creativecommons為roombadge/lang/en.utf8/help/blocktype.roombadge.
3. 刪除資料夾roombadge/lang/en.utf8/help.
4. 刪除資料夾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 <francois@catalyst.net.nz>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
 * @copyright  (C) 2009 Catalyst IT Ltd
*/

將其替換為

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

完成註釋編輯後，將它們複製貼上到其他 php 程式碼檔案中。

1. roombadge/lang/en.utf8/blocktype.roombadge.php
2. 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:///mahara/

如果有任何錯誤，請更正。您應該看到一條訊息，告訴您錯誤的來原始檔和行號。

例如，我插入了這個錯誤

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

如果一切正常，將滑鼠懸停在頁面頂部 Mahara 徽標旁邊的小箭頭上。選擇網站管理。您應該會轉到

https:///mahara/admin/

點選選項卡擴充套件您的登入名稱應該會顯示出來，旁邊是安裝按鈕。

roombadge (Install)

單擊安裝。一切應該順利。使用選項卡導航回您的一個使用者檢視返回網站。選擇一個檢視

https:///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上檔案內容的直接連結

• lib.php
• lang/en.utf8/blocktype.roombadge.php
• version.php
• README.txt