MySQL :: MySQL Workbench 手冊 :: 9.7 自訂 DBDoc 模型報表範本

MySQL Workbench 手冊 / 資料庫設計和建模 / 自訂 DBDoc 模型報表範本

9.7 自訂 DBDoc 模型報表範本

9.7.1 支援的範本標記
9.7.2 建立自訂範本

本節概述如何建立和修改 MySQL Workbench 使用的 DBDoc 模型報表範本。

MySQL Workbench DBDoc 模型報表系統基於 Google 範本系統。本討論不嘗試詳細解釋 Google 範本系統。如需了解 Google 範本系統如何運作的實用概述，請參閱 Google 文件：如何使用 Google 範本系統。

DBDoc 模型報表系統使用的範本是包含標記的文字檔案。這些文字檔案由內建於 MySQL Workbench 的範本系統處理，並將標記替換為實際資料。然後產生輸出檔案。使用者檢視的正是這些輸出檔案，通常是 HTML 或文字。

標記可以是下列任何一種類型

範本包含
註解
設定分隔符號
編譯指示
變數
區段開始和區段結束

最後兩種是 MySQL Workbench 範本中最常用的，這些重要的標記將在以下章節中簡要說明。

變數

範本檔案中由標記表示的變數，會在產生輸出檔案之前被其對應的資料取代。變數與其對應資料之間的映射關係由 MySQL Workbench 儲存在資料字典中。在資料字典中，變數名稱是索引鍵，而變數的對應資料是值。MySQL Workbench 會建置資料字典，並以處理過的模型中包含的資料填入。

舉例來說，以下程式碼片段顯示範本檔案的一部分
```
Total number of Schemas: {{SCHEMA_COUNT}}
```
在產生的輸出檔案中，變數 {{SCHEMA_COUNT}} 會被模型中的綱要數量取代
```
Total number of Schemas: 2
```
變數可以在範本檔案中出現多次。
區段

區段用於在範本中執行迭代。當 MySQL Workbench 將區段中的變數與資料交換時，它會迭代執行，使用資料字典中定義變數的所有資料。MySQL Workbench 會根據目前正在處理的模型建置資料字典。

請考慮以下程式碼片段
```
{{#SCHEMATA}}
Schema: {{SCHEMA_NAME}}
{{/SCHEMATA}}
```
在前面的程式碼片段中，區段的開始和結束由 {{#SCHEMATA}} 和 {{/SCHEMATA}} 標記表示。當 MySQL Workbench 處理範本時，它會記下區段並迭代它，直到對應資料字典中 {{SCHEMA_NAME}} 的變數資料耗盡為止。例如，如果正在處理的模型包含兩個綱要，則該區段的輸出可能類似如下
```
Schema: Airlines
Schema: Airports
```

資料字典

更詳細了解區段和資料字典之間的關係非常重要。在資料字典中，變數的索引鍵是變數名稱，即標記。變數的值是變數的資料。資料字典中區段的條目有所不同。對於資料字典中的區段條目，索引鍵是區段名稱，即標記。但是，與索引鍵關聯的值是資料字典的清單。在 MySQL Workbench 中，每個區段通常與資料字典關聯。您可以將區段視為啟動其關聯的字典（或字典）。

處理範本時，資料字典會以階層模式載入，形成資料字典樹狀結構。下表說明了這一點。

表格 9.2 資料字典樹狀結構

資料字典	載入資料字典
主要	綱要
綱要	表格、欄位 (詳細資訊為 true)、外鍵 (詳細資訊為 true)、索引 (詳細資訊為 true)
表格	關聯清單、索引清單、欄位清單、表格註解清單、DDL 清單
欄位清單	欄位 (詳細資訊為 false)
關聯清單	關聯 (詳細資訊為 false)
索引清單	索引 (詳細資訊為 false)

樹狀結構的根是主要字典。其他字典會從根載入，以形成字典樹狀結構。

注意

如果範本沒有區段，則會在主要字典中查閱範本中使用的任何變數。如果在主要字典（可以視為與預設區段或主要區段關聯）中找不到變數，則不會在該標記的輸出檔案中產生資料。

變數評估

資料字典的樹狀結構對於變數評估非常重要。由於變數是在資料字典中定義的，因此只有在該特定資料字典處於作用中狀態時，其關聯值才有意義，也就是說，只有在與該資料字典關聯的區段處於作用中狀態時。當發生變數查閱時，系統會檢查與目前區段關聯的資料字典。如果可以在該處找到變數值，則會進行替換。但是，如果在目前的資料字典中找不到變數的值，則會檢查父資料字典的變數值，依此類推，直到到達主要資料字典或根。

假設我們要顯示模型中所有欄位的名稱。請考慮使用以下範本來嘗試實現此目的

Report
------
Column Name: {{COLUMN_NAME}}

此範本不會產生任何輸出，即使是包含一個或多個欄位的模型。在此範例中，唯一處於作用中的資料字典是主要字典。但是，COLUMN_NAME 儲存在 COLUMNS 資料字典中，該字典與 COLUMNS 區段關聯。

有了這些知識，可以對模板進行如下改進

Report
------
{{#COLUMNS}}
Column Name: {{COLUMN_NAME}}
{{/COLUMNS}}

這樣仍然不會產生輸出。若要了解原因，請參閱表格 9.2，「資料字典樹」。COLUMNS資料字典的父字典為COLUMNS_LISTING。COLUMNS_LISTING的父字典為TABLES，而TABLES的父字典為SCHEMATA，SCHEMATA的父字典則是主字典。請記住，若要讓字典參與變數查找，其關聯的區段必須處於啟用狀態。

若要達到所需的輸出，模板必須類似如下

Report
------

{{#SCHEMATA}}
{{#TABLES}}
{{#COLUMNS_LISTING}}
{{#COLUMNS}}
Column Name: {{COLUMN_NAME}}
{{/COLUMNS}}
{{/COLUMNS_LISTING}}
{{/TABLES}}
{{/SCHEMATA}}

以下模板相同，但增加了說明註解

Report
------

{{! Main dictionary active}}
{{#SCHEMATA}}  {{! SCHEMATA dictionary active}}
{{#TABLES}}  {{! TABLES dictionary active}}
{{#COLUMNS_LISTING}} {{! COLUMNS_LISTING dictionary active}}
{{#COLUMNS}}  {{! COLUMNS dictionary active}}
Column Name: {{COLUMN_NAME}} {{! COLUMN_NAME variable is looked-up,
and found, in COLUMNS data dictionary}}
{{/COLUMNS}}
{{/COLUMNS_LISTING}}
{{/TABLES}}
{{/SCHEMATA}}

現在假設您還希望為顯示的每個欄位名稱顯示其對應的綱要名稱，則模板會如下所示

Report
------

{{#SCHEMATA}}
{{#TABLES}}
{{#COLUMNS_LISTING}}
{{#COLUMNS}}
Schema Name: {{SCHEMA_NAME}} Column Name: {{COLUMN_NAME}}
{{/COLUMNS}}
{{/COLUMNS_LISTING}}
{{/TABLES}}
{{/SCHEMATA}}

當執行SCHEMA_NAME的變數查找時，會檢查COLUMNS字典。由於該變數在那裡找不到，因此會檢查父字典COLUMNS_LISTING，依此類推，直到最終在SCHEMATA字典中找到該變數的位置。

如果模型中有多個綱要，則會針對相符的次數重複外部區段，並且SCHEMA_NAME在每次重複時都會有正確的值。

務必始終考慮哪個字典必須處於啟用狀態（以及哪些父字典），才能正確評估變數。以下章節有一個表格，可協助您識別區段需求。