開発したモデルを、モジュラーモデル形式に変換する

最終更新日: 2020年10月20日
R8 | R9

はじめに Prefix を決める

モジュラーモデルの運用では、モデルIDが重複しないように配慮する必要があります。例えば異なる開発チーム X と Y が、たまたま PRODUCT というモデルを定義してしまうと、利用者は自分のリポジトリに両方の PRODUCT モデルをインストールすることができません。

これを回避するために、モジュラーモデルを開発する方は、はじめに開発チーム専用の Prefix を決めるようにしてください。これは英数字の組み合わせで 3 文字とします。

開発チーム X と Y がそれぞれ Prefix として "X01" と "Y01" に決めたとします。するとモジュラーモデルに含まれるモデルIDは必ず "X01PRODUCT", "Y01PRODUCT" となるため、利用者は二つのモデルをインストールすることができます。

注意

"JSH" という Prefix はジャスミンソフトが予約しています。それ以外の任意の文字の組み合わせを決めてください。

フォルダとファイルの構成ルール

addoncheker プログラムに渡すモジュラーモデルのルールを説明します。開発者はこのルールに基づいてモジュラーモデルを用意することができます。

ここからの説明は、addonchecker/input_addon_dir フォルダにモジュラーモデルを準備するものとします。

input_addon_dir フォルダには次のファイルを用意することができます。すべてのファイルの文字エンコーディングは UTF-8 で保存してください。

input_addon_dir
  |-- auth.key
  |-- metadata.txt
  |-- doc
  |    |-index.html
  |
  |-- repo
       |-<モデルID>
       |-<モデルID>
       |...

auth.key

インストール時に利用する認証キー。このファイルが存在しない場合、このモジュラーモデルは自由にインストールできます。認証キーについては後述します。

metadata.txt

アドオンギャラリーに表示されるアドオンアプリのアイコンが利用するメタデータ。次のフォーマットとなります。

キー:値 <改行>

サンプルを示します。

TARGET: 8.4.0
VERSION: 1.0.0
NAME: JSHSCHEDULE
ICONCLASS: fas fa-calendar-alt
SUMMARY: 
汎用スケジュール管理
キー 説明 区分
TARGET このモジュラーモデル作成に利用したWagbyのバージョン。 必須
VERSION モジュラーモデルのバージョン。”メジャー.マイナー1.マイナー2” 表記。 必須
NAME 識別するためのモジュラーモデルID。アルファベットと数字の組み合わせで構成される。アドオンギャラリー内で重複させることはできない。なお NAME の先頭3文字は事前に決めた Prefix ではじめること。 必須
ICONCLASS アドオンギャラリータブに表示されるアイコン。Wagbyのアイコンは Font Awesome を利用しているため、ここにはFont Awesome のクラスを指定する。 任意
SUMMARY このモジュラーモデルの簡単な説明文。HTMLタグは利用できない。このキーは必ず metadata.txt の最後に記述し、キー "SUMMARY:" で改行したあとに記述する。 必須

doc/index.html

アドオンギャラリーに表示されたアイコンをクリックすると表示されるHTML文書です。標準的な構造は次の通り。

<div class="addonDocument">
<h1>モジュラーモデル名</h1>
<h2>含まれるモデル1</h2>
<h3>特徴1</h3>
<p>
内容
</p>
<h3>特徴2</h3>
<p>
内容
</p>
<h2>含まれるモデル2</h2>
<h3>特徴1</h3>
<p>
内容
</p>
...
</div>

なお、この文書には、利用者がインストールしたあとでやるべきことも明記するとよいでしょう。例えばメニューへ登録すべきモデルや、初期データの設定方法などです。(初期データについては後述します。)

画像ファイル

doc フォルダに画像ファイルを含めることができます。例えば doc/images というフォルダを用意し、ここに capture.jpg という画像ファイルを置いたとき、index.html には次のように指定することができます。

<img src="/mms/doc/<モジュラーモデルID>/images/capture.jpg"/>
<モジュラーモデルID> の部分は適切に読み替えてください。(例 JSHSCHEDULE など)
wagby.com に配置して一般にダウンロードしてもらう場合(後述)、URLの先頭に "https://wagby.com/" を含めるようにしてください。

repo

開発者が作成したモデルを含むフォルダです。具体的には、リポジトリフォルダ (repository/trunk) に含まれる <モデルID> フォルダ一式をコピーします。ここでモデルIDは、上述した Prefix ではじまる必要があります。

なお、<モジュラーモデルID>で指定したモデルIDを一つ、含めるようにしてください。例えばモジュラーモデルIDが "JSHSCHEDULE" の場合、同名のモデルIDフォルダが存在する必要があります。

また、この例では Prefix が "JSH" でした。そこでモジュラーモデルに含めるモデルIDはすべて "JSH" ではじまる必要があります。

Wagby Designer で 2 つのモデル JSHSCHEDULE, JSHSCHEDULETYPEM を用意したとします。この2つのモデルを含むモジュラーモデルのIDを "JSHSCHEDULE" としました。このとき、repository/trunk/JSHSCHEDULE, repository/trunk/JSHSCHEDULETYPEM フォルダをそれぞれ repo/JSHSCHEDULE, repo/JSHSCHEDULETYPEM としてコピーします。このように、モジュラーモデルIDの先頭3文字JSHと、これに含まれる各モデルIDの先頭3文字JSHは必ず一致しなければなりません。

認証キー

input_addon_dir フォルダの直下に auth.key を配置することができます。この内容は gethash コマンドで、sha-256 アルゴリズムを使ったハッシュ値とします。

例えば認証キーを "wagby" とする場合、この文字列を sha-256 アルゴリズムでハッシュ化した値を auth.key の内容とします。

