Etherpad/外掛
出自福留子孫
可參考以下影片
寫出第一個Etherpad外掛步驟
- 可將 setting.json 中 "minify" 的設定由 true 改成 false ，方便 debug
- 創造 plugins 資料夾(舉例 ep_previewimages)
- 在資料夾中新增 packages.json ，裡面打此外掛的基本資訊(名字 作者 版本 描述 貢獻者 運行引擎)，無涉外掛運用(範例(搜尋Package definition))
其中 name 為外掛的名字， version 為外掛版本， description 為外掛介紹， author 為外掛作者， contributors 為貢獻者名單， dependencies 為寫程式所依賴的工具包， engines 為運行引擎。
{
"name": "ep_PLUGINNAME",
"version": "0.0.1",
"description": "DESCRIPTION",
"author": "USERNAME (REAL NAME) <MAIL@EXAMPLE.COM>",
"contributors": [],
"dependencies": {"MODULE": "0.3.20"},
"engines": {"node": ">=12.13.0"}
}
- 以 ep_previewimages 中的 packages.json 為例：
{
"name":"ep_previewimages",
"description":"Image previewer, paste the URL of an image or upload an image using ep_fileupload",
"version":"0.0.13",
"author":"johnyma22 (John McLear) <john@mclear.co.uk>",
"contributors":[],
"dependencies":{},
"repository":{"type":"git","url":"https://github.com/JohnMcLear/ep_previewimages.git"},
"engines":{"node":"*"}
}
- 在資料夾中新增 ep.json ，裡面打外掛的函式介紹(範例(搜尋Plugin definition))
其中 name 為外掛名字， hook 及 client hook 中會寫出外掛使用的函式及位置。
{
"parts":[
{
"name":"nameThisPartHoweverYouWant",
"hooks":{
"authenticate":"ep_<plugin>/<file>:functionName1",
"expressCreateServer":ep_<plugin>/<file>:functionName2"
},
"client_hooks":{"acePopulateDOMLine":"ep_<plugin>/<file>:functionName3"}
}
]
}
- 以 ep_previewimages 中的 ep.json 為例：
{
"parts":[
{
"name":"ep_previewimages",
"client_hooks":{
"aceGetFilterStack":"ep_previewimages/static/js/index:aceGetFilterStack",
"aceCreateDomLine":"ep_previewimages/static/js/index:aceCreateDomLine"
}
}
]
}
- 最後寫出 index.js 裡面使用 javascript 語法寫出所需要的函式。
可用函式解說：
在解說 index.js 之前，先介紹一些其中可以用的函式：
- Etherpad 中，「ACE」是「Asynchronous Collaborative Editing」(非同步協同編輯)的縮寫。Etherpad 使用 ACE 來實現多人實時協同編輯功能。外掛中的 ace 前綴指的是與 Etherpad 的協同編輯引擎相關的功能或操作。
- exports 物件， Node.js 的原生物件，用來定義模組的公開介面，也就是透過「require」引入模組後，可以訪問的屬性或方法。
如「exports.aceGetFilterStack = function(name, context){...} 」是 Etherpad ep_previewimages 外掛的方法，載入此外掛後。就可以使用此方法來過濾出文本中匹配的行。 - 特定含義函式引數：
- name(名稱)：這個參數代表了觸發這個函數的鉤子(hook)名稱。在調用函式中，開發者一般不需要對 name 參數進行操作，但有時候這個參數可以用於區分不同的鉤子。
- args(參數)：這個參數是一個物件，包含了與該鉤子相關的數據。在 aceCreateDomLine 函式的例子中， args 物件包含了與 DOM 行相關的資訊，如 CSS 類別名稱(args.cls)。開發者可以通過操作這些參數來自定義外掛的行為。
- context：物件，其屬性和方法可能會因具體的外掛鉤子(hook)而有所不同。但通常會與當前 Etherpad 外掛操作的上下文信息相關。在這個例子中，context 物件包含一個名為 「linestylefilter」的屬性，它提供了一個方法「getRegexpFilter(...)」來創建正規表示式過濾器。「linestylefilter」是 Etherpad 中一個用於處理文檔「行」樣式的組件，它可以讓外掛開發者更方便地為文檔中的文本添加樣式。
- context.linestylefilter.getRegexpFilter(第一參數,第二參數)，造一個正規表示式過濾器，造好後添加到過濾器堆疊中，並在處理 Etherpad 文檔時使用。
- 第一個參數：一個正則表達式物件，用於指定要在文本中匹配的模式。如：「new RegExp("http.+((\.[pP][nN][gG])|(\.[jJ][pP][gG])|(\.[gG][iI][fF])|(\.[jJ][pP][eE][gG])|(\.[bB][mM][pP])|(\.[sS][vV][gG]))","g")」
- 第二個參數：一個字串，用於指定「與匹配到的文本相關聯」的樣式名。如："image"。
產生 img 標籤：
// 定義名為 aceCreateDomLine 的插件函數，該函數接收兩個參數：name 和 args
exports.aceCreateDomLine = function (name, args) {
// 檢查 args.cls 中是否包含 'image'，即是否為圖片 URL
if (args.cls.indexOf("image") > -1) {
// 定義一個變數 src，用於存儲圖片 URL
var src;
// 使用正則表達式替換 args.cls 中的圖片 URL
cls = args.cls.replace(/(^| )image:(\S+)/g, function (x0, space, image) {
// 將圖片 URL 設置為 src
src = image;
// 返回一個新的 CSS class，格式為 'image image_URL'
return space + "image image_" + image;
});
// 返回一個 DOM 行描述物件的陣列，其中包含圖片元素及其樣式
// 注意：這裡的額外 span 包裹器是必需的，用於避免在圖片 URL 之後輸入文字時出現錯誤
return [
{
cls: cls,
extraOpenTags:
'<span style="display:block;"><img src="' +
src +
'" style="max-width:100%" /></span>',
extraCloseTags: "",
},
];
}
};
- 函數 aceCreateDomLine 首先檢查 args.cls 是否包含 'image'。
- 如果是圖片 URL，則將 URL 設置為變數 src。
- 替換 args.cls 中的圖片 URL，生成一個新的 CSS class，格式為 'image image_URL'。
- 返回一個 DOM 行描述物件的陣列，其中包含圖片元素及其樣式。
- 這裡使用一個額外的 span 元素包裹圖片，以避免在圖片 URL 之後輸入文字時出現錯誤。
