モジュラ開発に対するRequireJSの使用

4 モジュラ開発に対するRequireJSの使用

Oracle JETには、サード・パーティのJavaScriptライブラリであるRequireJSが含まれており、必要なOracle JETライブラリのみをロードするためにアプリケーションで使用できます。RequireJSを使用すると、モジュールの遅延ロードの実装や、複数のモジュールを含むJavaScriptパーティションの作成もできます。

Oracle JETおよびRequireJSについて

RequireJSは、ライブラリ参照の管理を簡素化するJavaScriptファイルおよびモジュール・ローダーであり、コードの速度および品質を向上させるように設計されています。

RequireJSでは、モジュールとその依存性を非同期でロードするためのメカニズムを提供する、非同期モジュール定義(AMD) APIが実装されます。

Oracle JETのモジュール編成により、アプリケーション開発者は、各参照オブジェクトに対してrequire()コールを実行せずに必要な機能のサブセットをロードできます。各Oracle JETモジュールによってツールキットの1つの機能領域が表され、通常は複数のJavaScriptオブジェクトが定義されます。

Oracle JETライブラリを参照するためにRequireJSを使用する必要はありませんが、アプリケーションでOracle JETの国際化またはデータ視覚化コンポーネントを使用する場合に必要です。Oracle JETダウンロードにはRequireJSライブラリが含まれており、デフォルトでOracle JETスタータ・テンプレートおよびクックブックの例で使用されます。

RequireJSの詳細は、http://requirejs.orgを参照してください。

Oracle JETのモジュール編成について

次の表に、Oracle JETモジュールをリストし、説明と使用上のヒントを示します。この表を使用して、アプリケーションでロードする必要があるモジュールを決定します。アプリケーションでモジュールAPIと直接対話できる場合、モジュールによって返される使用可能なオブジェクトも表に示されています。アプリケーションは、通常、返されたオブジェクトに対して関数をコールするか、コンストラクタ関数を通じて新規オブジェクトをインスタンス化します。Oracle JETアプリケーションでのモジュール・ロードの詳細は、『Oracle® JavaScript Extension Toolkit (Oracle JET) APIリファレンス』のJETモジュール・ロードの概要に関する項を参照してください。

ノート:

非推奨になったojcore、ojvalidation-base、ojvalidation-datetimeおよびojvalidation-numberモジュールから以前に入手可能だった特定の機能は、自身のオブジェクトを返すリファクタされたモジュールによって提供されます。表は、どのモジュールがリファクタされたかを示しています。必要な機能の依存性リストで必要なモジュールを明示的にインポートして、そのクラスを使用する必要があります。

