ch04插件參數——Joomla插件開發

使用參數

Joomla在很多地方可以設置很多參數。每個擴展，都可以添加自己的參數或選項。
參數可以設置基本參數，比如，如果一個插件自動糾錯，應該添加一些參數，讓管理員設置糾錯如何執行。要不要自動把首字母大寫？要不要刪除段首的空格？通過添加參數可以做到這些。

在XML中定義參數

在XML配置文件中，參數通過<config>標籤來添加。爲插件添加參數和爲組件、模塊一樣。
下面的例子顯示一個字段集，命名爲basic，一個輸入字段，命名爲test。這個字段允許管理員保存一個值，一遍以後再PHP代碼中使用。

    <config>
        <fields>
            <fieldset name="basic">
                <field 
                    name="test" 
                    type="text" 
                    defalut=''Hello World''
                    label="PLG_CONTENT_CH04TEST01_FIELD_LABEL_LABEL" 
                    description="PLG_CONTENT_CH04TEST01_FIELD_LABEL_DESC"
                />

當使用Plugin Manager時，它會讀取這個XML文件，自動轉換爲HTML，顯示在編輯區域。
上面的例子是一個字段集和一個輸入框。Joomla允許很多的字段集和表格字段。甚至可以自定義字段。比如，可以創建一個自定義的下拉框。
<fieldset name="basic">字符集沒有標籤。Joomla自動爲basic和advanced添加標籤。也可以通過lable參數自定義標籤。如果沒有lable值，將會自動填充爲COM_PLUGINS_CUSTOMX_FIELDSET_LABEL。這個語言字符串在com_plugin中定義了。

參數存在哪？如何存儲的？
當使用Plugin Manager存儲參數時，參數值存儲在數據表#__extensions中的params中，以Json的格式存儲。當從數據庫中讀取後，JSON數據解碼爲JRegistry對象，並綁定到插件對象上。這些是自動完成的。

更多字段類型

最通用的四種：text, textarea, list, radio。還有些複雜的，比如calendar,combo, color,email, password。
例子，

                <field
                    name="align"
                    type="list"
                    default="left"
                    label="PLG_CONTENT_CH04TEST01_FIELD_ALIGN_LABEL"
                    description="PLG_CONTENT_CH04TEST01_FIELD_ALIGN_DESC"
                >
                    <option value="left">PLG_CONTENT_CH04TEST01_FIELD_ALIGN_OPTION_LEFT</option> 
                    <option value="right">PLG_CONTENT_CH04TEST01_FIELD_ALIGN_OPTION_RIGHT</option> 
                    <option value="center">PLG_CONTENT_CH04TEST01_FIELD_ALIGN_OPTION_CENTER</option> 
                </field> 

下拉列表框通過<option>標籤，來顯示選項。

在php文件中使用參數

在插件的php文件中，使用$this->params這個對象，這是一個JRegistry，包含一個get()方法，參數名作爲第一個參數，第二個參數是如果讀取爲空的時候的默認值。

public function onContentBeforeDisplay(
$context, &$row, &$params, $page = 0
)
{
$test = $this->params->get(′test′, ′Hello World′);
$row->title = $row->title . ′ [′ . $test . ′]′;
$row->text = $row->text . ′<p>[′ . $test . ′]</p>′;
}

$params 和 $this->params的區別：
onContentBeforeDisplay()有四個參數，第三個是$params，也是一個JRegistry對象。區別是， $this->params包含本插件參數，$params 包含的是內容類型參數。比如，文件插件的參數就是Article Manager中的參數。
安全問題：
如果是調用個數值，可以做下強制轉換

$integer = (int) $this->params->get(′integer′);

如果用的下拉列表，可以看看是不是在選項中

$value = $this->params->get(′color′);
if (in_array($value, array(′yellow′, ′red′, ′blue′)) == FALSE)
{
$value = ′yellow′;
}

一般情況下，Plugin Manager需要輸入一個值，也有變通的方法輸入多個值，用逗號把值分開。比如輸入一組顏色

green,yellow, #ffcc00, #000,

然後再PHP中用explode轉換爲一個數組

