ブログ

ozawa · ‎05-07-2019

通常、Alteryxで作成したマクロはインターフェースデザイナーでレイアウトを決めます。

インターフェースデザイナーでは、設置されたインターフェースツールに基づいて項目が自動生成されるほか、項目のグループ化やタブの作成が行えます。
しかし、UIとしての見た目の変更は柔軟には行えません。
また、設定画面自体に何らかの動作をさせることはできません。

これは例えば、Google Sheetsツールで実現しているような

設定画面で認証を行う
認証後画面が遷移して一覧から読み込むスプレッドシートを選択

のような設定画面はこの機能のみでは実現できないことを意味します。
こういった仕組みを実現するには設定画面をHTMLを使って構築し、JavaScriptによって内部処理を行う必要があります。

HTML GUIを作成するために必要なファイル

通常のマクロであれば、yxmcファイルのみで完結していました。
HTML GUIを利用する場合はAlteryxで作成したyxmcファイルに加えていくつかのファイルが必要になります。

マクロ本体のyxmcファイル
インターフェースを定義したHTMLファイル
マクロのアイコンとなる画像ファイル
それらを紐づける設定ファイル

これら4つのファイルは必須となります。
また、インターフェースをHTMLで記述するため、CSSやJSファイルなどを別に持つ場合はそれらも用意することになります。

これら4つのファイルの作り方を順に確認していきます。

マクロ本体のyxmcファイル

マクロ本体は通常と同じように作成します。
「マクロを使って自作ツールを作成する」で作成したマクロをHTML GUI化してみます。

ワークフローの内容は同じです。

HTML GUIを使ったマクロを作成する際に重要な要素として、必ずNameの値を入れる必要があります。
設定の方法は、ツールの設定右側にあるメニューからAnnotationを選択して、Nameのところに適当な名前を入れます。

また、Macro Input/Macro OutputではInput Name/Output Nameを値も適切に設定してください。

インターフェースを定義したHTMLファイル

設定画面をHTML GUIを使って実現するためのHTMLファイルとなります。
GUIは通常のHTMLを使って記述可能ですが、Alteryxのインターフェースに対応する設定のみ独自のタグで記述します。

今回のインターフェース用HTML GUI全体は以下のようになります。

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>Simple Macro</title>
    <script type="text/javascript">
      document.write('<link rel="import" href="' + window.Alteryx.LibDir + '2/lib/includes.html">')
    </script>
  </head>
  <body>
    <h2>XMSG("Sort Field")</h2>
    <ayx
      data-ui-props="{type : 'TextBox', widgetId: 'sort_field'}"
      data-item-props="{dataName : 'sort_field', dataType : 'SimpleString'}">
    </ayx>
  </body>
</html>

まずは、Alteryxで利用するために必要なライブラリの読み込みを行います。この部分は定型文として常にそのまま利用できます。

<script type="text/javascript">
  document.write('<link rel="import" href="' + window.Alteryx.LibDir + '2/lib/includes.html">')
</script>

続いて、インターフェース用の要素を配置します。
これにはayxタグを利用します。
ayxタグの属性としてdata-ui-propsとdata-item-propsを指定します。

<ayx
  data-ui-props="{type : 'TextBox', widgetId: 'sort_field'}"
  data-item-props="{dataName : 'sort_field', dataType : 'SimpleString'}">
</ayx>

data-ui-propsは表示に関する設定で以下の2項目をJSON形式で設定します。

項目	内容
type	どのようなパーツを利用するか
widgetId	全てのインターフェースに対応するayxで一意となる値

typeはマクロのインターフェースがText Boxツールとなっているため、それに対応するTextBoxを指定しています。
ドロップダウンやチェックボックスなどのインタフェースとして表示するパーツにあわせてこの部分を指定することになります。

data-item-propsはHTML GUIからマクロに設定された値を渡すための設定項目になります。

項目	内容
dataName	マクロで設定したインターフェースのName属性
dataType	どのようなものを入力として受け付けるか

dataNameで指定した値を使ってこのayxタグの要素がマクロ上のどのインターフェースの設定値に対応しているかを定義しています。

マクロのアイコンとなる画像ファイル

HTML GUIを使ったマクロでは、インターフェースデザイナーで設定したアイコンは利用されません。
変わりに別途アイコン画像となるファイルを用意する必要があります。

これはpngファイルなどを単純に用意しておくのみです。

それらを紐づける設定ファイル

最後に必要となるのはマクロのyxmcファイル、HTML GUIのhtmlファイル、アイコンのpngファイルの対応関係を定義する設定ファイルです。

設定ファイル全体像は以下のようになっています。

<?xml version="1.0"?>
<AlteryxJavaScriptPlugin>
  <EngineSettings EngineDllEntryPoint="Supporting_Macros\simple_macro.yxmc" EngineDll="Macro" SDKVersion="10.1"/>
  <Properties>
    <MetaInfo>
      <Name>Simple Test</Name>
      <Description><![CDATA[This is simple macro.]]></Description>
      <ToolVersion>1</ToolVersion>
      <CategoryName>Sample Macros</CategoryName>
      <Author>Yuya Ozawa</Author>
    </MetaInfo>
  </Properties>
  <GuiSettings Help="" Html="SimpleMacroGui.html" Icon="SimpleMacro.png" SDKVersion="10.1">
    <InputConnections>
      <Connection Name="Input1" AllowMultiple="False" Optional="False" Type="Connection"/>
    </InputConnections>
    <OutputConnections>
      <Connection Name="Output1" Type="Connection"/>
    </OutputConnections>
  </GuiSettings>