Oracle JETモジュール	リファクタ	使用可能なオブジェクト	説明	使用する場合
`ojs/ojmodel`	いいえ	`Collection` `Events` `Model` `OAuth` `URLError`	JET共通モデルのクラス	`OAuth`以外のすべてのOracle JET共通モデル・クラスは、Oracle JET `RESTDataProvider`クラスに置き換える必要があります。
`ojs/ojknockout-model`	いいえ	`KnockoutUtils`	Oracle JETの共通モデルをKnockout.jsに統合するためのユーティリティ	非推奨。Oracle JET `RESTDataProvider`クラスを使用します。
`ojs/ojcomponent`	いいえ	コンポーネントごとに異なる	Oracle JETコンポーネント・モジュール。例 `ojs/ojbutton` `ojs/ojtoolbar` `ojs/ojtabs` ほとんどのOracle JETコンポーネントには、小文字でハイフンがない同じ名前を持つ独自のモジュールがありますが、次のコンポーネントは除きます。 `oj-buttonset-`: `ojs/ojbutton` `oj-input-password`: `ojs/ojinputtext` `oj-text-area`: `ojs/ojinputtext` `oj-combobox-`: `ojs/ojselectcombobox` `oj-select-`: `ojs/ojselectcombobox` `oj-spark-chart`: `ojs/ojchart` `oj--gauge`: `ojs/ojgauge`	アプリケーション内のOracle JETコンポーネントに対応するコンポーネント・モジュールを使用します。
`ojs/ojknockout`	いいえ	`ComponentBinding`	ユーザー・インタフェースのHTML要素のグローバル属性に対するOracle JETのデータ・バインディング	データバインドされたグローバル属性(コロン(:)接頭辞を使用した属性)を持つHTML要素(JETカスタム要素を含む)、または(カスタム要素のグローバル属性に対して)[[..]]/{{..}}構文が使用されているHTML要素がアプリケーションに含まれている場合に使用します。
`ojs/ojcorerouter`	いいえ	`urlParamAdapter、urlPathAdapter` `CoreRouter、CoreRouterState`	シングルページ・アプリケーションにおけるルーティングを管理するためのクラス	シングルページ・アプリケーションでルーティングを管理する必要がある場合に使用します。
`ojs/ojmodule`	いいえ	`ModuleBinding`	シングルページ・アプリケーションのリージョン内でナビゲーションを実装するバインディング	シングルページ・アプリケーションで、ページ・リージョン内のナビゲーションを管理する必要がある場合に使用します。
`ojs/ojmodule-element`	いいえ	`ModuleElementAnimation`	シングルページ・アプリケーションのリージョン内でナビゲーションを実装するコンポーネント	シングルページ・アプリケーションで、ページ・リージョン内のナビゲーションを管理する必要がある場合に使用します。
`ojs/ojmoduleanimations`	いいえ	`ModuleAnimations`	`ojs/ojmodule-element`とともに使用されます。CSSアニメーション効果によってアニメーション・サポートを追加します。	アプリケーションでアニメーション効果を追加する場合に使用します。
`ojs/ojcontext`	はい(`ojcore`から)	`BusyContext、Context`	現在アニメーションを実行しているか、データをフェッチしているコンポーネントを追跡する`BusyContext`を公開するクラス。	アプリケーションでページのコンポーネントのビジー状態を問い合せる必要がある場合に使用します。
`ojs/ojconfig`	はい(`ojcore`から)	`Config`	構成オプションを設定および取得するクラス。	アプリケーションでアプリケーション構成の詳細を設定または取得する必要がある場合に使用します。
`ojs/ojlogger`	はい(`ojcore`から)	`Logger`	ログ出力を設定してログ情報を収集するユーティリティ	アプリケーションでログ出力コールバック関数を定義する必要がある場合に使用します。
`ojs/ojresponsiveutils`	はい(`ojcore`から)	`ResponsiveUtils`	レスポンシブ画面の幅と範囲を操作するユーティリティ。`ojs/ojresponsiveknockoututils`と組み合せて、レスポンシブ・ページの動作を促すために使用できるknockoutのobservableを作成する場合によく使用されます。	アプリケーションがレスポンシブ・ページ・デザインで動作する必要がある場合に使用します。
`ojs/ojthemeutils`	はい(`ojcore`から)	`ThemeUtils`	テーマ情報を取得するユーティリティ	アプリケーションでテーマのフォントまたはターゲット・プラットフォームについて知る必要がある場合に使用します。
`ojs/ojtimeutils`	はい(`ojcore`から)	`TimeUtils`	時間情報のユーティリティ	アプリケーションで範囲内の指定された時点の位置を計算する必要がある場合に使用します。
`ojs/ojtranslation`	はい(`ojcore`から)	`Translations`	翻訳済リソースを取得するサービス	アプリケーションで翻訳済リソースを使用する必要がある場合に使用します。
`ojs/ojattributegrouphandler`	いいえ	`AttributeGroupHandler、ColorAttributeGroupHandler、ShapeAttributeGroupHandler`	属性グループを管理するクラス	アプリケーションでデータ・セット値(キー値のペア)から属性値を生成する必要がある場合に使用します。
`ojs/ojknockouttemplateutils`	いいえ	`KnockoutTemplateUtils`	Knockoutテンプレートを、JETコンポーネントのレンダラAPIで使用できるレンダラ関数に変換するユーティリティ	アプリケーションでKnockoutテンプレートを使用する必要がある場合に使用します。
`ojs/ojresponsiveknockoututils`	いいえ	`ResponsiveKnockoutUtils`	レスポンシブ・ページ・デザインを実装するためにKnockoutのobservableを作成するユーティリティ	アプリケーションでレスポンシブ・ページ・デザインのobservableを作成する必要がある場合に使用します。
`ojs/ojswipetoreveal`	いいえ	`SwipeToRevealUtils`	オフキャンバス要素上で表示するためにスワイプを設定および処理するユーティリティ	アプリケーションでスワイプ・ジェスチャをサポートする必要がある場合に使用します。
`ojs/ojkeyset`	いいえ	`KeySet、KeySetImpl、AllKeySetImpl`	`ojTable`、`ojListView`および`ojDataGrid`コンポーネントの選択項目を操作するクラス	アプリケーションでセットとして選択を操作する必要がある場合に使用します。
`ojs/ojdiagram-utils`	いいえ	`DiagramUtils`	`ojDiagram`コンポーネントをサポートするためにJSONオブジェクトを操作するユーティリティ	アプリケーションでJSONオブジェクトから`ojDiagram`コンポーネントを作成する場合に使用します。
`ojs/ojoffcanvas`	いいえ	`OffcanvasUtils`	オフキャンバス・リージョンを制御するクラス	アプリケーションでオフキャンバス・リージョンを管理する必要がある場合に使用します。
`ojs/ojcube`	いいえ	`Cube、CubeAggType、CubeAxis、CubeAxisValue、CubeCellSet、CubeDataValue、CubeHeaderSet、CubeLevel、DataColumnCube、DataValueAttributeCube`	`ojDataGrid`のデータ値を集計するクラス	アプリケーションで、`ojDataGrid`コンポーネントの集計済キューブ・データをレンダリングする場合に使用します。
`ojs/ojtypedataprovider`	いいえ	`ArrayDataProvider、ArrayTreeDataProvider、CollectionDataProvider、DeferredDataProvider、FlattenedTreeDataProvider、IndexerModelTreeDataProvider、ListDataProviderView、PagingDataProviderView、TreeDataProviderView` `FilterFactory`	データ・プロバイダ・モジュール。たとえば、次のものがあります: `ojs/ojarraydataprovider` `ojs/ojcollectiondataprovider` `ojs/ojtreedataprovider`	アプリケーションにOracle JETコンポーネントが含まれていて、そのデータ・ソースが`*DataProvider`クラスのいずれかで定義されている場合に使用します。
`ojs/ojtimezonedata`	いいえ	使用可能なパブリック・クラスなし	タイムゾーンのデータ	`oj-input-date-time`、`oj-input-time`またはコンバータにタイムゾーン・サポートを追加する場合に使用します。
`ojconverter-color`、`ojconverter-datetime`、`ojconverter-number`	はい(`ojvalidation-base`、`ojvalidation-datetime`または`ojvalidation-number`から)	`ColorConverter`、`converterDateTime`、`converterColor`	色、日付および時刻変換サービス。	アプリケーションで変換サービスをサポートする必要がある場合に使用します。
`ojvalidator-daterestriction`、`ojvalidator-datetimerange`、`ojvalidator-length`、`ojvalidator-numberrange`、`ojvalidator-regexp`、`ojvalidator-required`	はい(`ojvalidation-base`、`ojvalidation-datetime`または`ojvalidation-number`から)	`DateRestrictionValidator`、`DateTimeRangeValidator`、`LengthValidator`、`NumberRangeValidator`、`RegExpValidator`、`RequiredValidator`	日付および数値検証サービス。	アプリケーションで検証サービスをサポートする必要がある場合に使用します。
`ojasyncvalidator-daterestriction`、`ojasyncvalidator-datetimerange`、`ojasyncvalidator-length`、`ojasyncvalidator-numberrange`、`ojasyncvalidator-regexp`、`ojasyncvalidator-required`	はい(`ojvalidation-base`、`ojvalidation-datetime`または`ojvalidation-number`から)	`AsyncDateRestrictionValidator`、`AsyncDateTimeRangeValidator`、`AsyncLengthValidator`、`AsyncNumberRangeValidator`、`AsyncRegExpValidator`、	非同期の日付および番号検証サービス。	アプリケーションで非同期検証サービスをサポートする必要がある場合に使用します。

