コンポーネント/マッパー関数ヘルプ書式ガイド

  1. ヘルプファイルについて
  2. ヘルプの枠組み
    1. デザイナーからのヘルプの参照
    2. jarファイルからのヘルプの抽出
      1. 日本語以外のヘルプファイルの配置について
    3. 変換によるヘルプファイルの生成
  3. ヘルプ原稿の書式
    1. 名前空間
    2. コンポーネントヘルプの要素構造
    3. マッパー関数ヘルプの要素構造
    4. Component/Function要素
    5. Streams要素
    6. (コンポーネントヘルプの)Input要素
    7. (コンポーネントヘルプの)Output要素
    8. Properties要素
    9. Property要素
    10. Loop要素
    11. Transaction要素
    12. Exception要素
    13. Topic/Guide要素
    14. (マッパー関数の)Input要素
    15. (マッパー関数の)Output要素
    16. Descriptionの書き方
    17. Descriptionで使える置換要素
      1. PropertyName要素
      2. PropertyValue要素
      3. CategoryName要素
  4. ヘルプに関連するANTタスク
    1. helpconvert
    2. helpgen
    3. helpcopy

1 ヘルプファイルについて

コンポーネント/マッパー関数ではデザイナーの右クリックメニュー「ヘルプ」からHTML形式のヘルプを参照することができます。
このHTMLはXML形式のヘルプ原稿を変換することで生成されます。
ここではそのヘルプ原稿の書式について説明します。

2 ヘルプの枠組み

2.1 デザイナーからのヘルプの参照

デザイナー上でコンポーネント(マッパー関数)の右クリックメニューからヘルプを実行した場合は規定のフォルダからそのコンポーネント(マッパー関数)に 関連付けられたHTMLファイルを検索し、ブラウザで表示されます。
その際に検索されるフォルダとファイル名は以下のようになります。

種別 フォルダ ファイル名
コンポーネント DESIGNER_HOME/docs/reference/component <コンポーネント名>_<ロケール>.html
マッパー関数 DESIGNER_HOME/docs/reference/function <マッパー関数名>_<ロケール>.html

コンポーネント名はコンポーネント定義ファイルで「Component/@name」に定義された名前です。
マッパー関数名はマッパー関数定義ファイルで「Function/@name」に定義された名前です。
ロケールはデザイナーがインストールされたマシンのロケールで日本語環境では「jp」となります。

2.2 jarファイルからのヘルプの抽出

コンポーネント(マッパー関数)はjarファイルで配布されます。
jarファイルを「DESIGNER_HOME/lib/flowlib」に置くことで新たに追加したコンポーネント(マッパー関数)がデザイナーにインストールされます。

この時にjarファイル内からヘルプ関連のファイルが抽出され上記フォルダにコピーされます。
抽出対象のファイルは以下のようになります。

種別 jarファイル内でのパス ファイル種別
コンポーネント META-INF/asteria/<ロケール>/reference/compoent すべてのファイル
マッパー関数 META-INF/asteria/<ロケール>/reference/function すべてのファイル

ロケールはデザイナーがインストールされたマシンのロケールです。 つまり作成したコンポーネント(マッパー関数)が日本語環境で使用されることを想定している場合は「META-INF/asteria/jp」以下にヘルプのHTMLファイルと関連するイメージファイルを配置します。

2.2.1 日本語以外のヘルプファイルの配置について

ヘルプファイルの枠組みは多言語に対応できるように設計されていますが、実際には現在は日本語(ロケール「jp」)と英語(ロケール「en」)以外の言語のヘルプは表示することができません。
(日本語以外の環境では英語版のヘルプ「<コンポーネント名(マッパー関数名)>_en.html」というファイルが使用されます。)
英語版のヘルプファイルを配置する場合はロケールを外した以下の場所に配置してください。

種別 jarファイル内でのパス ファイル種別
コンポーネント META-INF/asteria/reference/compoent すべてのファイル
マッパー関数 META-INF/asteria/reference/function すべてのファイル

※これ以降で説明するヘルプ原稿の変換ツールは日本語環境専用です。

2.3 変換によるヘルプファイルの生成

ヘルプファイルの枠組みを考えた場合、HTMLファイルを直接作成してjarファイルの規定の場所に配置するという方法を取ることもできますが、この方法には次の2つの欠点があります。

これらの問題を回避するためにヘルプ作成では次のような手順で行われます。


ヘルプ原稿のxmlと定義ファイルをマージすることによって定義ファイルから必要な情報を取得した中間ファイルを生成し、それに対してxsl変換を行うことでスタイルの統一されたHTMLを生成します。
SDKによって生成されるANTのビルドファイルにはこれらの手順を自動化するタスクがあらかじめ定義されています。

