# DocuWidgets 使用導引 (舊版)

<!-- 標籤 -->
###### tags: `使用導引`, `文件狀態：停止更新`

<!-- 內文編輯更新資訊，若有更動此份文件內容，請更新此項資訊 -->
> [name=Hsieh-Chang Tu, 杜協昌]
> [time=Aug, 2017]

<!-- 摘要 -->
:::success

<!-- 當前負責人使用高亮標示，新接替維護人員請加在第一個 -->
- **建立者**：杜協昌
- **維護者**：杜協昌

:::

<!-- 筆記正文開始 -->

## Briefly description
- DocuWidgets 是由數個 DocuSky widgets 所組成。其中，每個 widget 是一份 JavaScript 元件形式的程式碼， 便利工具開發者存取 DocuSky 上的資料。
- DocuSky 提供一組 Web API 供工具開發者存取 DocuSky 的資料。這些 API 可讓工具透過 HTTP protocol 來進行使用者登入、登出、資料庫列表、資料庫查詢、以及二進位檔案 (binary file) 上載與下載等操作。 DocuSky widgets 可將登入認證的程序包裝起來，如此工具開發者就不必去處理繁雜的認證程序。 此外，widget 也將 DocuSky Web API 以 JavaScript 物件的形式進行包裝， 如此工具就可直接呼叫物件的函式（而不需自己處理 Web API 的輸入輸出格式）來存取 DocuSky 資料。 DocuSky widgets 必須使用 jQuery 和 jQuery UI 來進行一些版面的設定。 因此工具程式除了引入 widget 外，也需引入 jQuery 和 jQuery UI 的程式庫。
- 目前，DocuSky 提供了三個簡單的 widgets：
1. ++docusky.ui.getDbCorpusDocumentsSimpleUI.js++
2. ++docusky.ui.manageDataFileListSimpleUI.js++
3. ++docusky.ui.manageDbListSimpleUI.js++
- 其中
- getDbCorpusDocumentsSimpleUI 可用來讓工具查找資料庫文件
- manageDataFileListSimpleUI 則可讓工具上載 binary file
- manageDbListSimpleUI 可用來讓使用者建構（透過上載 DocuXml 建庫檔）與刪除資料庫。 以下分別介紹這些 widgets 載入後所提供的函式 API。
## docusky.ui.getDbCorpusDocumentsSimpleUI.js
- **範例程式：**[簡單範例與說明](https://docusky.digital.ntu.edu.tw/DocuSky/documentation/docs/widget.getDbCorpusDocumentsSimpleUI/simpleExample-docs.html)
- 這個 widget 主要是提供查找資料庫文件的功能。工具引入 widget 後， 全域的 getDbCorpusDocumentsSimpleUI 物件將提供以下的方法 (methods)：
1. getDbCorpusDocuments(target, db, corpus, evt, successFunc)
2. getDbCorpusDocumentsGivenPageAndSize(target, db, corpus, page, pageSize, evt, successFunc, message)
3. getQueryResultDocuments(param, evt, successFunc, successFuncParameters)
4. addExtraApiFunctions(apiObj)
- **getDbCorpusDocuments(target, db, corpus, evt, successFunc)**
- 這個函式可指定的資料庫文獻集，然後取得其結果的第一頁內容。
- 它的功能，相當於在 getDbCorpusDocumentsGivenPageAndSize() 函式指定 page=1， 然後使用當前（預設）pageSize。
- target 的值必須是 'USER'
- db 的值為資料庫名稱，而 corpus 的值則為欲查詢的文獻集名稱
- evt 可傳入（例如滑鼠點選所觸發的事件）event 物件
- successFunc 則可傳入查找成功後的回呼 (callback) 函式。
- 查詢的回傳結果，可以從 getDbCorpusDocumentsSimpleUI 物件的相關屬性取得。這些屬性包括：
- query（查詢字串）
- totalFound（符合查詢的條目總筆數）
- page（當前的資料是查詢結果的第幾頁）
- pageSize（每頁的條目數量）
- docList（符合條件的回傳文件集）
- target（目前只能是 'USER'）
- db（資料庫名稱）
- corpus（文獻集名稱）
- spotlights（該文獻集的後分類項目編碼）
- 其中，docList 是一個陣列 \[e, e, ...\]，其中每一個元素 e 是一個包含回傳編號的物件：

     { 
         "number": ...,
         "docInfo": {...} 
     };

- docList 陣列元素的 docInfo 屬性中，包含了這篇文件的所有資訊。例如 DocuXml Sample-01 的文件上載建庫後， widget 所回傳的 docInfo 物件，應該長得像這樣 ：

    {
        "xmlFormatName": "ThdlContentXml",
        "docXmlFormatSubname": "-",
        "docId": "14428854",
        "docFilename": "cca100003_od_ta_01516_000112_0001_u.xml",
        "srcFilename": "DB_01001863_000.xml",
        "corpus": "古契書",
        "corpusOrder": "0",
        "docAuthor": "許汝旺(賣主)",
        "docCompilation": "臺灣總督府檔案抄錄契約文書‧永久保存公文類纂(國中圖93)",
        "placeInfo": {
            "geoLevel1": "桃澗堡",
            "geoLevel2": "銅鑼圈",
            "geoLevel3": "銅鑼圈庄",
            "geoX": "121.193740",
            "geoY": "24.839710"
        },
        "docTopicL1": "杜賣契",
        "docTopicL1Order": "0",
        "timeInfo": {
            "dateOrigStr": "道光十一年",
            "dateDynasty": "清",
            "dateEra": "道光",
            "dateAdDate": "18320103",
            "dateAdYear": "1832",
            "timeseqType": "my_time_sequence",
            "timeseqNumber": "1018320103",
            "dateChNormYear": "清道光十一年",
        },
        "docUserTagging": "測試;相關",
        "docTitleXml": "<DocTitle>賣土窨字｜臺灣總督府檔案</DocTitle>",
        "docMetadataXml": "<DocMetadata>...</DocMetadata>",
        "extraMetadata": {
            "allFeaturesXml": "<AllFeatures/>"
        },
        "docTimeCreated": "2017-07-26 11:12:00",
        "docContentXml": "<Content>od-ta_01516_000112 \n<LocName>桃澗堡</LocName>\n...</Content>"
    }

- 下表說明以上各屬性所代表的意義：

|docInfo 屬性名稱|說明|DocuXml 1.0 的對應標籤|
|--- |--- |--- |
|xmlFormatName|記錄當前的 XML 格式| |
|docXmlFormatSubname|當前 XML 格式的額外資訊| |
|docId|系統自動產生的文件辨識碼| |
|docFilename|文件的檔名（文獻集中可唯一辨識該文件的編碼）|\<document\> 的 filename 屬性|
|srcFilename|上載建庫過程中，系統自動產生的 XML 檔名||
|corpus|文件所屬的文獻集名稱|\<corpus\>|
|corpusOrder|文獻集的排序編號（數字小的文獻集會排在前面）|\<corpus\> 的 corpus_order 屬性|
|docAuthor|文件的作者|\<author\>|
|docCompilation|文件的出處|\<coompilation\>|
|placeInfo.geoLevel1|文件的地理資訊：地域階層第一層|\<geo_level1\>|
|placeInfo.geoLevel2|文件的地理資訊：地域階層第二層|\<geo_level2\>|
|placeInfo.geoLevel3|文件的地理資訊：地域階層第三層|\<geo_level3\>|
|placeInfo.geoX|文件的地理資訊：經度座標（可被換算為浮點數）|\<geo_longitude\>|
|placeInfo.geoY|文件的地理資訊：緯度座標（可被換算為浮點數）|\<geo_latitude\>|
|docTopicL1|文件的主題|\<topic\>|
|timeInfo.dateOrigStr|文件的時間資訊：原始的日期字串|\<time_orig_str\>|
|timeInfo.dateDynasty|文件的時間資訊：朝代|\<time_dynasty\>|
|timeInfo.dateEra|文件的時間資訊：年號|\<time_era\>|
|timeInfo.dateChNormYear|文件的時間資訊：中曆年|\<time_norm_year\>|
|timeInfo.dateAdDate|文件的時間資訊：西元日期（可被轉換為整數）|\<time_ad_date\>|
|timeInfo.dateAdYear|文件的時間資訊：西元年（可被轉換為整數）|\<time_ad_year\>|
|timeInfo.timeseqType|文件的時間資訊：時間序列的型態|\<timeseq_type\>|
|timeInfo.timeseqNumber|文件的時間資訊：時間序列的編號（可被轉換為數字）|\<timeseq_number\>|\
|docUserTagging|使用者自訂的標記資訊（一個詞彙列表，詞彙間以分號 ';' 隔開）|\<doc_user_tagging\>|
|docTitleXml|以 XML 表示的文件標題|\<title\>|
|docMetadataXml|以 XML 表示的（使用者自訂）詮釋資料|\<xml_metadata\>|
|extraMetadata|額外的詮釋資料（系統保留以後使用）||
|docTimeCreated|文件的建立時間||
|docContentXml|以 XML 表示的文件內文|\<doc_content\>|

- **getDbCorpusDocumentsGivenPageAndSize(target, db, corpus, page, pageSize, evt, successFunc, message)**
- 這個函式提供比 getDbCorpusDocumentsGivenPageAndSize() 更有彈性的功能。 它將 target, db, corpus, query, page, pageSize 等參數包裝到 param 物件內。 例如

    var param = { 
        "target": 'USER',
        "db": '我的資料庫',
        "corpus": '我的文獻集',
        "query": '芝麻',
        "page": 2,
        "pageSize": 100 
    };

- 可指定要在使用者資料庫「我的資料庫」、文獻集名稱「我的文獻集」中，查詢「芝麻」， 並回傳查詢結果的第 2 頁（每頁 100 筆文件，也就是第 101-200 筆資料）內容。 若在 param 中加入 message 屬性，則 widget 會將 message 的內容顯示在 loading icon（正在進行載入程序的動態圖示）內。
- `evt` 可傳入（例如滑鼠點選所觸發的事件）event 物件，而 `successFunc` 則傳入查找成功後的回呼函式。 與 getDbCorpusDocumentsGivenPageAndSize() 相較，這個函式還多出一個 successFuncParameters 參數，讓 widget 在成功從 DocuSky 取回資料後， 以 `successFunc(successFuncParameters)` 的方式， 將參數 successFuncParameters 傳給指定的回呼函式。
- **addExtraApiFunctions(apiObj)**
- 這個函式是用來在 getDbCorpusDocumentsSimpleUI 物件上，動態添加 dbRefdataAPI 的函式。 DocuSky 允許在每個資料庫中，以 JSON 格式儲存工具所需的 dbRefdata（資料庫參考資料）。 若這個資料庫被刪除，該資料庫下的所有 dbRefdata 都會被一併移除。欲存取一份 dbRefdata， 必須指定 dbTitle（該資料庫的名稱）、dbRefdataDatasetName（一般建議以專案或工具名稱， 來作為資料集名稱）、以及 dbRefdataName（資料名稱）。dbRefdataAPI 將這些存取的 Web API 包裝起來，以 JavaScript 物件函式的方式讓工具呼叫使用。
- dbRefdataAPI 將這些存取的 Web API 包裝起來，以 JavaScript 物件函式的方式讓工具呼叫使用。
- 範例程式：[範例截圖與程式](https://docusky.digital.ntu.edu.tw/DocuSky/documentation/docs/widget.getDbCorpusDocumentsSimpleUI/simpleExample-dbRefdata-docs.html)
- 工具程式可透過以下程式碼， 將 dbRefdataAPI 所提供的函式加入 getDbCorpusDocumentsSimpleUI 物件：

    var docuSkyObj = getDbCorpusDocumentsSimpleUI;
    $.getScript("js.ui/extra/docusky.dbRefdataAPI.js", function() {
        docuSkyObj.addExtraApiFunctions(appendDbRefdataAPI);
    });

- dbRefdataAPI 提供以下幾個函式：
- **deleteDbRefdataData(dbTitle, dbRefdataDatasetName, dbRefdataName, callback)**
- 嘗試從 DocuSky 中，刪除資料庫名稱 dbTitle，參考資料集名稱為 dbRefdataDatasetName 之下的 dbRefdataName 資料集。 接著，widget 會將控制權轉給 callback 回呼函式。
- **getDbRefdataData(dbTitle, dbRefdataDatasetName, dbRefdataName, callback)**
- 嘗試從 DocuSky 中，取得資料庫名稱 dbTitle、參考資料集名稱 dbRefdataDatasetName、且資料名稱為 dbRefdataName 的資料項。回呼函式 callback 可利用 `getDbCorpusDocumentsSimpleUI.dbRefdataObj` 取得 DocuSky 所回傳的 **dbRefdataObj 物件**：

            { 
                 "dbTitle": ...,
                 "dbRefdataDatasetName": ...,
                 "dbRefdataName": ...,
                 "dbRefdataType": ...,
                 "dbRefdataFormat": ...,
                 "dbRefdataFormatVersion": ...,
                 "dbRefdataData": ...
            }

- 其中，dbRefdataObj 物件的 dbRefdataData 屬性，就是以 JavaScript 物件形式儲存的該資料項內容。 也就是說，工具可透過 `getDbCorpusDocumentsSimpleUI.dbRefdataObj.dbRefdataData` 直接取得該資料項的內容。
- **getDbRefdataInfoList(dbTitle, callback)**
- 回傳資料庫名稱 dbTitle 下的所有資料集資訊。 工具可在回呼函式中，透過 `getDbCorpusDocumentsSimpleUI.dbRefdataInfoList` 來取得這些資料集的資訊列表。這個列表是一個 JavaScript 陣列， 其中每個元素都具有以下的結構（與 dbRefdataObj 物件 相較，少了 dbRefdataData 屬性）的物件，而每個物件則提供一份資料項的參考資訊。工具可透過 getDbRefdataData() 方法取得該資料項的內容。：

            { 
                "dbTitle": ...,
                "dbRefdataDatasetName": ...,
                "dbRefdataName": ...
                "dbRefdataType": ...,
                "dbRefdataFormat": ...,
                "dbRefdataFormatVersion": ...,
            }

- **replaceDbRefdataData(dbRefdataObj, callback)**
- 這個函式可將 dbRefdataObj 物件的 dbRefdataData 屬性內容， 儲存到 dbRefdataObj.dbTitle 資料庫、dbRefdataObj.dbRefdataDatasetName 資料集的 資料庫、dbRefdataObj.
- 另外，這個 widget 還提供以下幾個尚處於開發測試階段的函式：
:::success
1. getQueryPostClassification(param, evt, successFunc, successFuncParameters)
2. getQueryTagAnalysis(param, evt, successFunc, successFuncParameters)
3. hideLoadingIcon(bool)
4. hideWidget(bool)
5. setLoginAction(loginInvokeFun, loginInvokeFunParameters)
6. updateDocument(db, corpus, docInfo)
- getQueryPostClassification(param, evt, successFunc, successFuncParameters)
- 這個函式的參數與 getQueryResultDocuments() 相同，請參看該函式的說明。 它的目的，是將查詢的後分類結果，放到 getDbCorpusDocumentsSimpleUI 物件的 postClassification 屬性中。
- getQueryTagAnalysis(param, evt, successFunc, successFuncParameters)
- 這個函式的參數與 getQueryResultDocuments() 相同，請參看該函式的說明。 它的目的，是將查詢的標記分析結果，放到 getDbCorpusDocumentsSimpleUI 物件的 tagAnalysis 屬性中。
- hideLoadingIcon(bool)
- 由於通常需要一段時間才能從 DocuSky 將查詢結果的文件載入 widget 中， 因此 widget 在載入文件時，會在瀏覽器上顯示動態的 loading 圖示。 這個函式的目的，是讓工具程式能夠隱藏這個圖示。
- hideWidget(bool)
- 這個函式的目的，是讓工具程式能夠隱藏 widget。執行 getDbCorpusDocumentsSimpleUI.hideWidget(true) 後， widget 將盡量不在執行物件的 getDbCorpusDocuments()、 getDbCorpusDocumentsGivenPageAndSize() 或 getQueryResultDocuments() 方法過程中， 顯示 widget 的各項訊息。
- setLoginAction(loginInvokeFun, loginInvokeFunParameters)
- 這個函式的目的，是讓工具程式能夠設定成功登入後的行為。
- updateDocument(db, corpus, docInfo)
- 這個函式可讓工具程式動態更新文件的內容。 工具程式需在 db 和 corpus 參數指定正確的資料庫和文獻集名稱， 並且以 docInfo 物件的形式傳入文件欲更新的內容。 呼叫此函式後，widget 會嘗試更新該資料庫文獻集的文件內容，並以 JavaScript alert() 顯示是否更新成功。
- **注意**：此函式只能用於更新文件內容，並無法在資料庫的文獻集中新增文件。
:::

## docusky.ui.manageDataFileListSimpleUI.js
- 這個 widget 可讓使用者上載檔案，並且透過 widget 對這些檔案進行檢視或刪除。 上載的檔案需指定 category, datapath, filename 三項參數，而上載後工具或使用者可透過以下的 URL 從 DocuSky 取得這份檔案的內容。
- `http://docusky.digital.ntu.edu.tw/DocuSky/webApi/getDataFileBinary.php?catpathfile=<catpathfile>`
- **注意**：`<catpathfile>` 為 category, datapath, filename 三者串接（中間加上斜線 '/'）起來的字串 category/datapath/filename。
- **manageDataFileList(evt, successFunc)**
- 這個函式要求 widget 列出使用者儲存在 DocuSky 的資料檔案。 evt 可傳入使用者所點選的滑鼠事件，而 successCallback 這個參數可傳一個回呼函式， 要求 widget 在取得資料檔的列表後，將控制權轉移到回呼函式（若沒有傳入 successCallback 參數，widget 會在瀏覽器上顯示使用者的資料檔， 並讓使用者可以對資料檔進行檢視或刪除，或者上載一份資料檔）。
- 範例程式：[點我執行](https://docusky.digital.ntu.edu.tw/DocuSky/documentation/docs/widget.manageDataFileListSimpleUI/simpleExample-manageDataFileList.html)
- 以下的函式，則仍處於開發測試階段：
:::success
- **hideWidget(bool)**
- 這個函式的目的，是讓工具程式能夠隱藏 widget。
- 這個 widget 另外提供了一個 jsonTransporter 物件， 讓工具程式經由這個物件在 DocuSky 上以 JSON 格式來存取資料。 這些資料對使用者帳號而言是全域的（刪除資料庫後依然存在，且其他的工具也可存取到）， 而工具必須提供 category, datapath, 以及 filename 來唯一辨識這個 JSON 物件。 為了避免其他工具錯誤存取到這個物件，我們建議在 category 填入專案或工具的名稱， datapath 填入工具對這個 JSON 物件的分類路徑， 而 filename 則以 xxx.json 的形式（以 .json 作為附加檔名）指定檔案名稱。
- 注意到，呼叫這些函式後，回傳的結果都必須在回呼函式中處理。 DocuSky 回傳的結果將會被放在 jsonTransporter.jsonObj 物件中。這個物件包含兩項基本的屬性 code 和 message。 code 碼若為 0，表示 API 呼叫成功，執行的結果將以 JSON 格式放在 message 中。 code 碼若不為零，表示 API 在執行過程中發生錯誤，錯誤訊息將以字串的方式存放在 message 中。
- 範例程式：[點我](https://docusky.digital.ntu.edu.tw/DocuSky/documentation/docs/widget.manageDataFileListSimpleUI/simpleExample-jsonTransporter.html)
- **jsonTransporter.deleteDataFile(category, datapath, filename, callback)**
- 這個函式將嘗試從 DocuSky 刪除符合 category、datapath 條件下的 filename 資料檔，然後執行回呼函式 callback。
- **jsonTransporter.listCategoryDataFiles(category, datapath, callback)**
- 這個函式將嘗試從 DocuSky 取得符合 category 和 datapath 的所有資料檔名稱，然後執行回呼函式 callback。
- **jsonTransporter.retrieveJson(category, datapath, filename, callback)**
- 這個函式將嘗試從 DocuSky 取得符合 category 和 datapath，資料檔名稱為 filename 的資料，然後執行回呼函式 callback。 若 widget 執行成功，這份資料將以 JSON 格式存放在 jsonTransporter.jsonObj 的 message 屬性中。
- **jsonTransporter.storeJson(category, datapath, filename, jsonObj, callback)**
- 這個函式會先將 jsonObj 物件執行序列化 (serialization)，並將序列化之後的結果儲存在 DocuSky 中（以 category, datapath, filename 區隔不同的資料）。 回呼函式可檢視 jsonTransporter.jsonObj 的 code 屬性，若它的值為 0，表示 widget 執行成功。
:::
## docusky.ui.manageDbListSimpleUI.js
- 這個 widget 的功能是讓工具可以建構、列出與刪除資料庫。在目前的版本中， 它僅提供一個操作介面，列出使用者當前所擁有的資料庫。 工具引入 widget 後，全域的 manageDbListSimpleUI 物件將提供以下的方法 (methods)：
- **manageDbList(evt, successCallback)**
- 這個函式要求 widget 顯示出當前的資料庫與文獻集列表。evt 可傳入使用者所點選的滑鼠事件。 successCallback 這個參數可傳一個回呼函式，要求 widget 在取得使用者的資料庫列表後， 將控制權轉移到回呼函式；若沒有傳入 successCallback 參數， widget 會在瀏覽器上顯示使用者的資料庫列表，並讓使用者新增或刪除資料庫。
- 範例程式：[點我執行](https://docusky.digital.ntu.edu.tw/DocuSky/documentation/docs/widget.manageDbListSimpleUI/simpleExample-manageDbList.html)
- **uploadMultipart(url, data, callback)**
- 此函式可將 `data` 的字串，以 HTTP multipart/form-data 的方式 POST 到 `url` 所指定的網址。成功後，將控制權轉移到回呼函式。
- 以下的函式，則仍處於開發測試階段：
:::success
- hideWidget(bool)
- 這個函式的目的，是讓工具程式能夠隱藏 widget。
:::