コンポーネント／マッパー関数ではデザイナーの右クリックメニュー「ヘルプ」からHTML形式のヘルプを参照することができます。
このHTMLはXML形式のヘルプ原稿を変換することで生成されます。
ここではそのヘルプ原稿の書式について説明します。
デザイナー上でコンポーネント／マッパー関数の右クリックメニューからヘルプを実行した場合、接続中のサーバー上にあるヘルプのHTMLファイルがブラウザで表示されます。
デザイナーがサーバー接続されていない場合はインターネット上にある製品サイトのヘルプが表示されます。
ただし、標準コンポーネント／マッパー関数以外のカスタムコンポーネント／マッパー関数のヘルプはインターネット上には存在しないのでそれらのヘルプはサーバー接続時にしか表示できません。
ヘルプのURLは以下になります。
| 種別 | URL |
|---|---|
| コンポーネント | http://<サーバー名>:<フローデザイナーリスナーのポート>/help/<ロケール>/flow/designer/reference/component/<コンポーネント名>.html |
| マッパー関数 | http://<サーバー名>:<フローデザイナーリスナーのポート>/help/<ロケール>/flow/designer/reference/function/<マッパー関数名>.html |
コンポーネント名はコンポーネント定義ファイルで「Component/@name」に定義された名前です。
マッパー関数名はマッパー関数定義ファイルで「Function/@name」に定義された名前です。
現在ヘルプのロケールは日本語(ja)固定です。
コンポーネント(マッパー関数)はjarファイルで配布されます。
jarファイルを「DATA_DIR/system/lib/components」に置くことで新たに追加したコンポーネント／マッパー関数がサーバーにインストールされます。
この時にjarファイル内からヘルプ関連のファイルが抽出されヘルプ用のフォルダにコピーされます。
コピー先のフォルダは以下になります。
| 種別 | フォルダ |
|---|---|
| コンポーネント | [INSTALL_DIR]/server/webapps/help/<ロケール>/flow/designer/reference/component |
| マッパー関数 | [INSTALL_DIR]/server/webapps/help/<ロケール>/flow/designer/reference/function |
抽出対象のファイルは以下のようになります。
| 種別 | jarファイル内でのパス | ファイル種別 |
|---|---|---|
| コンポーネント | META-INF/asteria/<ロケール>/reference/compoent | すべてのファイル |
| マッパー関数 | META-INF/asteria/<ロケール>/reference/function | すべてのファイル |
ロケール毎に異なる言語でのヘルプを複数配置することができます。
日本語でのヘルプを作成する場合は「META-INF/asteria/ja」以下にヘルプのHTMLファイルと関連するイメージファイルを配置します。
ヘルプファイルの枠組みは多言語に対応できるように設計されていますが、現在はデザイナーからのヘルプ表示は日本語、英語、中国語のヘルプに対応しています。日英中のロケールはそれぞれ「ja」、「en」、「zh_CN」となります。
※これ以降で説明するヘルプ原稿の変換ツールは日英中の3言語に対応していますが、使用しない言語のヘルプはメンテナンスしなくても問題ありません。
ヘルプファイルの枠組みを考えた場合、HTMLファイルを直接作成してjarファイルの規定の場所に配置するという方法を取ることもできますが、この方法には次の2つの欠点があります。
これらの問題を回避するためにヘルプ作成では次のような手順で行われます。
ヘルプ原稿のxmlと定義ファイルをマージすることによって定義ファイルから必要な情報を取得した中間ファイルを生成し、それに対してxsl変換を行うことでスタイルの統一されたHTMLを生成します。
SDKによって生成されるANTのビルドファイルにはこれらの手順を自動化するタスクがあらかじめ定義されています。
ヘルプ原稿の要素はすべて上記の名前空間に属します。
ヘルプ原稿内では別の名前空間に属する要素(主にHTML)を自由に使用することができます。
コンポーネントヘルプ原稿の要素構造は以下のようになります。
| 要素名 | 出現回数 | 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 | ○ |
| Message | 0..1 | ○ |
| ParamDescription | 0..1 | ○ |
| Stream | 0..1 | ○ |
| Topic | 0..* | |
| Guide | 0..* |
表のDescription列はそれぞれの要素に対する説明を記述できるかどうかを示しています。
Descriptionの記述方法については後述します。
マッパー関数ヘルプ原稿の要素構造は以下のようになります。
| 要素名 | 出現回数 | 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要素など一部の要素では定義方法が異なるので注意が必要です。
以下にそれぞれの要素の定義方法と意味を説明して行きます。
コンポーネントヘルプまたはマッパー関数ヘルプの文書要素です。
| 名前 | 区分 | 説明 |
|---|---|---|
| name | 必須 | コンポーネント(マッパー関数)名 定義ファイルのComponent要素またはFunction要素のname属性と同じでなければなりません。 |
| title | コンポーネント(マッパー関数)の簡潔な説明を書きます。 コンポーネント(マッパー関数)の表示名とこのtitleがヘルプの大見出しになります。 |
Descriptionにはコンポーネント(マッパー関数)の概要を書きます。
表示名(displayName)やアイコンファイル名(icon)は定義ファイルからマージするので記述する必要はありません。
コンポーネントのストリーム情報のプレースホルダです。
入力ストリームの情報です。
サブコネクタを持つコンポーネントの場合は複数定義します。
| 名前 | 区分 | 説明 |
|---|---|---|
| type | 必須 | 受け入れ可能なストリーム型を「,」あるいは「|」区切りで記述します。 |
| count | 必須 | 受け入れ可能なストリーム数を記述します。 無制限にストリームを受け入れる場合は「unbounded」とします。 |
Descriptionには入力ストリームがどのように使用されるかを記述します。
入力ストリームを使用しないコンポーネントの場合は省略しても構いません。
コンポーネントが入力ストリームに設定されたストリーム変数を使用する場合は
子要素としてVariable要素を定義し使用するストリーム変数に対する説明をDescriptionに記述します。
Variable要素は複数定義することができます。
| 名前 | 区分 | 説明 |
|---|---|---|
| name | 必須 | ストリーム変数名 |
| type | 必須 | データ型 |
出力ストリームの情報です。
サブコネクタや分岐のあるコンポーネントの場合は複数定義します。
| 名前 | 区分 | 説明 |
|---|---|---|
| type | 必須 | 出力可能なストリーム型を「,」あるいは「|」区切りで記述します。 |
| name | 複数の出力コネクタを持つコンポーネントの場合は出力コネクタに対応する名前を記述します。 出力コネクタが一つしかないコンポーネントの場合は省略して構いません。 |
Descriptionにはどのようなストリームが出力されるのかを記述します。
入力をそのまま出力するだけのコンポーネントの場合は属性定義で「description="filter"」とすることで
キーワードファイルの説明を参照することができます。
コンポーネントが出力ストリームにストリーム変数を付加する場合は
子要素としてVariable要素を定義し付加するストリーム変数に対する説明をDescriptionに記述します。
Variable要素は複数定義することができ、その定義方法はInput要素で行う場合と同じです。
コンポーネント(マッパー関数)のプロパティ情報のプレースホルダです。
プロパティの情報です。
プロパティの数だけ定義します。
| 名前 | 区分 | 説明 |
|---|---|---|
| name | 必須 | プロパティ名 定義ファイルのProperty要素またはCategory要素のname属性と同じでなければなりません。 |
Descriptionにはプロパティの概要を記述します。
表示名(displayName)やプロパティ型(type)、マッピング(mapping)は定義ファイルからマージするので記述する必要はありません。
プロパティがboolean型やchoice型など選択肢を持つ場合には
子要素としてValue要素を定義しそのDescriptionに選択肢に対する説明を記述することができます。
Value要素は複数定義することができます。
| 名前 | 区分 | 説明 |
|---|---|---|
| name | 必須 | 選択肢の値 定義ファイルでChoiceItemとして定義された値と同じでなければなりません。 |
選択肢の表示名は定義ファイルからマージするので記述する必要はありません。
コンポーネントがループの起点となる場合にその情報を記述します。
ループがない場合は省略して構いません。
コンポーネントがトランザクションをサポートする場合にその情報を記述します。
コミット時の処理とロールバック時の処理をそれぞれCommit要素とRollback要素に分けて記述します。
コミット時にのみ何かしらの処理を行いロールバック時には何も行わない場合はRollback要素は省略して構いません。
発生しうるエラーについての情報を記述します。
エラー情報はケース毎にCase要素に分けて記述します。
Exception要素は対応するエラー処理プロパティごとに複数記述でき、 ひとつのException要素内に複数のCase要素を記述することもできます。
| 名前 | 区分 | 説明 |
|---|---|---|
| name | 対応するエラー処理プロパティの名前 対応するエラー処理プロパティが「Exception」(汎用)の場合は省略して構いません。 |
|
| title | 対応するParam要素のTopicのタイトル 省略した場合はnameで設定した値から自動で作成されます。 Param要素を設定しない場合は省略して構いません。 |
|
| id | 対応するParam要素のTopicのID 省略した場合はnameで設定した値が使用されます。 Param要素を設定しない場合は省略して構いません。 |
エラー処理プロパティの表示名(displayName)は定義ファイルからマージするので記述する必要はありません。
| 名前 | 区分 | 説明 |
|---|---|---|
| code | 発生するエラーにエラーコードが振られている場合はそのコードを記述します。 |
エラー発生時にパラメーター(エラー処理フロー内でシステム変数から参照できる)が設定される場合は
Exception要素の子要素としてParam要素を定義しパラメーターに関する情報をそのDescriptionに記述します。
Param要素はTopicの一つとして出力されます。
Param要素は複数定義することができます。
| 名前 | 区分 | 説明 |
|---|---|---|
| index | 必須 | システム変数ExceptionParamでのインデックス |
| name | 必須 | システム変数ExceptionParamでの名前 |
Param要素が定義されている場合、Exception要素の子要素としてMessage要素を定義しParam要素に関する情報をそのDescriptionに記述します。 省略した場合はParam要素のTopicへのリンクが表示されます。
Param要素が定義されている場合、Exception要素の子要素としてParamDescription要素を定義しParam要素のTopicの詳細情報をそのDescriptionに記述します。 省略した場合は何も表示されません。
エラー発生時にエラー処理用のストリームを生成するコンポーネントの場合は
Exception要素の子要素としてStream要素を定義しエラー処理用のストリームに関する情報をそのDescriptionに記述します。
エラー処理用のストリームを生成しない場合はコンポーネントの入力ストリームがそのまま出力されるので、
この場合はStream要素は不要です。
コンポーネント(マッパー関数)に関してさらに詳細な説明を加えたい場合にはTopicまたはGuide要素の下に 任意のHTMLを記述することができます。
TopicとGuideは若干スタイルが異なるだけで定義方法自体は同じです。
TopicとGuideの使い分けについて明確な規定はありませんが、Topicは「注釈」、Guideは「説明」というような意味合いです。
例えばRDBGetコンポーネントのSQLBuilderのような専用UIがある場合にはGuideにその使用方法の説明を加えます。
Topic、Guideともに複数定義することができます。
| 名前 | 区分 | 説明 |
|---|---|---|
| title | 必須 | 見出しを記述します。 |
| id | 見出しに対してidを設定します。 ヘルプ内でハイパーリンクしたい場合には設定してください。 |
マッパー関数の入力に関する情報です。
| 名前 | 区分 | 説明 |
|---|---|---|
| min | 必須 | マッパー関数の動作に最低限必要な入力数 |
| max | 必須 | マッパー関数に入力できる最大数 無制限に入力をとることができる場合は「N」とします。 |
Input要素では入力毎に子要素としてValue要素を定義しDescriptionを記述します。
Constのように入力を持たないマッパー関数の場合はValue要素は省略して構いません。
Concatenateのように無制限に入力をとるマッパー関数の場合はValue要素はひとつ定義すれば構いません。
| 名前 | 区分 | 説明 |
|---|---|---|
| type | 必須 | データ型 |
| property | 入力がマッパー関数のプロパティ値を置き換える場合にそのプロパティ名を記述します property属性が定義された場合はDescriptionは必要ありません。 |
マッパー関数の出力に関する情報です。
出力毎に子要素としてValue要素を定義しそこにDescriptionを記述します。
Value要素の定義方法はInput要素の場合と同じですがproperty属性は使用できません。
Descriptionは対象とする概念に対して説明を加えるための書式です。
ある要素に対してDescriptionを記述する方法には次の3つがあります。
正確には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で設定するコネクション情報。 | コネクションプロパティ |
プロパティ名や選択肢など、定義ファイル上では実名と表示名が別に定義されているものが多数あります。
Description内ではそれらの実名を特別な要素で括ることで表示名と置き換えることができます。
また置換された単語にはスタイルが適用されるので文章中でその単語は強調されます。
例えばPropertyName要素でプロパティ名を置換した場合その置換文字列はspanで括られ「propertyName」
というclassが与えられます。
<h:PropertyName>Property1</h:PropertyName> ↓ 置換 <span class="propertyName">プロパティ1</span>
PropertyName要素でプロパティ名を括るとその表示名に置換されます。
PropertyName要素には属性はありません。
PropertyValue要素でプロパティの選択肢の値を括るとその表示名に置換されます。
| 名前 | 区分 | 説明 |
|---|---|---|
| property | 必須 | その選択肢のホルダであるプロパティ名 |
CategoryName要素でCategoryPropertyの列名を括るとその表示名に置換されます。
| 名前 | 区分 | 説明 |
|---|---|---|
| property | 必須 | その選択肢のホルダであるCategoryProperty名 |
ツールガイドで説明しているJavaInterpreterのウィザードから
生成されるbuild.xmlにはいくつかヘルプ生成に関するタスクが含まれています。
以下にヘルプに関連するタスクについて説明します。
ヘルプの原稿から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と同じフォルダにコピーされます。
(下位にフォルダを作成してそこにイメージを配置することはできません。)
定義ファイルからヘルプ原稿の雛型を生成するタスクです。
ウィザードでは最初に一度だけこのタスクが実行され、ヘルプ原稿がそれぞれの置き場所に生成されます。
ヘルプHTMLの生成先からjarファイルの所定の位置にヘルプをコピーするタスクです。