SfXpY49wuPzTjccA4w6zjvjvPbLwdV4zhPm3euckgvg
無用な空白や空行を含めないようにしてください。少しでも異なる文字が含まれていると認証キーを正しく解釈できません。

モジュラーモデルに auth.key が含まれているとき、利用者がこれをインストールしようとしたときに認証キーの入力が求められます。認証キーが一致しないと、インストールすることができません。

ワンポイント

モジュラーモデルに auth.key が含まれていない場合、利用者は認証なしでインストールすることができます。

初期データを含める

モジュラーモデルに、モデル毎の初期データを含めることができます。具体的には次のフォルダにインポート用の xml ファイルを含めます。

repo/<モデルID>/<モデルID>/.initialdata

例えば消費税を扱うモデル JSHTAX に、初期データとして 3,5,8,10 パーセントというデータを用意する場合、上記フォルダにそれぞれのデータを示す xml ファイルを保存しておきます。この実体は、Wagbyのエクスポート機能で出力されるファイルです。

このモジュラーモデルをインストールすると、export/data_addon_<モデルID> フォルダが用意され、その中にxmlファイルが展開されます。(なお同名のフォルダがすでにexportフォルダ内に存在した場合、最初に既存フォルダを削除してからコピーします。)

利用者はアプリケーションをビルド後、上のフォルダを指定してインポート処理を行い、初期データを登録することができます。

スクリプトを含める

モジュラーモデルにスクリプトを含めることができます。このとき、スクリプト中に Java のパッケージ名 (例 jp.jasminesoft.wagby) が記述されている場合があります。しかしインストール先のプロジェクトはパッケージ名が変わっている可能性があるため、このままではインストール先でスクリプトの実行が失敗する懸念があります。

そこで開発者は、パッケージ名部分をプレースホルダ表記に変更するための addonchecker コマンドのオプション -p を利用します。

addonchecker.bat -i JSHSCHEDULE -s input_addon_dir –p jp.jasminesoft.wagby -o

この指定を行うとスクリプト中の文字列 "jp.jasminesoft.wagby" が "${packagename}" に置換されます。利用者によるインストール時に、このプレースホルダ表記は再度、環境に応じて置換されます。

カスタマイズファイルを含める

モジュラーモデルにカスタマイズファイル (.jspや.javaなどのファイル)を含めることができます。具体的には次のフォルダにカスタマイズファイルを含めます。

repo/<モデルID>/<モデルID>/.customize

このフォルダの扱いは次のルールに則ります。

  • このモジュラーモデルをインストールすると、利用者のWagbyインストールフォルダのcustomizeにマージされる。
  • すでに同名のファイルが存在した場合は「上書き」される。
  • 拡張子 .java の場合、.customize/java/${packagename}/app などといったフォルダを用意する。
  • 拡張子 .java, .jsp, .js のファイルはテキスト中の ${packagename} 指定が、パッケージ名に置換される。
  • 拡張子 .java, .jsp, .js のファイルの文字コードはUTF-8であること。
  • 拡張子 .bak およびファイルの末尾が “~” で終わるファイルは無視される。

.customize フォルダに .java や .jsp を含めるとき、ソースコードに記述するパッケージ名を固定にすることはできません。そこで開発者は、手動でパッケージ名部分を${packagename}と変更したものを (.customizeフォルダに) 配置するようにしてください。例を示します。

repo
 |- JSHSCHEDULE
    |- .customize
        |- java
            |- ${packagename}
                |- app
                   |- MyJSHSCHEDULEHelper.java

MyJSHSCHEDULEHelper.java は次のように記述されることを前提としています。

package ${packagename}.app;
public class MyJSHSCHEDULEHelper extends JSHSCHEDULEHelper {
...
}

読み込み専用モデルとする

モジュラーモデルに含まれるモデルを読み込み専用として提供することができます。 addonchecker コマンドのオプション -r を利用します。

addonchecker.bat -i JSHSCHEDULE -s input_addon_dir -r JSHSCHEDULE -o

-r オプションに続いてモデルIDを指定します。複数のモデルIDを指定する場合は "," で区切ります。

wagby.comへ配置する

wagbydesigner/webapps/mms/WEB-INF フォルダにある modules 一式を zip コマンドで圧縮します。

cd wagbydesigner/webapps/mms/WEB-INF
zip -r modules.zip modules

作成した modules.zip をジャスミンソフトへお送りください。

modules/docフォルダが画像を含む場合、imgタグのsrc属性は "https://wagby.com/" ではじまるように予め修正してください。

仕様・制約

  • モジュラーモデルのID (metadata.txtのNAME値) の先頭3文字と、repoフォルダに含まれるすべてのモデルIDの先頭3文字は一致する必要があります。この先頭3文字は Prefix として事前に決めるようにしてください。
  • アドオンアプリの追加先は常に「ユーザモデル」です。「システムモデル」に追加することはできません。
  • 項目ルールを含めたモデルは流通させることができません。(項目ルールだけをインポートエクスポートすることはできないためです。)
  • 環境に依存する定義を含めることはできません。例えばサブデータベースや、MQの利用を前提とすることはできません。
  • モジュラーモデルを作成したときの Wagby のバージョンは metadata.txt の TARGET に記載されています。利用者(Wagby Designer)の Wagby のバージョンが新しい場合、自動的に移行ツールが適用されます。
  • TARGET に記載されたバージョンが、利用者の Wagby よりも新しい場合、つまり利用者の Wagby が古い場合は、そのモジュラーモデルをインストールすることはできません。
  • モジュラーモデルをインストールすると、repository/trunk に .mm_install_logs フォルダが用意されます。アンインストール機能は、このログを参照します。