Oracle JETアプリケーションでのRequireJSについて

Oracle JETには、RequireJSライブラリとサンプルのブートストラップ・ファイルがOracle JETダウンロードに含まれています。

次のコードは、appRootDir\node_modules\@oracle\oraclejet\dist\js\libs\oj\ディレクトリのOracle JET基本配布で配布されるmain-template.jsブートストラップ・ファイルの一部を示しています。通常、ブートストラップ・ファイルはアプリケーションのjsディレクトリに配置し、名前をmain.jsに変更します。コードのコメントに、各セクションの目的が記述されています。通常編集するセクションは、太字で強調表示されています。

/**
 * Example of Require.js boostrap javascript
 */
(function () {
    requirejs.config({
      // Path mappings for the logical module names
      paths: {

      },

      // This section configures the i18n plugin. It is merging the Oracle JET built-in translation
      // resources with a custom translation file.
      // Any resource file added, must be placed under a directory named "nls". You can use 
      // a path mapping or you can define a path that is relative to the location 
      // of this main.js file.
      config: {
        ojL10n: {
          merge: {
            // 'ojtranslations/nls/ojtranslations': 'resources/nls/myTranslations'
          }
        },
        text: {
          // Override for the requirejs text plugin XHR call for loading text 
          // resources on CORS configured servers
          // eslint-disable-next-line no-unused-vars
          useXhr: function (url, protocol, hostname, port) {
            // Override function for determining if XHR should be used.
            // content omitted for brevity
            // Return true or false. true means "use xhr", false 
            // means "fetch the .js version of this resource".
            return true;
          }
        }
      }
    });
  }());
  
  /**
   * A top-level require call executed by the app.
   * Although 'ojcore' and 'knockout' would be loaded in any case (they are specified as dependencies
   * by the modules themselves), we are listing them explicitly to get the references to the 'oj' and 'ko'
   * objects in the callback.
   *
   * For a listing of which JET component modules are required for each component, see the specific component
   * demo pages in the JET cookbook.
   */
  require(['ojs/ojcore', 'knockout', 'jquery', 'ojs/ojknockout', 'ojs/ojbutton', 'ojs/ojtoolbar', 'ojs/ojmenu'], 
     // add additional JET component modules as needed
    // eslint-disable-next-line no-unused-vars
    function (oj, ko, $) { // this callback gets executed when all required modules are loaded
        // add any startup code that you want here
    }
  );

