手冊:內容處理器
| 內容模型及處理器 |
|---|
| MediaWiki允許維基文本之外的頁面內容類型。 提供對JavaScript、CSS、JSON和純文本的內置支持。 擴展功能可以使用MediaWiki的內容處理器(ContentHandler)機制來添加新的內容模型,以便接受不同格式的文本,並控制這些頁面如何渲染、存儲和編輯。 |
| 關於 |
|
關於內容處理器 內容處理器及其實現 |
| 用法 |
|
更改頁面的內容模型 更改命名空間的內容模型 使用內容處理器的擴展功能 添加帶副檔名的內容模型 示例: |
| 組態設定 |
|
$wgContentHandlers $wgNamespaceContentModels $wgContentHandlerTextFallback $wgContentHandlerUseDB |
| 支持和發展 |
|
最新技術文檔(Git) Phabricator |
| 查 · 論 · 編 |
內容處理器(ContentHandler)是一種在維基頁面上支援任意內容類型的機制,而不是一切都依賴於維基文字來處理所有內容。 這原先是作為維基數據專案的一部份開發的,而從1.21版本開始成了MediaWiki核心的一部分。
有關內容處理器架構的典型概述,請參閱MediaWiki代碼文件中的內容處理器。
有關可用的內容處理器的列表,請參閱內容處理器 。
關於
這一相當激進的改變背後的原因是,在MediaWiki中,被迫依賴wikitext來取得所有內容使得很多事情變得相當麻煩。 新的可插拔架構適用於任意類型的頁面內容,這將使我們能夠:
- 在部分或全部頁面上使用不同的標記式語言,如TeX或Markdown。
- 取消CSS和JavaScrip 頁面的特例。
- 儲存和編輯結構化組態數據的方式比Gadgets擴充在MediaWiki:Gadgets-definition頁面或 LanguageConverter在MediaWiki:Conversiontable***頁面上使用的方式更合理。
- 為 wikitext 頁面提供數據「附件」,例如地理數據(使用頁面的「多部分」內容模型,類似於使用多部分資訊格式實現電子郵件附件的方式)。 (註:該計劃從未實現,現已被Multi-Content Revisions 取代)。
- 過渡到不在維基文字中維護類別等內容的系統,但仍以通常的方式進行儲存和版本控制(再次使用多部分內容模型)。
- 為維基數據輕鬆儲存結構化數據,並將其作為頁面內容。
設計理念
我們的想法是,以與目前儲存 wikitext 完全相同的方式儲存其他類型的數據,但要讓MediaWiki知道每個頁面所處理的內容類型。 這樣,任何類型的數據都可以用作維基頁面的內容,而且其儲存和版本控制都與以前完全一樣。 為了實現這一目標,我們在MediaWiki核心中實現了以下功能:
- 追蹤每個頁面的「內容模型」。 這主要是在資料庫中的page表(也包括revision和archive表)中完成的,並可透過
Title、RevisionRecord、和WikiPage等相關核心類別存取。 「內容模型」定義了內容的「原生形式」,無論是包含文字的字串、巢狀陣列結構,還是PHP物件。 對內容的所有操作都是在其「原生形式」上進行的。 - 跟蹤每次修訂的「內容格式」(序列化格式)。 這主要是在資料庫中的revision表(也包括archive表,但不包括page表)中完成的,並可透過相關的核心類(如
RevisionRecord)存取。 請注意,序列化格式只與載入和儲存修訂版時相關,不會對內容的序列化形式執行任何操作。
這意味着所有需要對內容執行任何操作的代碼都必須了解內容的原生形式。 這些知識透過基於兩個類別的可插拔處理器框架進行封裝:
Content類別表示內容本身,並為在內容原生形式上執行所有標準操作提供介面。 它不知道內容屬於哪個頁面或版本。 內容物件一般是、但不必然是,不可變的。ContentHandler類別,代表有關內容模型具體內容的知識,但不能存取具體的內容。 最重要的是,內容處理器的實例可作為內容物件的工廠,並提供序列化/反序列化功能。 內容物件是無狀態的單例模式,每個內容模型都有一個。
內容處理器也用於生成Article,EditPage,SlotDiffRenderer等子類別的合適實例。
這樣,就可以透過內容處理器介面輕鬆為每種內容類型插入專門的用戶介面。
所有以任何方式存取修訂文字的代碼都應修改為使用內容物件所提供的方法。
存取修訂文字的核心類別(最重要的是RevisionRecord和WikiPage類)已進行調整,以提供對相應內容物件的存取,而不是對文字的存取。
向下相容
在MediaWiki代碼庫中,頁面包含有維基文字的假設是非常普遍的。因此,與仍然如此假設的部分代碼,尤其是與擴充,保持相容是非常重要的。
當然,提供良好相容性的正確方法是不去變更公共介面。
因此,所有提供存取修訂內容的方法(就像Revision::getText()等)仍然保留,而是以允許存取內容物件的替代方法(如Revision::getContent())輔助。
基於文字的方法現已棄用,但對所有包含維基文字的頁面/修訂版而言,其功能與以前完全相同。
這也同樣適用於Action API。
我們提供了一個方便的方法--ContentHandler::getContentText(),以方便獲取某個頁面的文字。
對於平坦的基於文字內容模型,如維基文字(也包括 JS 和 CSS),對於此類修訂,getContentText()將只返回文字,舊的基於文字方法也將返回相同的結果,如同以前一樣。
不過,如果在不包含維基文字(或其他如 CSS的平坦文字內容模型)的頁面/修訂版上呼叫基於文字的向下相容方法,其行為取決於$wgContentHandlerTextFallback的設置:「ignore」(忽略)使其返回空值,「fail」(失敗)使其引發異常,而 「serialize」(序列化)則使其返回預設的序列化內容。
預設設置為「ignore」(忽略),這可能是大多數情況下最保守的選擇。
但對於編輯,預設情況下不支援非文字內容。
EditPage和Action API中的相應處理器將無法處理非文字內容。
連結
Content和ContentHandler類別
- 設定
- 使用內容處理器的擴充
- 如何添加帶有副檔名的內容模型: 頁面內容模型
- 基本例子: Extension:Markdown
- 分類:ContentHandler擴充功能
- Examples 擴充
- 內容處理器 — 所有內容模型的列表(包括在核心和在擴充中的)
代碼維護
- Maintained by Unknown or Unassigned[Maintainers page].
- Issue tracker: Phabricator MediaWiki-ContentHandler (Report an issue)