第4章 フォーム

4.1. フォームの Cordova アプリへの統合

フォームの機能は既存アプリに統合できます。本ガイドでは、監督者がジョブを割り当て、作業者がモバイルデバイスでその割り当てを受信し、ジョブについての情報を送り返すまでの労働力管理の例を使ってこの統合について説明します。

本ガイドの手順では、Cordova アプリおよびクラウドアプリを使用します。これらのアプリをプロジェクトにインポートして、本ガイドで説明する実際例について説明します。

4.1.1. 実際例

4.1.1.1. 概要

このサンプルアプリケーションには以下の要件が設定されます。

監督者は、暴風雨で倒れた木を取り除くという作業者のジョブを作成します。監督者は作業者に対し、木の写真や位置情報、コメントおよび開始時間と終了時間などのジョブについての詳細情報の提出を求めます。このタスクはフォームアプリを使用して実行することができます。

監督者は以下を実行してジョブを作成します。

  • 作業者が記入するフォームの選択
  • フォームの選択およびジョブの詳細情報のフォームへの記入
  • ジョブの固有 ID の指定

アプリケーションの要件には以下が含まれます。

  • ジョブは、管理者が作成フォームに記入して作成する。
  • 新規ジョブは管理者と管理者以外のユーザーのどちらも利用できる。アプリユーザーは記載済みの作成フォームを閲覧できる。
  • アプリユーザーは別の完了フォームに記入してジョブを完了できる。
  • 完了フォームはすべてのアプリユーザーが確認できるよう表示可能でなければならない。
  • クライアントアプリのユーザーは、完了フォームをドラフトとして保存し、これに「In Progress (進行中)」または「Complete (完了)」のいずれかのマークを付けることができます。

4.1.1.2. Cordova アプリ

クライアントアプリは以下のテクノロジーをベースとしています。

  • Backbone: Cordova アプリは backbone モデルおよびビューを使用してジョブの作成および更新を管理します。
  • Handlebars: ビューのテンプレートに使用されます。
  • Boostrap: スタイリングに使用されます。
  • Font-Awesome: アイコンに使用されます。

Cordova アプリは以下を行います。

  • さまざまな状態のジョブの一覧表示を管理
  • フォームの表示を管理
  • フォーム提出および提出のアップロードを管理
  • フォームおよび提出データを含むジョブの作成を管理
4.1.1.2.1. ジョブモデル

ジョブモデルは、ジョブについて説明する単純な Backbone モデルです。

ジョブコレクションは、ジョブモデルの集合です。

クライアントとクラウド間でジョブを同期するためにカスタム URL が組み込まれます。このカスタム URL はクラウドアプリで RESTful /jobs エンドポイントにアクセスするために使用されます。

4.1.1.3. クラウドアプリ

クラウドアプリは、$fh.db API を使用してジョブデータに対して CRUD 操作を実行するための RESTful エンドポイント (/jobs) で構成されています。

注記

すべてのクラウドベースのフォームロジックは クラウド API に含まれているため、クラウドアプリではフォームを処理するためのロジックは表示されません。

4.1.2. 実際例の作成

  1. App Studio で新規プロジェクトを作成します。
  2. アプリをプロジェクトにインポートします。たとえば、本ガイドのサンプルでは Cordova アプリおよびクラウドアプリが使用されます。
  3. プロジェクトのフォームおよびテーマを作成します。プロジェクトに関連付けて作成されるすべてのフォームとテーマは Cordova アプリに表示されます。
  4. オプションで、ユーザーおよびフィールドコードをプロジェクトに追加します。例えば以下のようになります。

    • 管理者: ジョブを作成し、完了することができる。
    • ユーザー: ジョブを完了することができる。

    ユーザーには、関連フォームの表示前に提出に自動的に追加される userId および userName フィールドがあります。2 つのテキストフィールドをこの実際例に関連付けられたフォームに追加します。

    これらのフィールドが追加されたら、データブラウザーの users (ユーザー) コレクションに 2 名のユーザーを追加します。

    管理者

    {
        "userId": "admin",
        "userName": "<<Any Name>>"
    }

    ユーザー

    {
        "userId": "user",
        "userName": "<<Any Name>>"
    }

4.1.3. 実装ガイド