示されているように、RequireJSを通常のアプリケーションで使用できます。または、RequireJSをoj-module要素とともに使用して、シングルページ・アプリケーションのページ・セクションに対するビュー・テンプレートおよびviewModelを定義することができます。たとえば、ユーザーがナビゲーション・ボタンの1つをクリックした場合、Oracle JETスタータ・テンプレートで、RequireJSとともにoj-module要素を使用して様々なviewおよびviewModelを使用します。

Oracle JETスタータ・テンプレートの詳細は、「スタータ・テンプレートについて」を参照してください。ojModuleおよびテンプレートの使用の詳細は、「シングルページ・アプリケーションの作成」を参照してください。

Oracle JETアプリケーションでのRequireJSの使用

アプリケーションでRequireJSを使用するには、ブートストラップ・ファイルを編集して、必要なOracle JETモジュールを追加します。また、必要に応じて、アプリケーション・コードに独自のモジュールを追加することもできます。

必要な場合は、Oracle JETをインストールし、http://requirejs.orgにあるRequireJSをインストールします。

Oracle JETアプリケーションでRequireJSを使用するには:

ブートストラップ・ファイルまたはアプリケーション・スクリプトのrequire()定義で、必要に応じて別のOracle JETモジュールを追加します。
アプリケーションで使用するスクリプトをrequire()定義に追加し、function(ko)定義を更新してそのスクリプトを含めます。
コールバック関数にアプリケーション起動コードを追加します。
アプリケーションにリソース・バンドルが含まれている場合は、バンドルへのパスをmergeセクションに入力します。

次に、ステップの例を順番に示します。

アプリケーションは、Knockoutと統合されたOracle JET共通モデルを使用し、oj-dialogを含みます。強調表示されたモジュールをブートストラップ・ファイルまたはアプリケーション・スクリプトに追加します。

require(['knockout', 'ojs/ojmodel', 'ojs/ojknockout-model','ojs/ojdialog'],
  function(ko) // obtaining a reference to the oj namespace
  {
  }
);

その後、myapp.jsというスクリプトを使用するため、強調表示されたコードをrequire()定義に追加します。

require(['myapp', 'knockout', 'ojs/ojmodel', 'ojs/ojknockout-model', 'ojs/ojdialog'],
  function(myapp, ko) // obtaining a reference to the oj namespace
  {
  }
);