3 ヘルプ原稿の書式

3.1 名前空間

ヘルプ原稿の要素はすべて上記の名前空間に属します。
ヘルプ原稿内では別の名前空間に属する要素(主にHTML)を自由に使用することができます。

3.2 コンポーネントヘルプの要素構造

コンポーネントヘルプ原稿の要素構造は以下のようになります。

要素名 出現回数 Description
Component 1
   Streams 1
      Input 0..*
         Variable 0..*
      Output 0..*
         Variable 0..*
   Properties 1
      Property 0..*
         Value 0..*
   Loop 0..1
   Transaction 0..1
      Commit 0..1
      Rollback 0..1
   Exception 0..*
      Case 1..*
      Param 0..1
      Stream 0..1
   Topic 0..*
   Guide 0..*

表のDescription列はそれぞれの要素に対する説明を記述できるかどうかを示しています。
Descriptionの記述方法については後述します。

3.3 マッパー関数ヘルプの要素構造

マッパー関数ヘルプ原稿の要素構造は以下のようになります。

要素名 出現回数 Description
Function 1
   Input 1
      Value 0..*
   Output 1
      Value 1..*
   Properties 1
      Property 0..*
         Value 0..*
   Exception 0..*
      Case 1..*
   Topic 0..*
   Guide 0..*

コンポーネントヘルプとマッパー関数ヘルプでは多くの要素が共通していますが、 Input要素やOutput要素など一部の要素では定義方法が異なるので注意が必要です。
以下にそれぞれの要素の定義方法と意味を説明して行きます。

3.4 Component/Function要素

コンポーネントヘルプまたはマッパー関数ヘルプの文書要素です。

Component/Function要素の属性
名前 区分 説明
name 必須 コンポーネント(マッパー関数)名
定義ファイルのComponent要素またはFunction要素のname属性と同じでなければなりません。
title コンポーネント(マッパー関数)の簡潔な説明を書きます。
コンポーネント(マッパー関数)の表示名とこのtitleがヘルプの大見出しになります。

Descriptionにはコンポーネント(マッパー関数)の概要を書きます。
表示名(displayName)やアイコンファイル名(icon)は定義ファイルからマージするので記述する必要はありません。

3.5 Streams要素

コンポーネントのストリーム情報のプレースホルダです。

3.6 (コンポーネントヘルプの)Input要素

入力ストリームの情報です。
サブコネクタを持つコンポーネントの場合は複数定義します。

Input要素の属性
名前 区分 説明
type 必須 受け入れ可能なストリーム型を「,」あるいは「|」区切りで記述します。
count 必須 受け入れ可能なストリーム数を記述します。
無制限にストリームを受け入れる場合は「unbounded」とします。

Descriptionには入力ストリームがどのように使用されるかを記述します。
入力ストリームを使用しないコンポーネントの場合は省略しても構いません。

コンポーネントが入力ストリームに設定されたストリーム変数を使用する場合は 子要素としてVariable要素を定義し使用するストリーム変数に対する説明をDescriptionに記述します。
Variable要素は複数定義することができます。

Variable要素の属性
名前 区分 説明
name 必須 ストリーム変数名
type 必須 データ型

3.7 (コンポーネントヘルプの)Output要素

出力ストリームの情報です。
サブコネクタや分岐のあるコンポーネントの場合は複数定義します。

Output要素の属性
名前 区分 説明
type 必須 出力可能なストリーム型を「,」あるいは「|」区切りで記述します。
name 複数の出力コネクタを持つコンポーネントの場合は出力コネクタに対応する名前を記述します。
出力コネクタが一つしかないコンポーネントの場合は省略して構いません。

Descriptionにはどのようなストリームが出力されるのかを記述します。
入力をそのまま出力するだけのコンポーネントの場合は属性定義で「description="filter"」とすることで キーワードファイルの説明を参照することができます。

コンポーネントが出力ストリームにストリーム変数を付加する場合は 子要素としてVariable要素を定義し付加するストリーム変数に対する説明をDescriptionに記述します。
Variable要素は複数定義することができ、その定義方法はInput要素で行う場合と同じです。

3.8 Properties要素

コンポーネント(マッパー関数)のプロパティ情報のプレースホルダです。

3.9 Property要素

プロパティの情報です。
プロパティの数だけ定義します。

Property要素の属性
名前 区分 説明
name 必須 プロパティ名
定義ファイルのProperty要素またはCategory要素のname属性と同じでなければなりません。