以下を使用してフォームの機能をアプリに統合します。

  1. $fh.forms.init 関数をクライアントに追加してフォームの初期化 (Forms Initialization) を追加します。これにより、クライアントアプリのフォームが初期化され、アプリの他の場所で $fh.forms Client API の使用が可能になります。

    $fh.forms.init 関数は、アプリのログインプロセスの一部を構成します。

  2. 管理者ユーザーとして完了フォームを選択します。これにより、ジョブを完了するために記載する必要のあるフォームが指定されます。$fh.forms.getForms クライアント API 関数を使用してアプリで利用できるすべてのフォームを一覧表示します。

    注記

    $fh.forms.getForms クライアント API 呼び出しは、フォームの一覧のみをダウンロードしますが、各フォームの全体のフォーム定義はダウンロードしません。

  3. $fh.forms.getForm クライアント API を使用してフォームをクライアントにダウンロードします。

    フォームはジョブ作成、ジョブ詳細の表示、およびジョブの完了で使用されるため、この関数はヘルパー関数のセットに抽象化されます (こちらを参照してください)。

    $fh.forms.getForm クライアント API の使用法は、FormFunctions.jsloadForm 関数の一部として使用される場合はこちらで確認できます。

  4. 提出をアプリにロードします。このプロセスは、FormFunctions.js ファイルの loadSubmission 関数の使用に関連して説明されています。

    フォームに入力されるデータは提出に設定されるため、フォームは提出に関連します。ただし、提出はクラウドにアップロードされる前にフォームに対して検証されます。

    提出を作成する方法として、以下の 3 つの方法があります。

    • ローカルメモリーから: 提出をドラフトとしてローカルメモリーに保存してから、提出モデルの saveDraft 関数を使用して保存します。この機能の実装については、loadLocalSubmission 関数で説明されています。
    • リモートからのダウンロード: クラウドから提出をダウンロードします。たとえば、監督者がジョブの詳細を説明するためにフォームに記載する際に、提出の ID がジョブモデルに保存されます。アプリユーザーがジョブモデルをダウンロードすると、ユーザーは管理者ユーザーが提出したフォームのリモート提出 ID にアクセスできます。このリモート提出 ID は、クラウドから提出の詳細定義をダウンロードするために使用されます。この機能の実装については、downloadSubmission 関数で説明されています。
    注記

    提出のフォーム定義はクラウドからダウンロードされる提出に含まれます。フォーム定義が複数の提出間で編集されている可能性があるためです。

    注記

    ダウンロードされた提出はクライアント上で編集できません。これらには読み取り専用アクセスのみが意図されています。ダウンロードされた提出のクラウドへの送信を試行すると、エラーが返されます。

    • 新規の提出の作成: フォームに関連付けられた提出がない場合に、新規の提出を作成できます。この場合、提出は、フォームモデルで作成されます。これにより、提出が適切なフォームに自動的に関連付けられます。
  5. ユーザーが編集できるようにフォームをビューに表示します。

    フォームを既存の Cordova アプリに表示する方法として、以下の 2 つの方法があります。

    • $fh.forms.backbone API を使用したフォームの表示: これには backbone/bootstrap SDK ($fh.forms.backbone) が含まれます。Appforms Backbone ファイルをダウンロードして Cordova アプリの一部として組み込みます。また、Cordova アプリは以下の JavaScript および CSS 依存関係に対応している必要があります。

      • Backbone
      • Bootstrap
      • Font-Awesome

      CSS および JavaScript 依存関係はサンプルの Cordova アプリに組み込まれています。

      FormViewSDK.js ファイルには、Backbone SDK バージョンのフォームビューが含まれます。Cordova アプリには Backbone SDK と手動によるフォーム表示間での切り換えを行うための「Settings」タブのオプションが含まれます。

      注記

      Backbone SDK は、Backbone/Bootstrap ベースの Cordova アプリのフォームアプリの統合を加速させることを目的としています。$fh.forms クライアント API についてはすべての Cordova アプリで機能します。フォームのレンダリングとユーザーデータの送信内容への事前設定は開発者が行うタスクになります。

    • フォームの手動表示

      注記

      フォームのユーザーへの表示は、提出を完了する最も簡単な方法ですが、フィールド入力値はどのソースからも提出に追加できます。提出はフィールドまたはページルールに対して有効な状態である必要があります。

      $fh.forms SDK はいずれのフレームワークにも依存しないため、どの Cordova アプリにも追加できます。このアプリは Backbone および Bootstrap をベースとしていますが、$fh.forms APIを他の javascript ベースの UI フレームワーク (例: Angular) と共に使用することも同様に可能です。

      基本的な Bootstrap フォームはフォーム定義に基づいて表示されます。このフォームは FormView.js ファイルで定義されます。フォームの表示、入力される提出内容および検証ロジックはすべて $fh.forms API およびモデルを使用してアプリに定義されます。

      注記

      手動で表示されるフォームは説明用としてのみ実装されます。手動で実装できるのはテキストフィールドと数値フィールドのみですが、利用可能なフォームのフィールドタイプはすべて $fh.forms.backbone SDK を使用して表示できます。

      カスタムフォームビューの表示ロジックは FormView.js ファイルにあります。ここでは、このビューがフォームのユーザーへの表示に関係するすべてのイベントを処理することを確認できます。

      さらに、FormView.js ファイルには以下を実行するためのロジックが含まれます。

      • 入力時のフィールドデータの検証
      • フィールドおよびページルールの検査
      • 提出へのデータの設定
      • 提出のドラフト保存
      • クラウドへのフォームの提出

      以下のステップでは、$fh.forms SDK をカスタムで表示されたフォームに手動で統合する際に Cordova アプリがこれらの要件にどのように対応するかを説明します。

  6. フィールドに入力できるデータを制限する検証パラメーターを定義します(たとえば、テキストフィールドではフィールドに入力できる最小/最大文字数を指定できます)。この機能をクライアントアプリに追加すると、フィールドの制限が反映されます。

    この要件に対応するために、validateInput 関数は FormView.js ファイルの入力の blur イベントに登録されます。

    注記

    検証パラメーターは提出の有効性に影響を与えます。フィールドの検証がクライアントアプリで実行されない場合でも、すべての提出フィールドはデータベースに保存される前に検証されます。

  7. フォームアプリには、フィールドおよびページルールが含まれます。Studio では、フォームエディターでフィールドルールを作成し、フィールド入力データに基づいてフィールドを表示/非表示にしたり、ページルールを作成してフィールドに入力されるデータに基づいてページを表示/スキップしたりすることができます。

    この機能は $fh.forms API の実装に反映されます。ルールエンジンを使用して提出を処理することで、その提出で表示/非表示にする必要のあるフィールドまたはページを特定できます。

    これは FormView.js ファイルの checkRules 関数で実装されます。

    注記

    フィールドおよびページルールは、提出の有効性に影響を与えます。クライアントアプリでフィールドおよびページルールにチェックが付けられていない場合でも、提出はデータベースに保存される前にすべてのルールに基づいてチェックされます。

  8. addInputValue 関数を使って提出モデルにデータを追加します。このデータのソースとして、ユーザーに表示されたフォームか、アプリで利用できる外部データ、またはそれらの組み合わせのいずれかを使用することができます。

    • 表示されたフォーム: この場合、フォームはユーザーが $fh.forms.backbone SDK を使用してデータを入力できるように表示されるか、または手動で表示されます。

      $fh.forms API をカスタムで表示されたフォームに手動で統合する際に、ビューから提出モデルへのデータ移行に対応する必要があります。

      これは FormView.js ファイルの saveFieldInputsToSubmission 関数で説明されています。

    • フィールドコードの使用による外部ソース: フィールドコードを追加してフォーム内のフィールドを一意に特定するためのフィールドを作成できます。このフィールドコードは外部データソース (例: CSV ファイルのヘッダー) に関連付けられます。この機能を使用して、外部データをフォームの提出にインポートすることができます。

      この機能は、サンプルの Cordova アプリにおいては addSubmissionData 関数で説明されています。この例では、ユーザーには userId および userName フィールドがあります。フォームにフィールドコード userId および userName のフィールドが含まれる場合、これらのフィールドにはユーザーモデルのデータが設定されます。

      注記

      フィールドコードはフォーム内で一意である必要があります。ただし、同じフィールドコードを複数のフォームに存在させることは可能です。

  9. 提出をドラフトとして保存します。この機能は FormView.js ファイルの saveDraft 関数で説明されています。
  10. 検証およびルール機能をフォームに追加すると、有効な提出をクラウドに送信して提出エディター (submission editor) で表示または編集を実行できます。

    フォームビューは、データの処理およびアップロード時に提出モデルで生成される提出関連のイベント (validationerrorqueuedprogresserrorsubmitted) をリッスンします。

    提出プロセスには以下の 2 つのステップが関係します。

    • Submit (提出): 提出モデルで submit 関数を呼び出すと、提出がローカルフォームの定義に対して検証され、提出ステータスが pending (保留中) に変更されます。
    • Upload (アップロード): 提出モデルで upload 関数を呼び出すと、提出がフォームデータベースへのアップロードのキューに入れられます。

