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

  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ファイルがブラウザで表示されます。
デザイナーがサーバー接続されていない場合はインターネット上にある製品サイトのヘルプが表示されます。
ただし、標準コンポーネント/マッパー関数以外のカスタムコンポーネント/マッパー関数のヘルプはインターネット上には存在しないのでそれらのヘルプはサーバー接続時にしか表示できません。

ヘルプのURLは以下になります。

種別URL
コンポーネントhttp://<サーバー名>:<フローデザイナーリスナーのポート>/help/<ロケール>/flow/designer/reference/component/<コンポーネント名>.html
マッパー関数http://<サーバー名>:<フローデザイナーリスナーのポート>/help/<ロケール>/flow/designer/reference/function/<マッパー関数名>.html

コンポーネント名はコンポーネント定義ファイルで「Component/@name」に定義された名前です。
マッパー関数名はマッパー関数定義ファイルで「Function/@name」に定義された名前です。
現在ヘルプのロケールは日本語(ja)固定です。

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

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

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

種別フォルダ
コンポーネントASTERIA_INSTALL/server/webapps/help/<ロケール>/flow/designer/reference/component
マッパー関数ASTERIA_INSTALL/server/webapps/help/<ロケール>/flow/designer/reference/function

抽出対象のファイルは以下のようになります。

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

ロケール毎に異なる言語でのヘルプを複数配置することができます。
日本語でのヘルプを作成する場合は「META-INF/asteria/ja」以下にヘルプのHTMLファイルと関連するイメージファイルを配置します。

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

ヘルプファイルの枠組みは多言語に対応できるように設計されていますが、現在はデザイナーからのヘルプ表示は日本語ヘルプのみに限定されています。
将来のバージョンではこの制限は緩和される予定なので可能なかぎり英語版のヘルプも作成し、「META-INF/asteria/en」以下に配置してください。

※これ以降で説明するヘルプ原稿の変換ツールは日英中の3言語に対応していますが、使用しない言語のヘルプはメンテナンスしなくても問題ありません。

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

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

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


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

3 ヘルプ原稿の書式

3.1 名前空間

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

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

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

要素名出現回数Description
Component1
   Streams1
      Input0..*
         Variable0..*
      Output0..*
         Variable0..*
   Properties1
      Property0..*
         Value0..*
   Loop0..1
   Transaction0..1
      Commit0..1
      Rollback0..1
   Exception0..*
      Case1..*
      Param0..1
      Message0..1
      ParamDescription0..1
      Stream0..1
   Topic0..*
   Guide0..*

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

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

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

要素名出現回数Description
Function1
   Input1
      Value0..*
   Output1
      Value1..*
   Properties1
      Property0..*
         Value0..*
   Exception0..*
      Case1..*
   Topic0..*
   Guide0..*

コンポーネントヘルプとマッパー関数ヘルプでは多くの要素が共通していますが、 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」(汎用)の場合は省略して構いません。
title対応するParam要素のTopicのタイトル
省略した場合はnameで設定した値から自動で作成されます。
Param要素を設定しない場合は省略して構いません。
id対応するParam要素のTopicのID
省略した場合はnameで設定した値が使用されます。
Param要素を設定しない場合は省略して構いません。

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

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

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

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

Param要素が定義されている場合、Exception要素の子要素としてMessage要素を定義しParam要素に関する情報をそのDescriptionに記述します。 省略した場合はParam要素のTopicへのリンクが表示されます。

Param要素が定義されている場合、Exception要素の子要素としてParamDescription要素を定義しParam要素のTopicの詳細情報をそのDescriptionに記述します。 省略した場合は何も表示されません。

エラー発生時にエラー処理用のストリームを生成するコンポーネントの場合は 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要素自体を省略しても良いので通常は使用しない)
connectionFSMCで設定するコネクション情報。コネクションプロパティ

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ファイルの所定の位置にヘルプをコピーするタスクです。