?? plugins_design.htm
字號:
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=gb2312">
<title>Discuz! 用戶使用說明書 - 插件相關</title><link rel="stylesheet" href="discuz_guide.css">
<base target="_blank">
</head>
<body leftmargin="0" rightmargin="0" topmargin="0">
<script language="JavaScript" src="header.js"></script>
<table width="100%" cellpadding="0" cellspacing="0" border="0">
<tr><td class="title">本欄目下相關鏈接</td></tr>
<tr><td><br><ul><script language="JavaScript" src="plugins.js"></script></ul><br></td></tr>
<tr><td class="title">插件設計</td></tr>
<tr><td><br>
<p>您在開始論壇插件的設計之前，有必要了解一下我們所推薦的插件設計方式，更好的規范性和兼容性，將使得您設計的插件受到更多使用者的歡迎，對于程序員而言，也有助于形成良好的編碼習慣，實現自身能力的提升。如果您有意編寫 Discuz! 論壇插件，請按照先后順序仔細閱讀本文檔。
<br><br><br></td></tr><tr><td class="title">準備工作</td></tr>
<tr><td><br>
<p class="subtitle">插件實現流程<ul>
<p>開始編寫論壇插件，您應當首先對插件實現的流程有一個大致的了解，以下是我們推薦的插件編寫流程：
<p><ul>
<li>熟練使用 Discuz! 論壇系統后，對希望完善或補充的個性化功能進行評估，進而提出插件的功能需求。
<li>對插件做一個概括性的設計，例如：需要使用什么菜單、什么參數，配置哪些選項、數據結構如何設計、前后臺實現哪些功能等等。
<li>閱讀本文檔并在系統設置中實際體驗 Discuz! 插件接口所實現的功用，例如：您的插件應當如何設計才能良好的掛接到論壇系統中來。插件接口能夠實現哪些功能、不能實現哪些功能，插件為此而需要做的優化、改造和取舍。
<li>編寫相應程序代碼和模板語句，實現所需的功能并進行代碼測試、兼容性測試和代碼改進。
<li>如果需要公開您的插件，可以用插件導出的方式，將插件配置信息導出到一個文本文件中，連同相應的程序和模板文件一同打包。同時，編寫一個適合新手的插件的說明書也是必不可少的，其中包括：插件適用的 Discuz! 版本、功能概述、兼容性聲明、安裝方法、使用方法、卸載方法等等。
<li>將插件提供給他人，或自己使用，根據使用者反饋，對插件進行完善。插件實現流程至此結束。
</ul>
</ul><p class="subtitle">文件命名規范<ul>
<p>Discuz! 按照如下的規范對程序和模板進行命名，請在設計插件時盡量遵循此命名規范：
<p><ul>
<li>可以直接通過瀏覽器訪問的普通程序文件，以 .php 后綴命名。
<li>被普通程序文件引用的程序文件，以 .inc.php 后綴命名。
<li>被普通程序文件，或引用程序文件引用的函數庫或類庫，以 .func.php(函數庫) 或 .class.php(類庫) 后綴命名。
<li>模板文件，以 .htm 后綴命名，模板文件只存在于 ./templates 目錄中。
<li>模板語言包文件，以 .lang.php 后綴命名，語言包文件只存放于 ./templates 目錄中，與模板文件同級目錄。
<li>被編譯后的模板文件，以 .tpl.php 后綴命名，前面的數字是模板套系的 ID，下劃線后面的是模板原名，編譯模板文件只存在于 ./forumdata/templates 目錄中。
<li>動態緩存文件，存放于 ./forumdata/cache 目錄中，依據不同的功用進行獨立的命名。
<li>使用后臺數據備份功能生成的備份文件，通常以 .sql 為后綴，存放于 ./forumdata/ 目錄中。
<li>有些目錄中存在內容為空白的 index.htm 文件，此類文件是為了避免 Web 服務器打開 Directory Index 時可能產生的安全問題。
</ul></ul><p class="subtitle">common.inc.php 模塊功能白皮書<ul>
<p>./include/common.inc.php 是 Discuz! 的通用初始化模塊程序，其幾乎被所有的外部代碼所引用，在您開始插件設計之前，可以先對該模塊的大致功能做一定的了解。common.inc.php 主要完成了以下任務：
<p><ul>
<li>對不同 PHP 及操作系統環境做了判斷和兼容性處理，使得 Discuz! 可以運行于各種不同配置的服務器環境下。
<li>初始化常量 IN_DISCUZ 為 TRUE，用于 include 或 require 后續程序的判斷，避免其他程序被非法引用。
<li>讀取論壇所在絕對路徑，存放于常量 DISCUZ_ROOT 中。
<li>加載所需的基本函數庫 include/global.func.php。
<li>通過 config.inc.php 中提供的數據庫賬號信息，建立數據庫連接。Discuz!支持數據表的前綴，如需獲得表的全名，可使用”{$tablepre}tablename”
或 $tablepre.’tablename’的方式。
<li>判斷用戶是否登錄，如登錄標記 $discuz_uid 為非 0，同時將 $discuz_user（加了 slash 的用戶名，可用于不加修改的插入數據庫）、
$discuz_userss（原始的用戶名，可用于頁面顯示）、$discuz_pw（用戶密碼的MD5串）、$discuz_secques（登錄提示問題的加密串）等相應用戶信息賦值。
<li>判斷用戶管理權限，將管理權限標記 $adminid 為 -1~3 中間的值。-1 代表為特殊用戶組用戶。0 代表普通用戶；1 代表論壇管理員；2 代表超級版主；3 代表論壇版主。
將用戶權限按照其所在的主用戶組 ID 標記為 $groupid，相關權限從該 $groupid 所對應的系統緩存中讀出（./forumdata/cache/usergroup_$groupid.php）。
將用戶擴展權限按照其擴展用戶組 ID 標記為 $extgroupids，中間以 \t（tab） 分隔，格式為“$groupid1\t$groupid2...”，擴展用戶組用于確定用戶的擴展瀏覽權限，例如能否訪問某些有特殊權限設定的論壇等。
<li>讀入系統設置中的各種變量，并根據 Cache 模塊的設定，根據當前被調用的程序文件名（如 index.php，forumdisplay.php 等等）讀入
相應的緩存代碼。緩存代碼被存放于 ./forumdata/cache/ 中。除了對應當前程序的緩存，可能還會加載一些通用的緩存數據，例如整個論壇
的設置（./forumdata/cache/cache_settings.php）、界面風格（./forumdata/cache/style_x.php）、當前用戶的用戶組（./forumdata/cache/usergroup_x.php）、
管理組權限（./forumdata/cache/adminusergroup_x.php）等。
<li>緩存數據的格式，大多是存放在 $_DCACHE['cachename'] 數組中，有些常用的參數，如系統設置中的參數、風格界面等，通常還被進行了
展開操作（extract）或使用常量進行賦值。
<li>用戶如果處在登錄狀態，會自動讀出 members 表相關用戶的參數值，用戶的個性設置參數：如時差、時間格式、界面風格等等，會根據實際
情況覆蓋系統默認值，因此在后續程序通常不用再做判斷。
<li>如果程序提交的 URL 中包含 tid=x 或 fid=x，common.inc.php 模塊會自動讀出其所對應的論壇記錄及包括 access masks、版主設定等相應
權限，記錄在 $forum 變量中。后續程序只要通過URL將tid或fid傳遞過來，便可通過 $forum 數組的存在性或相關參數來對論壇權限進行判斷，
不需要再讀 forums 表的資料。
</ul>
<br><br></td></tr><tr><td class="title">插件接口概述</td></tr>
<tr><td><br>
<p>使用管理員賬號登錄 Discuz! 系統設置，在左側菜單將可以看到“插件設置”和“插件管理”兩個選項，使用超級版主或版主賬號登錄，將只出現“插件設置”一個選項。“插件管理”是控制插件打開與否、設計插件模塊、菜單、參數和使用權限的地方，插件開發者可以依照設計意圖，在此進行插件的初步設置，這里同時也提供插件導入和插件開關的功能，用于導入他人設計的插件和對插件的可用狀態進行變更。“插件設置”是對已經安裝的插件進行設置的地方，供使用者對插件參數進行調整以實現不同的插件功能。即前者主要面向開發者，后者主要面向使用者。
<p>開始編寫一個新插件，請首先在插件管理中，輸入新插件的名稱和惟一標識符。名稱用于表明此插件的用途，例如設置為“虛擬銀行插件”。惟一標識符用于在后續的插件模塊中調用本插件，不可與現有插件重復，命名規則限制與 PHP 變量命名相同，雖然初次設置后仍可改動，但強烈建議一次性將此配置設置好，否則可能涉及到很多代碼方面的變更，增加編碼的麻煩。請注意：惟一標識符請不要設置的過短，或使用有可能與其他插件重復的命名，例如制作此插件的公司叫做 Comsenz Inc.，插件名稱是“虛擬銀行插件”，惟一標識符可設置為“comsenz_virtual_bank”，后面將以“虛擬銀行插件”和“comsenz_virtual_bank”為例進行說明。
<p>在插件管理中添加插件后，僅僅是增加了一條插件記錄，后面還需要很多相關的設計和設置。在列表中選擇插件的“詳情”進入插件的詳細設置。插件設置分為三個部分：
<ul>
<p><li><b>插件基本設置：</b><br>設置插件的基本參數，配置項目右邊括號中的內容，為此設置對應的參數名稱，調用方法將在后面的《參數讀取與緩存控制》中詳細說明。
<p><li><b>插件模塊和自定義菜單：</b><br>插件接口默認提供四種可選的模塊方式：<ul>
<li>直接鏈接（前臺菜單）：可在前臺右上角加入一個菜單項，可自主指派菜單鏈接的 URL。注意：由于引用外部程序，因此即便設置了模塊的使用等級，您的程序如需權限判斷，仍需要引用 common.inc.php 和插件相關的緩存文件（將在后面的《參數讀取與緩存控制》中詳細說明），并自行判斷使用等級是否合法。
<li>前臺調用（前臺菜單）：與直接鏈接類似，但其調用的是插件的一個模塊，模塊文件名指派為“./plugins/插件目錄/插件模塊名.inc.php”，由 plugin.php 調用此模塊，調用 URL 將在后面的《編寫插件的原則與注意事項》中詳細說明。
<li>后臺調用（后臺菜單）：可在后臺插件設置中為此插件增添一個管理模塊，模塊文件名指派為“./plugins/插件目錄/插件模塊名.inc.php”，由 admincp.php 調用此模塊，調用 URL 將在后面的《編寫插件的原則與注意事項》中詳細說明。
<li>包含運行（無菜單）：可設置一個在論壇所有頁面均包含運行的腳本，此腳本在 ./include/common.inc.php 中加載，腳本文件名指派為“./plugins/插件目錄/插件模塊名.inc.php”。請注意，為了不導致錯誤的插件影響論壇運行，在 common.inc.php 加載此模塊時，屏蔽了錯誤信息，因此請務必仔細檢查是否存在語法錯誤，任何微小的語法錯誤都將不被提示出來，并且導致此模塊不被正常加載。如果您配置了不正確的包含腳本而導致論壇系統設置無法使用，刪除服務器上相應的腳本文件即可解決。
</ul>
您可以為每個模塊設置不同的使用等級，例如設置為“超級版主”，則超級版主及更高的管理者（例如論壇管理員）可以使用此模塊。
<p><li><b>插件鉤子設置：</b><br>插件鉤子能夠將插件代碼埋藏在程序中的任意位置，從而實現更加靈活的插件功能，最大限度的減少對原有程序代碼的修改。 論壇版本升級后，只需將相應鉤子重新埋入相應程序中，原有插件即可繼續使用。 關于插件鉤子的具體設計方法請見下面的《插件鉤子的設計》。
<p><li><b>插件變量配置：</b><br>插件接口中提供了一個通用的插件配置管理程序，在大多數情況下可實現插件的參數配置，省卻了插件開發者自行編寫后臺管理模塊（即上面提到的“后臺調用（后臺菜單）”模塊）的麻煩。通常情況下，應優先使用通用插件配置管理程序來實現插件的參數配置，只有在通用程序確實無法實現時，才自行編寫后臺管理模塊。輸入配置名稱和配置變量名、選擇合適的配置類型后，即可為此插件增加一個配置變量，點“詳情”可以編輯此配置變量的更多信息。為了方便插件程序調用使用者配置好的參數，配置變量同樣被存放在了緩存文件中，讀取方法將在后面的《參數讀取與緩存控制》中詳細說明。
<p><b>注意：您只有在插件管理中將插件設置為“可用”，以上設置才能生效。</b>
</ul><br></td></tr><tr><td class="title">參數讀取與緩存控制</td></tr>
<tr><td><br>
<p>編寫插件程序時，可能需要讀取一些插件的信息，如果插件需要使用者進行配置，還需要讀取使用者設置的參數值。Discuz! 允許插件程序使用數據庫讀取和緩存讀取這兩種方法獲取插件信息和參數。Discuz! 的插件接口已經對插件信息進行了合理的緩存，使用緩存讀取的方式，將比數據庫讀取速度更快，消耗的資源更是幾乎可以忽略不計。緩存讀取唯一的局限是需要插件使用插件接口提供的通用后臺管理程序。如果使用自定義后臺模塊的方式，需要后臺模塊將參數存放到 pluginvars 數據表中，才能被系統正常緩存。我們強烈推薦您通過緩存讀取插件信息和配置數據。
<p class="subtitle">插件數據結構<ul>
<p>插件數據使用兩個數據表存放，分別是 plugins 和 pluginvars。前者用于存放插件信息：安裝了多少個插件，就有多少條記錄；后者用于存放插件的配置參數和配置值：所有已安裝的插件總共有多少個配置項目，就有多少條記錄。下面的表格列出了這兩個表的主要字段及其用途說明。
<p>plugins 表：
<table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td><pre>
pluginid 插件的惟一 ID，自動遞增
available 插件是否可用，1=是，0=否
adminid 使用系統設置中插件接口自帶的插件參數設置程序所需的最低權限等級要求，1=管理員，2=超級版主，3=版主
name 插件名稱
identifier 插件惟一標識符
description 插件簡介
datatables 插件數據表，不包含前綴，多個表使用半角逗號“,”分隔
directory 插件所在目錄，例如設置為 comsenz_bank，則對應論壇目錄的位置為 ./plugins/comsenz_bank/
copyright 插件版權信息
modules 插件模塊信息，數組格式，使用 serialize() 序列化后存放
</pre></td></tr></table>
<p>pluginvars 表：
<table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td><pre>
?? 快捷鍵說明
復制代碼
Ctrl + C
搜索代碼
Ctrl + F
全屏模式
F11
切換主題
Ctrl + Shift + D
顯示快捷鍵
?
增大字號
Ctrl + =
減小字號
Ctrl + -