</AlteryxJavaScriptPlugin>

設定ファイルはどこにどのファイルがあるかの記述となるので、ここまでで作成したファイルのディレクトリ構造も確認しておきます。

SimpleMacro
    │  SimpleMacro.png
    │  SimpleMacroConfig.xml
    │  SimpleMacroGui.html
    │
    └─Supporting_Macros
            simple_macro.yxmc

作成したマクロは Supporting_Macros以下、それ以外は直下に置いています。

この配置は必須ではありませんが慣習的にこのような配置としています。
必須となる部分として、設定ファイルを作成する際のファイル名として<ディレクトリ名>Config.xmlという名前にしてやる必要があります。
この命名に従っていない場合はツールとして認識されません。

設定ファイルはいつかのパーツで構成されています。
まずは、実体となるマクロがどこにあるのかを指定します。

<EngineSettings
  EngineDllEntryPoint="Supporting_Macros\simple_macro.yxmc" EngineDll="Macro"
  SDKVersion="10.1"/>

EngineDllEntryPoint属性でマクロのファイルを指定しています。
パスは設定ファイルからの相対パスで指定しています。
それ以外の2つの要素は固定値と考えて問題ありません。
マクロ以外の方法でツールを作成するときに設定が必要になるものとなります。

続いてのPropertiesでは、このマクロに関する設定を行います。

<Properties>
  <MetaInfo>
    <Name>Simple Test</Name>
    <Description><![CDATA[This is simple macro.]]></Description>
    <ToolVersion>1</ToolVersion>
    <CategoryName>Sample Macros</CategoryName>
    <Author>Yuya Ozawa</Author>
  </MetaInfo>
</Properties>

それぞれの設定内容は以下のようになります。

Name : Alteryx Designer上に表示されるこのマクロの名前
Description : ツールリストで選択した際にポップアップで表示される説明分
ToolVersion : バージョン番号(任意の値を設定)
CategoryName : ツールリストでどのカテゴリに配置するか
Author : 作成者(任意の値を設定)

3つ目の要素はHTML GUIとの結び付けに関する設定となります。

<GuiSettings Help="" Html="SimpleMacroGui.html" Icon="SimpleMacro.png" SDKVersion="10.1">
  <InputConnections>
    <Connection Name="Input1" AllowMultiple="False" Optional="False" Type="Connection"/>
  </InputConnections>
  <OutputConnections>
    <Connection Name="Output1" Type="Connection"/>
  </OutputConnections>
</GuiSettings>

GuiSettingsタグのHtml属性で先ほど作成したhtmlファイル、Icon属性でツールのアイコン画像のファイルを指定します。

内部では、入力・出力ののコネクションに関する設定を行います。これは、マクロ内に含まれるMacro Input/Macro Outputツール1つ1つに対して1要素を定義します。
Name属性には、それぞれツールのInput Name/Output Nameで設定した値と同じものを指定します。
AllowMultipleは1つのコネクションで複数の入力を受け付けるか(UnionつーるやJoin Multipleツールのような挙動)、Optionalはこの入力を任意(Dynamic RenameツールのRのような挙動)を行うかの設定になります。
これらの設定値は実際のツールの動きに合わせてTrue/Falseを指定してください。

ツールを利用する

最後にこのツールを利用する方法を紹介します。
yxmcファイル単一の場合、それさえ読み込めればよかったので表情に簡単でしたが、HTML GUIを利用する場合はどうすればいいのでしょうか？
これは特定の場所に作成したマクロを配置するという仕組みになっています。

%APPDATA%\Alteryx\Toolsというパスに先ほどの構成のSimpleMacroディレクトリをそのまま配置します。
エクスプローラのアドレスバーに%APPDATA%と入力すればあとは順に辿っていけます。
これでAlteryxから利用可能になったので、設定ファイルで指定したカテゴリのタブに表示されています。

より複雑なツールでのHTML GUIの作り方

Text Boxが1つのシンプルなツールを例にHTML GUIの作り方を紹介しましたが、通常はより複雑な処理を行うツールを作成することになるでしょう。

その際の参考情報をいくつか挙げておきます。

以下では入力データに基づいて選択肢の項目を決定する例を紹介しています。

AlteryxでHTML GUIを使ってマクロのインターフェースを作る

各設定でどのような値の指定が可能かなどは公式のドキュメントを参照するのが便利です。

HTML GUI SDK

ブログ

マクロの設定インターフェースをHTML GUIで作成する

HTML GUIを作成するために必要なファイル

マクロ本体のyxmcファイル

インターフェースを定義したHTMLファイル

マクロのアイコンとなる画像ファイル

それらを紐づける設定ファイル

ツールを利用する

より複雑なツールでのHTML GUIの作り方

データの形の変化でわかるAlteryx Data Preparation Cheat Sheet

Alteryx Academy が日本語でご利用できるようになりました!

Alteryxコミュニティ2019年9月リリース（v19.7）

マクロを使って自作ツールを作成する

ワークフロー開発を高速化させるTips