Cognos Analytics カスタムビジュアライゼーション チュートリアル - visdef.xmlの説明

#カスタムビジュアライゼーション チュートリアル
Cognos Analyticsの「Custom Visualizations Developer Guide」には、簡単な散布図を開発するためのチュートリアルがあります。

**カスタム視覚化 - チュートリアル**
https://www.ibm.com/support/knowledgecenter/ja/SSEP7J_11.1.0/com.ibm.swg.ba.cognos.dg_custom_vis.doc/ca_customviz_lib_tutorialscatter0.html

このチュートリアルをやると、このような散布図が作成できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/4320d85c-1e78-8f9c-a997-6d91f790edec.png)

カスタムビジュアライゼーション開発で重要なファイルは、visdef.xmlとMain.tsファイルですが、今回は開発の開始からvisdef.xmlの編集までをチュートリアルの流れに沿ってご説明します。

#カスタム視覚化の新規作成
コマンドプロンプトを開き、カスタム視覚化を作成するために、以下のコマンドを実行します。

```html
> customvis create MyScatter
> cd MyScatter
> customvis start
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/9b705f4e-1204-e9c5-4ba4-bd0b41a5367a.png)

以下のフォルダとファイルが自動的に作成されます。
それぞれのファイルをご説明します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/38369be3-21fb-ce36-8c91-30239b388307.png)

**package.json**
カスタム視覚化のパッケージ情報を定義するファイル。
Cognos Analyticsに表示するカスタム視覚化の名前やアイコンを変更できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/bdba9012-759f-e63b-20b7-c2a0ad0c727b.png)

**vizdef.xml（初期状態のもの）**
視覚化の様々な情報（スロット、データ編成、プロパティーなど）を記述します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/65edd639-6674-e659-7570-fa6cc0fc13b1.png)

**externals.d.ts**
D3のような外部ライブラリー参照が必要な場合に追加するファイル。
※今回のチュートリアルではこのファイルは更新しません。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/3fc98e2c-806f-3eff-3ef5-6098e63d3cd9.png)

**customvis-lib.tgz**
視覚化開発で使用するAPIライブラリー。
視覚化クラス作成用の「RenderBase」という基本クラスが含まれます。

**renderer/Main.ts（初期状態のもの）**
カスタム視覚化開発時のメインの実装ファイル。
typescript ファイルとなります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/08a93fb0-bd27-5f44-615e-7b53b5575888.png)

**その他のファイル、フォルダー**
customvis start を実行するとさらにいくつかのファイルやフォルダが生成されます。
これは視覚化の実行に必要なビルド出力も含まれます。
クリーンな状態で再び開発を開始するには、customvis cleanを実行する必要があります。

#visdef.xmlの説明
チュートリアルのパート1を完了すると、visdef.xmlファイルは以下の記述になります。
以降で、個々の記載を説明します。

```html
<?xml version="1.0" encoding="UTF-8"?>
<visualizationDefinition version="3.1" xmlns="http://www.ibm.com/xmlns/prod/ba/vipr/vizBundle/vizdef.3">
    <slots>
        <slot name="categories" type="cat" optional="false" channel="color" />
        <slot name="xpos" type="cont" optional="false" />
        <slot name="ypos" type="cont" optional="false" />
    </slots>

    <dataSets>
        <dataSet>
            <ref slot="categories" />
            <ref slot="xpos" />
            <ref slot="ypos" />
        </dataSet>
    </dataSets>

    <properties>
        <palette name="color" slot="categories" />
    </properties>

    <capabilities>
        <decorations>
            <decoration name="selected" type="boolean" target="datapoint" />
            <decoration name="hasSelection" type="boolean" target="dataset" />
            <decoration name="highlighted" type="boolean" target="datapoint" />
        </decorations>
    </capabilities>
</visualizationDefinition>
```

**スロット**
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/b2d665a2-0f7f-51de-ca25-23f37e7fa224.png)

\<slots> ～ \</slots>には、視覚化内のデータを保持できる部分を定義します。
チュートリアルで作成する散布グラフの視覚化には3つのスロットがあります。
・カテゴリー型のタプル用のスロット1個 (type="cat")
・値用のスロット2個 (type="cont")

\<slots>に定義した順番で、視覚化開発画面に表示されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/b47a4797-0a96-01e3-fdbd-84fa7dd6eaf2.png)
スロットには name (内部参照用) および type (カテゴリー型または連続型) が必須となります。

optional 属性 ： そのスロットにデータのマッピングが無くても視覚化をレンダリングできるかを指定します。falseを指定するとスロットは必須項目となります。

channel 属性 ： スロットの凡例を表示することができます。channel に指定できる値は color および size のみです。
・color (カテゴリー型凡例) ： データ・セット内のタプルに対応するスウォッチのリストを表示します。 スウォッチごとに、色付きの形状とキャプションを設定できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/7ae81126-6ad6-13ce-6b4f-c3dd2d04fd00.png)
・size (連続型凡例) ： 連続型の凡例は、値の範囲を表示します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/77c6d538-bf72-4672-6b7f-068da580ecb8.png)

※チュートリアルでは使用しませんが、caption 属性を使用することもできます。
caption 属性 ： 視覚化開発画面上で表示する名前を指定することができます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/81a08408-989b-a0fd-6335-c5197b0a212d.png)

**データ・セット**
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/4101c633-d8ce-cd56-3f3c-9812162858ed.png)
\<datasets>～\</datasets>には、slotsで定義した項目に紐づけるデータを定義します。
現在、RenderBase ではデータ・セットは 1 つしかサポートされないので、VizDef.xml の典型的な DataSets エントリーは上記のようになります。
slots セクションで定義した各スロットをデータ・セットにリストする必要があります。

**プロパティー**
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/1d00ea14-3520-55eb-afb2-d0ea159f88c9.png)
\<properties>~\</properties>では、視覚化の一般的なプロパティーを定義します。
チュートリアルでは、categoriesへ凡例用にカラー・パレットというプロパティを1つ追加しています。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/ffc6fed9-972d-c74e-e5fa-2ca2f3f39743.png)

**選択機能と強調表示機能**
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/04c33603-2308-ee9d-1b69-d6691d11c78b.png)
\<capabilities>~\</capabilities>でデータ要素の選択状態や強調表示状態を示します。
強調表示や選択に対応できる視覚化にするには、上記のセクションを指定する必要があります。
チュートリアルの記載方法で、標準装備のサポートを利用することが可能となります。
name 属性で指定する名称は、DataSetクラス、DataPointクラスのAccessors「selected、highlighted、hasSelecton」が使用できます。
datapoint.selected ：散布図のプロットをクリックした状態
datapoint.highlightted ：散布図のプロットにカーソルを合わせた状態
dataset.hasSelection ：散布図のレジェンドのアイテムを選択した状態

vizdef.xml ファイルを保存すると視覚化のソースのビルドが行われます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147246/ba69c012-6b9e-857f-4d9e-4d95d20ce415.png)

visdef.xmlの説明は以上です。
次回は、カスタム視覚化開発のメインとなる、Main.tsの開発について説明します。

#目次
**Cognos Analytics カスタムビジュアライゼーション機能の紹介**
https://qiita.com/shinyama/items/0adde0d1665a4e385faa