Descriptionにはプロパティの概要を記述します。
表示名(displayName)やプロパティ型(type)、マッピング(mapping)は定義ファイルからマージするので記述する必要はありません。

プロパティがboolean型やchoice型など選択肢を持つ場合には 子要素としてValue要素を定義しそのDescriptionに選択肢に対する説明を記述することができます。
Value要素は複数定義することができます。

Value要素の属性
名前 区分 説明
name 必須 選択肢の値
定義ファイルでChoiceItemとして定義された値と同じでなければなりません。

選択肢の表示名は定義ファイルからマージするので記述する必要はありません。

3.10 Loop要素

コンポーネントがループの起点となる場合にその情報を記述します。
ループがない場合は省略して構いません。

3.11 Transaction要素

コンポーネントがトランザクションをサポートする場合にその情報を記述します。
コミット時の処理とロールバック時の処理をそれぞれCommit要素とRollback要素に分けて記述します。
コミット時にのみ何かしらの処理を行いロールバック時には何も行わない場合はRollback要素は省略して構いません。

3.12 Exception要素

発生しうるエラーについての情報を記述します。
エラー情報はケース毎にCase要素に分けて記述します。

Exception要素は対応するエラー処理プロパティごとに複数記述でき、 ひとつのException要素内に複数のCase要素を記述することもできます。

Exception要素の属性
名前 区分 説明
name 対応するエラー処理プロパティの名前
対応するエラー処理プロパティが「Exception」(汎用)の場合は省略して構いません。

エラー処理プロパティの表示名(displayName)は定義ファイルからマージするので記述する必要はありません。

Case要素の属性
名前 区分 説明
code 発生するエラーにエラーコードが振られている場合はそのコードを記述します。

エラー発生時にパラメータ(エラー処理フロー内でシステム変数から参照できる)が設定される場合は Exception要素の子要素としてParam要素を定義しパラメータに関する情報をそのDescriptionに記述します。
Param要素は複数定義することができます。

Param要素の属性
名前 区分 説明
index 必須 システム変数ExceptionParamでのインデックス
name 必須 システム変数ExceptionParamでの名前

エラー発生時にエラー処理用のストリームを生成するコンポーネントの場合は Exception要素の子要素としてStream要素を定義しエラー処理用のストリームに関する情報をそのDescriptionに記述します。
エラー処理用のストリームを生成しない場合はコンポーネントの入力ストリームがそのまま出力されるので、 この場合はStream要素は不要です。

3.13 Topic/Guide要素

コンポーネント(マッパー関数)に関してさらに詳細な説明を加えたい場合にはTopicまたはGuide要素の下に 任意のHTMLを記述することができます。

TopicとGuideは若干スタイルが異なるだけで定義方法自体は同じです。
TopicとGuideの使い分けについて明確な規定はありませんが、Topicは「注釈」、Guideは「説明」というような意味合いです。
例えばRDBGetコンポーネントのSQLBuilderのような専用UIがある場合にはGuideにその使用方法の説明を加えます。
Topic、Guideともに複数定義することができます。

Topic/Guide要素の属性
名前 区分 説明
title 必須 見出しを記述します。
id 見出しに対してidを設定します。
ヘルプ内でハイパーリンクしたい場合には設定してください。

3.14 (マッパー関数の)Input要素

マッパー関数の入力に関する情報です。

Input要素の属性
名前 区分 説明
min 必須 マッパー関数の動作に最低限必要な入力数
max 必須 マッパー関数に入力できる最大数
無制限に入力をとることができる場合は「N」とします。

Input要素では入力毎に子要素としてValue要素を定義しDescriptionを記述します。
Constのように入力を持たないマッパー関数の場合はValue要素は省略して構いません。
Concatenateのように無制限に入力をとるマッパー関数の場合はValue要素はひとつ定義すれば構いません。

Value要素の属性
名前 区分 説明
type 必須 データ型
property 入力がマッパー関数のプロパティ値を置き換える場合にそのプロパティ名を記述します
property属性が定義された場合はDescriptionは必要ありません。

3.15 (マッパー関数の)Output要素

マッパー関数の出力に関する情報です。
出力毎に子要素としてValue要素を定義しそこにDescriptionを記述します。
Value要素の定義方法はInput要素の場合と同じですがproperty属性は使用できません。

3.16 Descriptionの書き方

Descriptionは対象とする概念に対して説明を加えるための書式です。
ある要素に対してDescriptionを記述する方法には次の3つがあります。

  1. Description要素を定義しその下にHTMLで説明を記述する
  2. Description要素を省略しその下にHTMLで説明を記述する
  3. description属性を用いてキーワードファイルを参照する

