7.8.2 Creating a Custom Template

In the simplest case, a template consists of two files: a template file, which has a .tpl extension, and a special file info.xml. The info.xml file has important metadata about the template. A third file is optional, which is the preview image file. This preview file provides a thumbnail image illustrating the appearance of the generated report.

One of the easiest ways to create a custom template is to make a copy of any existing template.

For example, the following procedure describes how to make a custom template based on the Text Basic template.

  1. Navigate to the folder where the templates are stored. Assuming that MySQL Workbench has been installed into the default location on Windows, this would be C:\Program Files\MySQL\MySQL Workbench 5.0 SE\modules\data\wb_model_reporting.

  2. Copy the Text_Basic.tpl folder. The copy can be given any suitable name; for example, Custom_Basic.tpl.

  3. Edit the info.xml file to reflect your custom template. The unedited file in this case is shown here:

    <?xml version="1.0"?>
    <data>
      <value type="object" struct-name="workbench.model.reporting.TemplateInfo"
      id="{BD6879ED-814C-4CA3-A869-9864F83B88DF}" struct-checksum="0xb46b524d">
        <value type="string" key="description">
          A basic TEXT report listing schemata and objects.
        </value>
        <value type="string" key="name">HTML Basic Frame Report</value>
        <value type="list" content-type="object"
        content-struct-name="workbench.model.reporting.TemplateStyleInfo"
        key="styles">
          <value type="object" struct-name="workbench.model.reporting.TemplateStyleInfo"
          id="{7550655C-CD4B-4EB1-8FAB-AAEE49B2261E}" struct-checksum="0xab08451b">
            <value type="string" key="description">
              Designed to be viewed with a fixed sized font.
            </value>
            <value type="string" key="name">Fixed Size Font</value>
            <value type="string" key="previewImageFileName">
              preview_basic.png
            </value>
            <value type="string" key="styleTagValue">fixed</value>
          </value>
        </value>
        <value type="string" key="mainFileName">report.txt</value>
      </value>
    </data>
    

    The file defines wwo objects: the TemplateInfo object and the TemplateStyleInfo object. These objects contain information about the template that will be displayed in the DBDoc Model Reporting wizard main page.

  4. Change the object GUIDs that are used in the file. In this example, there are two that need replacing:

    id="{BD6879ED-814C-4CA3-A869-9864F83B88DF}"
    ...
    id="{7550655C-CD4B-4EB1-8FAB-AAEE49B2261E}"
    

    Generate two new GUIDS. This can be done using any suitable command-line tool. There are also free online tools that can be used to generate GUIDs. Another way to generate GUIDs is by using the MySQL UUID() function:

    mysql> SELECT UUID();
    +--------------------------------------+
    | UUID()                               |
    +--------------------------------------+
    | 648f4240-7d7a-11e0-870b-89c43de3bd0a |
    +--------------------------------------+
    

    Once you have the new GUID values, edit the info.xml file accordingly.

  5. Edit the textual information for the TemplateInfo and TemplateStyleInfo objects to reflect the purpose of the custom template.

  6. The modified file will now look something like the following:

    <?xml version="1.0"?>
    <data>
      <value type="object" struct-name="workbench.model.reporting.TemplateInfo"
      id="{cac9ba3f-ee2a-49f0-b5f6-32580fab1640}" struct-checksum="0xb46b524d">
        <value type="string"
        key="description">
          Custom basic TEXT report listing schemata and objects.
        </value>
        <value type="string" key="name">Custom Basic text report</value>
        <value type="list" content-type="object"
        content-struct-name="workbench.model.reporting.TemplateStyleInfo" key="styles">
          <value type="object"
          struct-name="workbench.model.reporting.TemplateStyleInfo"
          id="{39e3b767-a832-4016-8753-b4cb93aa2dd6}" struct-checksum="0xab08451b">
            <value type="string" key="description">
              Designed to be viewed with a fixed sized font.
            </value>
            <value type="string" key="name">Fixed Size Font</value>
            <value type="string" key="previewImageFileName">preview_basic.png</value>
            <value type="string" key="styleTagValue">fixed</value>
          </value>
        </value>
        <value type="string" key="mainFileName">custom_report.txt</value>
      </value>
    </data>
    
  7. Create the new template file. This too may best be achieved, depending on your requirements, by editing an existing template. In this example the template file report.txt.tpl is shown here:

    +--------------------------------------------+
    | MySQL Workbench Report                     |
    +--------------------------------------------+
    
    Total number of Schemata: {{SCHEMA_COUNT}}
    =============================================
    {{#SCHEMATA}}
    {{SCHEMA_NR}}. Schema: {{SCHEMA_NAME}}
    ----------------------------------------------
    ## Tables ({{TABLE_COUNT}}) ##
    {{#TABLES}}{{TABLE_NR_FMT}}. Table: {{TABLE_NAME}}
    {{#COLUMNS_LISTING}}## Columns ##
    Key  Column  Name  Datatype  Not Null  Default  Comment
    {{#COLUMNS}}{{COLUMN_KEY}}{{COLUMN_NAME}}{{COLUMN_DATATYPE}} »
    {{COLUMN_NOTNULL}}{{COLUMN_DEFAULTVALUE}}{{COLUMN_COMMENT}}
    {{/COLUMNS}}{{/COLUMNS_LISTING}}
    {{#INDICES_LISTING}}## Indices ##
    Index  Name  Columns  Primary  Unique  Type  Kind  Comment
    {{#INDICES}}{{INDEX_NAME}}{{#INDICES_COLUMNS}}{{INDEX_COLUMN_NAME}} »
    {{INDEX_COLUMN_ORDER}}{{INDEX_COLUMN_COMMENT}}{{/INDICES_COLUMNS}} »
    {{INDEX_PRIMARY}}{{INDEX_UNIQUE}}{{INDEX_TYPE}}{{INDEX_KIND}}{{INDEX_COMMENT}}
    {{/INDICES}}{{/INDICES_LISTING}}
    {{#REL_LISTING}}## Relationships ##
    Relationship  Name  Relationship  Type  Parent Table  Child Table Cardinality
    {{#REL}}{{REL_NAME}}{{REL_TYPE}}{{REL_PARENTTABLE}}{{REL_CHILDTABLE}}{{REL_CARD}}
    {{/REL}}{{/REL_LISTING}}
    ---------------------------------------------
    
    {{/TABLES}}
    {{/SCHEMATA}}
    =============================================
    End of MySQL Workbench Report
    

    This template shows details for all schemata in the model.

  8. The preceding template file can be edited in any way you like, with new markers being added, and existing markers being removed as required. For the custom template example, you might want to create a much simpler template, such as the one following:

    +--------------------------------------------+
    | MySQL Workbench Custom Report              |
    +--------------------------------------------+
    
    Total number of Schemata: {{SCHEMA_COUNT}}
    =============================================
    {{#SCHEMATA}}
    Schema Name: {{SCHEMA_NAME}}
    ----------------------------------------------
    ## Tables ({{TABLE_COUNT}}) ##
    
    {{#TABLES}}
    Table Name: {{TABLE_NAME}}
    {{/TABLES}}
    {{/SCHEMATA}}
    
    Report Generated On: {{GENERATED}}
    =============================================
    End of MySQL Workbench Custom Report
    

    This simplified report just lists the schemata and the tables in a model. The date and time the report was generated is also displayed as a result of the use of the {{GENERATED}} variable.

  9. The custom template can then be tested. Start MySQL Workbench, load the model to generate the report for, select the Model, DBDOC - Model Reporting menu item. Then select the new custom template from the list of available templates, select an output directory, and click Finish to generate the report. Finally, navigate to the output directory to view the finished report.