# OxOffice Online v4 模組開發

本節將會介紹如何使用 OxOffice Online Module SDK 開發 OxOffice Online 模組

# OxOOL v4 模組編譯手冊

## 一、環境準備

* 參考[技術手冊](https://docs.ossii.com.tw/books/oxoffice-online-%E6%8A%80%E8%A1%93%E6%89%8B%E5%86%8A/chapter/oxoffice-online)，先行編譯 oxool-community 以產生 oxool 開發相關套件。

	* 請留意：此步驟編譯 oxool-community 時應使用 `autogen.sh`，不需再執行 `configure`。`autogen.sh` 預設會開啟 `--enable-debug` 並載入 ModuleTesting 模組供開發測試使用。

	* 透過 `rpmbuild` 或 `debuild` 產生 `oxool` 與 `oxool-dev` 安裝套件。

* 將產生出來之 oxool-dev 套件安裝於系統內。oxool-dev 內含編譯模組所需之標頭檔、模組範本與 `oxool-module-maker` 程式。

## 二、使用 oxool-module-maker 產生模組基本檔案

* 執行 oxool-module-maker 以產生新模組的基本檔案。參數說明如下：

	* `--module-name=name` : 模組名稱。必須符合正規表示式： `^[\w\@#]+$`，也就是所有的大小寫英文字母、數字0-9、底線以及 # @ 三種符號的組合。注意減號 '-' 不能使用，而底線雖然可以使用但不建議。

	* `--serviceURI=serviceURI` : 此模組所使用的網址路徑。若結尾有 / 表示此模組會處理一系列指令。例如 "/oxool/user/" 表示此模組可能會處理 /oxool/user/add 、 /oxool/user/del 、 /oxool/user/update 等一系列動作。若結尾沒有 / 則為固定的網址路徑。

	* `--version=version` : 指定版號。預設為 "0.0.1"。

	* `--summary=summary` : 指定 Summary，用於產生出來的rpm 檔。

	* `--description=Description` : 指定 Description，用於產生出來的 deb 檔。

	* `--author=author` : 模組作者。預設會去找使用者全域 git 設定中的 user.name 與 user.email 兩個欄位。

	* `--license=license` : 所使用的授權條款。預設為 MPLv2.0。

	* `--adminPrivilege=true/false` : 此模組的網址路徑是否需要 admin 權限。預設為 false。

	* `--adminIcon=icon` : 在後台管理介面中所使用的圖示（請參考 getbootstrap.com 。預設值為 "bug-fill"。

	* `--adminItem=text` : 在後台管理介面中所使用的文字。

	* `--template-path=path` : 指定模組範本路徑，也就是產生新模組時要從哪裡複製檔案過來。預設會從 `/usr/share/oxool-devel/module-template` 中複製模組檔案。

	* `--output-path=path` : 指定產生的模組要放在哪個路徑。預設為使用者的家目錄。要留意不能用 ~ 符號。最好使用完整路徑。

	* 執行範例：
```
oxool-module-maker --module-name="samplemod" --serviceURI="/oxool/samplemod/" --summary="A sample moudle service on OxOOL" --description="A sample module service on OxOOL" --output-path="/home/oxool/git"
```

* 完成後在指定的 output-path 中會產生一個 git repository。裡面的內容是 template-path 參數指定的路徑裡的內容。

## 三、編譯與測試模組

* 用 `autogen.sh` 產生 configure 檔，然後用 `configure` 去確認該有的標頭檔、函式庫等是否都存在，並產生 Makefile 檔。

* 用 `make` 編譯。

* 測試模組前，先在 oxool-community 中執行 `make run` 啟動 oxool 服務。

* 啟動後，在模組目錄中執行 `./test.sh <模組的 XML 檔>`。`test.sh` 會呼叫 oxool 服務中的 ModuleTesting 模組，並將 XML 路徑傳送過去。ModuleTesting 模組則會通知 oxool 載入模組的 .so 檔（模組編譯完成後可以在 `.libs/` 目錄下找到此模組的 .so 檔）。此時就可以透過 `serviceURI` 指定的網址路徑執行模組。例如在瀏覽器中輸入：`http://127.0.0.1:9980/oxool/samplemod/`。

* 模組修改後需重新編譯並重新執行 `test.sh` 以便把新的 .so 檔載入 oxool 服務中。

# OxOOL 模組開發手冊

本手冊將簡單介紹 OxOOL 模組結構與開發說明。

## OxOOL 預設模組檔案結構

這裡就以使用 `oxool-module-maker` 並以 `oxool-dev` 套件中預設之模組範本產生之新模組為例，重要的檔案與目錄重點說明如下：

* `ModuleConfiguration.md` : 模組配置檔說明。
* `module.xml.in` : 模組配置檔，用來在執行 `configure` 時產生模組 XML 檔。如果在 `oxool-module-maker` 所下的參數有誤或需要修改、需要調整 XML 檔中的內容或新增標籤等，則可根據 `ModuleConfiguration.md` 中的說明修改此檔並重新執行 `autogen.sh` 與 `configure`。
* `module.spec.in` : 用來產生 rpm 軟體包的 spec 檔。
* `debian/*` : 用來產生 deb 軟體包的檔案。
* `admin/*` : 如果模組有後端管理介面，則放在此處。管理介面裡顯示的名稱定義在 `module.xml.in` 中的 `<adminItem>` 標籤，或是在執行 `oxool-module-maker` 時指定的 `--adminItem` 參數。可參考 README.md 中的說明。
* `src/*` : 模組的 C++ 源碼檔，會編譯成 .so 檔並在 OxOOL 執行時載入。
* `html/*` : 模組前端網頁介面。模組可以不必用 C++ 實作，而是直接透過網頁進行。預設的頁面為 index.html。
* `test.sh` : 模組開發期間測試時，只要執行此檔，並將模組的 XML 檔傳給 OxOOL 即可進行測試。可參考 OxOOL模組編譯手冊中的說明。

## OxOOL 模組中 C++ 的類別與方法

`oxool-module-maker` 產生之新模組，預設在 src 下會有 `Module.cpp` 檔，裡面定義此模組的基礎類別，以模組名稱為類別名稱。裡面除了建構子與解構子之外，定義了幾個方法：

* `getVersion()` : 取得版本號。
* `initialize()` : 初始化模組。
* `handleRequest()` : 處理來自前端 Client 對模組的請求。根據模組需求去實作每個請求。
* `handleAdminRequest()` : 處理來自後端管理介面對模組的請求。根據模組需求去實作每個請求。
* `handleAdminMessage()` : 處理來自後端管理介面對模組傳送的 websocket 訊息。