4.2. OpenShift 2 ターゲットでのフォームサポートの有効化

OpenShift 2 ターゲットにデプロイされたクラウドアプリでフォームを使用するためのサポートはすぐに利用できる訳ではありません。このサポートは、本ガイドで説明されているステップを実行して有効にすることができます。

注記

本ガイドは、openshift.feedhenry.com などの OpenShift 2 ターゲットのサポートのある Platform インスタンスのみに適用されます。他のターゲットの場合も、フォームのサポートを追加の設定なしに利用可能にすることができます。

4.2.1. Platform のフォームのバックグラウンド

Platform のバックエンドには、fh-mbaas というフォーム関連の操作を処理するサービスがあります。この機能は $fh.forms API で公開され、これにはフォーム定義へのアクセス、フォームの提出およびデプロイメントが含まれます。

Red Hat MBaaS ターゲットの場合、fh-mbaas のインスタンスは常に利用でき、これを手動で有効にする必要はありません。ただし、デフォルトで fh-mbaas サービスがデプロイされない OpenShift 2 ターゲットの場合にはこの限りではありません。この機能は Platform のサービステンプレートとして別途提供され、これを OpenShift 2 ターゲットにデプロイすることでフォームのサポートを有効にすることができます。

fh-mbaas OpenShift アプリケーション