次に、dialogWrapperという要素のKnockoutバインディング・コールを含めます。これをコールバック関数に追加します。

require(['myapp', 'knockout', 'ojs/ojmodel', 'ojs/ojknockout-model', 'ojs/ojdialog'],
  function(myapp, ko) // obtaining a reference to the oj namespace
  {
    ko.applyBindings(new app()/*View Model instance*/,
                     document.getElementById('dialogWrapper'));
  }
);

最後に、翻訳バンドルを含めるため、これをmergeセクションに追加します。

config: {
  ojL10n: {
    merge: {
      'ojtranslations/nls/ojtranslations': 'resources/nls/myTranslations'
    }
  }
}

Oracle JETアプリケーションでのモジュール・ロードの詳細は、『Oracle® JavaScript Extension Toolkit (Oracle JET) APIリファレンス』のJETモジュール・ロードの概要に関する項を参照してください。

Oracle JETアプリケーションへのサード・パーティ・ツールまたはライブラリの追加

Oracle JETアプリケーションにサード・パーティ・ツールまたはライブラリを追加できます。実行するステップは、アプリケーションの作成に使用した方法によって異なります。

コマンドライン・ツールを使用してアプリケーションをスキャフォールドした場合は、ライブラリをインストールしてappRootDir/src/js/path_mapping.jsonを変更します。他の方法でアプリケーションを作成し、RequireJSを使用している場合は、ライブラリをアプリケーションに追加してRequireJSブートストラップ・ファイル(通常はmain.js)を更新します。

ノート:

このプロセスは、Oracle JETの開発者の利便性のために提供されています。Oracle JETでは追加のツールまたはライブラリをサポートしていないため、それらがOracle JETのその他のコンポーネントまたはツールキット機能で正しく機能することを保証できません。

Oracle JETアプリケーションにサード・パーティ・ツールまたはライブラリを追加するには、次のいずれかを実行します:

コマンドライン・ツールでアプリケーションを作成した場合は、次のステップを実行します。
1. メイン・プロジェクト・ディレクトリで、ターミナル・ウィンドウに次のコマンドを入力し、npmを使用してライブラリをインストールします。
```
npm install library-name --save
```
  たとえば、my-libraryという名前のライブラリをインストールするには、次のコマンドを入力します。
```
npm install my-library --save
```
2. 新規ライブラリをパス・マッピング構成ファイルに追加します。
  1. appRootDir/src/js/path_mapping.jsonを編集するために開きます。
    
    ファイルの一部を次に示します。
```
{
  "baseUrl": "js",
  "use": "local",

  "cdns": {
    "jet": "https://static.oracle.com/cdn/jet/16.0.0/default/js",
    "css": "https://static.oracle.com/cdn/jet/16.0.0/default/css",
    "config": "bundles-config.js"
    },
    "3rdparty": "https://static.oracle.com/cdn/jet/16.0.0/3rdparty"
  },

  "libs": {

    "knockout": {
      "cdn": "3rdparty",
      "cwd": "node_modules/knockout/build/output",
      "debug": {
        "src": "knockout-latest.debug.js",
        "path": "libs/knockout/knockout-#{version}.debug.js",
        "cdnPath": "knockout/knockout-3.x.x"
      },
      "release": {
        "src": "knockout-latest.js",
        "path": "libs/knockout/knockout-#{version}.js",
        "cdnPath": "knockout/knockout-3.x.x"
      }
    },

... contents omitted
```
  2. "libs"内にある既存のエントリのいずれかをコピーし、ライブラリの必要に応じて変更します。
    
    次のサンプルは、縮小バージョンとデバッグ・バージョンの両方が含まれるライブラリmy-libraryのための変更を示しています。
```
...
 "libs": {

    "my-library": {
      "cwd": "node_modules/my-library/dist",
      "debug": {
        "src": "my-library.debug.js",
        "path": "libs/my-library/my-library.debug.js"
      },
      "release": {
        "src": "my-library.js",
        "path": "libs/my-library/my-library.js"
      }
    },
...
```
    この例で、cwdはnpmによってライブラリがインストールされた場所、srcはビルド時にコピーされるファイルが格納されているパスまたはパスの配列、pathはビルド・バージョンの格納先をそれぞれ指しています。
    
    ノート:
    
    コピーして変更する既存のエントリに"cdn": "3rdparty",が含まれている場合は、ライブラリの新しく作成されたエントリから削除します。この行は、Oracleによって管理されるコンテンツ配布ネットワーク上のOracle JETサードパーティ領域を参照します。ライブラリはそこでホストされないため、この行を残しておくと、存在しないURLにライブラリのパスをマップすることで、実行時にリリース・ビルドが失敗します。
    
    CDNを使用する場合は、CDNのURLをcdnPathのエントリに追加します。