正確には2は1の略記法です。
原則的には説明はDescription要素の下に書きますが、その要素に他に子要素がない場合は Description要素を省略することができます。

例えばProperty要素は選択肢の説明としてValue要素を持つことがあり、 その場合はDescription要素を省略することはできませんが、 それ以外の場合はDescription要素を省略してProperty要素直下に説明を書くことができます。
(もちろん省略せずにDescription要素を定義しても構いません。)


<h:Property name="Prop1">
	Prop1に対する説明<br/>
	説明では<b>自由に</b>HTMLを使用することができる
</h:Property>

<h:Property name="Prop2">
	<h:Description>
		Prop2に対する説明<br/>
		他に子要素がある場合はDescriptionは省略不可
	</h:Description>
	<h:Value name="true">値の説明</h:Value>
	<h:Value name="false">
		<h:Description>省略せずにDescriptionを定義しても良い</h:Description>
	</h:Value>
</Property>

Description要素に直接説明を書く替わりにキーワードファイルを参照してそこから 説明文を引っ張ってくることもできます。
その場合はdescription属性に参照するキーワードの名前を指定します。


<!-- キーワードファイルから「filter」という名前の説明文を取得してDescriptionとします。-->
<h:Output type="ALL" description="filter"/>

キーワードファイルは「DESIGNER_HOME/conf/sdk/keywords.xml」です。
キーワードファイルの書式はroot要素の下にkeyword要素が羅列されているだけで、 keyword要素の下には任意のHTMLを記述することができます。

標準では以下のキーワードが登録されています。

キーワード名 内容 使用箇所
ignore 入力ストリームは使用せず、すべて無視します。 入力ストリームを使用しないコンポーネントのInput要素
filter 入力ストリームをそのまま出力します。 入力をそのまま出力するコンポーネントのOutput要素
notLoop なし。 ループしないコンポーネントのLoop要素
(Loop要素自体を省略しても良いので通常は使用しない)
connection FSMCで設定するコネクション情報。 コネクションプロパティ

3.17 Descriptionで使える置換要素

プロパティ名や選択肢など、定義ファイル上では実名と表示名が別に定義されているものが多数あります。
Description内ではそれらの実名を特別な要素で括ることで表示名と置き換えることができます。

また置換された単語にはスタイルが適用されるので文章中でその単語は強調されます。
例えばPropertyName要素でプロパティ名を置換した場合その置換文字列はspanで括られ「propertyName」 というclassが与えられます。


<h:PropertyName>Property1</h:PropertyName>

↓ 置換

<span class="propertyName">プロパティ1</span>

3.17.1 PropertyName要素

PropertyName要素でプロパティ名を括るとその表示名に置換されます。
PropertyName要素には属性はありません。

3.17.2 PropertyValue要素

PropertyValue要素でプロパティの選択肢の値を括るとその表示名に置換されます。

PropertyValue要素の属性
名前 区分 説明
property 必須 その選択肢のホルダであるプロパティ名

3.17.3 CategoryName要素

CategoryName要素でCategoryPropertyの列名を括るとその表示名に置換されます。

CategoryName要素の属性
名前 区分 説明
property 必須 その選択肢のホルダであるCategoryProperty名

4 ヘルプに関連するANTタスク

ツールガイドで説明しているJavaInterpreterのウィザードから 生成されるbuild.xmlにはいくつかヘルプ生成に関するタスクが含まれています。
以下にヘルプに関連するタスクについて説明します。
(これらのタスクは日本語環境に特化しています。)

4.1 helpconvert

ヘルプの原稿からHTMLを生成するタスクです。(マージとXSL変換の両方を行います。)
ヘルプ原稿の置き場所と生成されるHTMLの出力先は以下になります。

コンポーネントヘルプ原稿 BUILD_HOME/doc/reference/component
マッパー関数ヘルプ原稿 BUILD_HOME/doc/reference/function
コンポーネントHTML生成先 BUILD_HOME/doc/refhtmls/component
マッパー関数HTML生成先 BUILD_HOME/doc/refhtmls/function

ヘルプ原稿のファイル名は次の二つのうちのいずれかでなければなりません。

イメージを使用する場合はヘルプ原稿と同じフォルダに置いてください。
生成されるHTMLと同じフォルダにコピーされます。
(下位にフォルダを作成してそこにイメージを配置することはできません。)

4.2 helpgen

定義ファイルからヘルプ原稿の雛型を生成するタスクです。
ウィザードでは最初に一度だけこのタスクが実行され、ヘルプ原稿がそれぞれの置き場所に生成されます。

4.3 helpcopy

ヘルプHTMLの生成先からjarファイルの所定の位置にヘルプをコピーするタスクです。