OpenShift 側では、フォームのサポートはカートリッジで実装されます。このカートリッジは、OpenShift アカウントにより個別アプリケーションの Node.js ランタイムおよびデータベースカートリッジと共にホストされ、この機能をフォームベースのすべてのアプリケーションに公開します。

4.2.2. OpenShift 2 ターゲットのフォームサポートを有効にする方法

前提条件:

  • OpenShift 2 ターゲットのサポートのある RHMAP アカウント
  • 既存の OpenShift 2 ターゲットおよび関連付けられた環境

以下のステップでは、アプリが OpenShift 2 ターゲットでフォームを使用できるようにするプロセスを説明します。

  1. OpenShift mBaaS サービスのインスタンスの作成およびデプロイ

    1. Studio のサービス & API セクションで、MBaas サービス/API のプロビジョニングをクリックします。
    2. 利用可能なサービスの一覧から OpenShift mBaaS Service を選択し、このサービスインスタンスに適切な名前を入力して次へ進むをクリックします。
    3. ログウィンドウに Service is ready! が表示されるまで待機し、終了をクリックします。「サービスの詳細」ページが表示されます。
    4. 左側のメニューにあるデプロイセクションに移動します。
    5. 画面右側のドロップダウンメニューから OpenShift ベースの環境を選択します。
    6. クラウドアプリをデプロイをクリックします。
    7. サービスがデプロイされるまで待機します。画面下部の Deploy History (デプロイ履歴) セクションにデプロイのステータスと結果が表示されます。これらのインジケーターには状態が即時に反映されない可能性があります。ページを再ロードしてステータスを更新し、正しい環境が選択されていることを確認します。デプロイメントが終了したら、ページを再度ロードし、画面上部の Deploy OptionsCurrent Host フィールドがあることを確認します。

      注記

      サービスのデプロイには数分の時間がかかる可能性があります。これはギアの作成、いくつかのカートリッジのプロビジョニング、Git リポジトリーおよび他のセットアップ操作のクローンが行われるためです。このデプロイは 1 つの OpenShift 2 ターゲットに対して 1 回のみ実行されます。同様に、クラウドアプリの初回デプロイメントの場合も、それに続くデプロイメントより多くの時間がかかる可能性があります。

      サービスのデプロイ履歴

    8. 画面の Deploy Options セクションの Current Host フィールドの値をメモするか、またはコピーします。この URL は fh-mbaas サービスとして機能する新たに作成された OpenShift アプリケーションを指します。

      デプロイされた fh-mbaas サービスの現行ホスト

  2. OpenShift 2 ターゲットに正しい fh-mbaas ホスト URL を設定します。

    1. Studio の管理/ MBaaS ターゲットセクションに移動し、既存の OpenShift 2 MBaaS ターゲットを開きます。
    2. 先に保存した fh-mbaas サービスの URL を fh-mbaas ホストフィールドに入力します。
    3. MBaaS を保存をクリックします。

この新たな OpenShift ベースの環境にデプロイされるすべてのクラウドアプリはフォーム機能にアクセスできます。

単一の fh-mbaas サービスを使用することでフォームサポートを複数の OpenShift 2 MBaaS ターゲットに提供することができ、このサービスを使用する OpenShift 2 MBaaS ターゲット以外の OpenShift インスタンスに配置することができます。フォームを使用するクラウドアプリは、ターゲットに有効な fh-mbaas ホストが設定されている限りすべての OpenShift 2 ターゲットにデプロイできます。