アプリケーションの作成にツールを使用しなかった場合は、次のステップを実行してツールまたはライブラリを追加します。
1. アプリケーションのjs/libsディレクトリに新しいディレクトリを作成し、このディレクトリに新しいライブラリおよび付随するファイルを追加します。
  
  たとえば、my-libraryというライブラリ名の場合は、my-libraryディレクトリを作成してmy-library.jsファイルおよび必要なファイルを追加します。使用可能な場合は縮小バージョンを追加していることを確認します。
2. RequireJSブートストラップ・ファイル(通常はmain.js)で、パス・マッピング・セクションに新しいファイルへのリンクを追加し、require()定義に新しいライブラリを含めます。
  
  たとえば、my-libraryという名前のライブラリを使用するには、強調表示された次のコードをブートストラップ・ファイルに追加します。
```
requirejs.config({
  // Path mappings for the logical module names
  paths: 
  {
    'knockout': 'libs/knockout/knockout-3.x.x',
    'jquery': 'libs/jquery/jquery-3.x.x.min',
    ... contents omitted
    'text': 'libs/require/text',
    'my-library': 'libs/my-library/my-library
  },
  require(['knockout', 'my-library'],
  function(ko) // this callback gets executed when all required modules are loaded
  {
      // add any startup code that you want here
  }
);
```
  RequireJSを使用したアプリケーションのモジュールの管理の詳細は、「モジュラ開発に対するRequireJSの使用」を参照してください。

Oracle JETアプリケーションでのRequireJSのトラブルシューティング

RequireJS問題は、使用されているが定義されていないモジュールに関することがよくあります。

RequireJSが原因と思われるOracle JETアプリケーションに関する問題をトラブルシューティングする場合は、次のヒントを使用してください:

JavaScriptコンソールでエラーおよび警告をチェックします。ojネームスペースの特定のオブジェクトが未定義の場合は、「Oracle JETのモジュール編成について」またはOracle JETクックブックの情報に基づいてそれを含むモジュールを特定し、アプリケーションに追加します。
Knockout.jsバインディングを使用して指定したコンポーネントが表示されず、エラーまたは警告が表示されていない場合は、ojs/ojknockoutモジュールをアプリケーションに追加していることを確認してください。

Oracle JETアプリケーションでのJavaScriptパーティションおよびRequireJSについて

RequireJSでは、複数のモジュールを含むJavaScriptパーティションがサポートされています。

RequireJSのbundlesオプションを使用してすべてのモジュールに名前を付けて、構成オプションにパス・マッピングを提供する必要があります。

requirejs.config(
  {
    bundles:
    {
      'commonComponents': ['ojL10n', 'ojtranslations/nls/ojtranslations',
                           'ojs/ojknockout', 'ojs/ojcomponentcore',
                           'ojs/ojbutton', 'ojs/ojpopup'],
      'tabs': ['ojs/ojtabs', 'ojs/ojconveyorbelt']    }
  }
);

この例では、2つのパーティション・バンドルcommonComponentsとtabsが定義されます。

RequireJSには、パーティションを作成し、JavaScriptコードを削減するための独自のオプティマイザ・ツールが同梱されています。ツールは、RequireJSを使用するようにすでに構成されている完全なプロジェクトによって、ビルド時に使用されるように設計されています。静的な依存性をすべて分析し、常に一緒にロードされるモジュールからパーティションを作成します。Oracle JETチームでは、オプティマイザを使用してモジュールのダウンロードに必要なHTTPリクエストの数を最小化することをお薦めします。

RequireJS Optimizerツールの詳細は、http://requirejs.org/docs/optimization.htmlを参照してください。

Oracle JETアプリケーションのパフォーマンスの最適化の詳細は、「Oracle JETアプリケーションのパフォーマンスの最適化」を参照してください。