$list = $this->params->get(′list_from_textarea′);
$list = explode(′,′, $list);

但是，用戶的輸入一定要過濾，有可能有空格和回車

foreach ($list as $index => $value)
{
$value = trim($value);
if (empty($value))
{
unset($list[$index]);
continue;
}
$list[$index] = $value;
}

可以通過將multiple屬性設置爲true來建立多種選擇的下拉框

定義新的字段類型

Joomla的參數都是基於JForm庫，包含一組類，提供一種面向對象的方法來建立和驗證表單。通過這個庫可以方便的添加HTML表單而不用擔心其顯示樣式。JForm庫會自動渲染XML代碼成Joomla風格的HTML，並且建議表單驗證（基於驗證規則）。

在Plugin Mananger中，不必操心渲染和驗證部分。唯一需要做的是添加XML代碼。

除了現有的字段類型，還可以自定義字段，基於JForm類，然後添加到表單中。比如，要添加一個下拉框，選項是自定義的，而不是靜態的。

XML選項
假設要建立一個新的字段，加做testselect。先需要建議一個相應的類JFormFieldTestselect，放在插件的子目錄field中。
在XML中，通過type屬性來使用新類型<feld type=″testselect″ ... />

    <config>
        <fields name="params">
            <fieldset name="basic" addfieldpath="plugins/content/ch04test02/fields">

其中addfeldpath變量保證JFrom庫能夠搜索到field目錄。
在自定義testselect中，<option>標籤不用寫。
在plugins/content/ch04test02/felds子目錄中，建議一個testselect.php文件，

<?php
defned(′_JEXEC′) or die();
jimport(′joomla.form.formfeld′);
class JFormFieldTestselect extends JFormField
{
protected $type = ′Testselect′;
protected function getInput()
{
       return ′′;
}
}

其中jimport()函數用來加載JFormField類。較新的Joomla版本中，這個不必須了。
然後新建一個子類JFormFieldTestselect，其中$type變量是新字段的名稱。
方法getInput()返回時間的HTML代碼。

$options = array();
		$options[] = JHTML::_('select.option', 'sample01', JText::_('JFORM_FIELDTYPE_TESTSELECT1_SAMPLE01'), 'value', 'text');
		$options[] = JHTML::_('select.option', 'sample02', JText::_('JFORM_FIELDTYPE_TESTSELECT1_SAMPLE02'), 'value', 'text');

		return JHTML::_('select.genericlist', $options, $this->name, 'class="inputbox"', 'value', 'text', $this->value, $this->name);

可以直接用HTML代碼。最好使用JHTML函數生成。變量$this->name 和$this->value用來爲表格元素增加正確的屬性。

從數據庫中獲取數據
出來使用靜態列表，還可以進一步的，通過數據庫查詢獲得新的數據。
JFactory::getDbo()方法可以獲取數據庫實例。爲了適應不同的數據庫，不要直接寫SQL語句，而是使用對象方法。

protected function getInput()
{
    $db = JFactory::getDbo();
    $query = $db->getQuery(true);
    $query->select($db->quoteName(array(′w.url′, ′w.title′)));
    $query->from($db->quoteName(′#__weblinks′, ′w′));
    $query->where($db->quoteName(′w.approved′).′ = 1′);
    $query->order($db->quoteName(′w.title′));
    $db->setQuery($query);
    $options = array();
    $rows = $db->loadObjectList();
if (!empty($rows))
{
    foreach ($rows as $row)
    {
      $options[] = JHtml::_(′select.option′, $row->url,  $row->title, ′value′, ′text′ );
    }
}
$attribs = ′class=″inputbox″′;
return JHtml::_(′select.genericlist′, $options,$this->name, $attribs, ′value′, ′text′,$this->value, $this->name);
}

這個例子從#__weblinks表中獲取數據，通過選擇標題來獲取URL
爲例能夠使第三方開發者也能使用你的自定義字段，需要能夠支持額外的XML參數。比如，你想方便的轉換單項選擇和多項選擇，

<input type=″testselect″ multiple=″1″ size=″10″ />

其中multiple默認是0，通過以下的方法，如果改爲1，就能多項選擇了。
通過$this->element[′multiple′]來調用XML中的設置。

$multiple = 0;
		$size = 3;
		$attribs = 'class="inputbox"';

		if (isset($this->element['multiple']))
		{
            $multiple= filter_var($this->element['multiple'], FILTER_VALIDATE_BOOLEAN); 
		}

		if (isset($this->element['size']))
		{
			$size = (int) $this->element['size'];
		}

		if ($size < 3)
		{
			$size = 3;
		}

下面就是加入到下拉框的屬性裏了。通過添加第四個變量到JHtml::_(′select.genericlist′)的調用中，這個參數可以添加額外的HTML屬性到select元素中。現在我們通過變量$attribs動態的創建這些屬性。這樣就可以通過改變XML變量來改變HTML元素了。

$attribs = ′class=″inputbox″′;
if ($multiple == true)
{
$attribs .= ′ multiple=″multiple″′;
}
if ($size > 0)
{
$attribs .= ′ size=″′ . $size . ′″′;
}
s we
add some arguments to the XML:
<input type=″testselect″ multiple=″1″ size=″10″ />
The multiple argument defaults to 0 (false), however by changing it to 1 (true) we
can enable the multiselect behavior which follows below.
The argument size does nothing by default. When multiple is true however, the
size argument is used to determine the size of the multiselect box. If the size is smaller
than 3, it will be ignored and the size will be set to 3. If the size is larger than or equal to 3,
the size will be equal to the amount of options available.
$multiple = 0;
$size = 3;
if (isset($this->element[′multiple′])
{
$multiple = (bool) $this->element[′multiple′];
}
if (isset($this->element[′size′]))
{
$size = (int) $this->element[′size′];
if ($size < 3) $size = 3;
}
Now that the variables are prepared, we can add them to the dropdown attributes. We
do this by adding a fourth argument to the JHtml::_(′select.genericlist′)
call, which allows us to add additional HTML attributes to the select element. We now
dynamically construct these attributes as a variable $attribs, in order for the HTML
attributes to change depending on the given XML arguments.
$attribs = ′class=″inputbox″′;
if ($multiple == true)
{
$attribs .= ′ multiple=″multiple″′;
}
if ($size > 0)
{
$attribs .= ′ size=″′ . $size . ′″′;
}
return JHtml::_(′select.genericlist′, $options,
$this->name, $attribs, ′value′, ′text′,
$this->value, $this->name;

在一個XML配置文件中使用多個文件路徑
在<fieldset>標籤中添加addfeldpath屬性是一種方式，來使JForm庫在搜尋字段類型時來查找這個目錄。因爲JForm類用來渲染整個表格，所以，這種引入在整個表格週期都能用。比如：

<feldset name=″basic″
addfeldpath=″plugins/content/ch04test01/felds″>
</feldset>
<feldset name=″advanced″>
<feld type=″testselect″ ... />
</feldset>

不能爲一個標籤指定多個addfeldpath，XML只添加第一個，第二個不會被添加

<feldset addfeldpath=″path1″ addfeldpath=″path2″ ...

爲了添加多個路徑，可以把一個添加到<felds>標籤，一個添加到<feldset>標籤，設置可以添加到實際需要它的<feld>標籤

<confg>
<felds addfeldpath=″path1″ ...
<feldset addfeldpath=″path2″ ...
<feld addfeldpath=″path3″ ...

當一個addfeldpath變量添加到JForm庫時，新路徑會被加入到path字符串的末尾。如果想要覆蓋一個Joomla核心中已經存在的字段類型，最好是在Joomla啓動過程中儘早添加，比如通過一個System Plugin在onAfterInitalise中添加。

JFormHelper::addFieldPath($path);

如果字段類型找不到怎麼辦？默認會被轉換成text類型。

小結

這章討論了插件參數，如果在XML配置文件中定義，如果在插件php文件中使用。也學習瞭如果自定義JForm使用新的插件類型。通過前四章，可以寫一個插件，完成安裝，更新和自定義表單。雖然沒有針對特定的場景。