モジュラ開発に対する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アプリケーションにサード・パーティ・ツールまたはライブラリを追加できます。これを行うステップは、アプリケーションの作成に使用した方法によって異なります。

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
```
2. 新規ライブラリをパス・マッピング構成ファイルに追加します。
  1. appRootDir/src/js/path_mapping.jsonを編集するために開きます。
    
    ファイルの一部を次に示します。
```
{
 "baseUrl": "js",
  "use": "local",
  "cdns": {
    "jet": "https://static.oracle.com/cdn/jet/17.1.0/default/js",
    "css": "https://static.oracle.com/cdn/jet/17.1.0/default/css",
    "config": "bundles-config.js"
  },
  "3rdparty": "https://static.oracle.com/cdn/jet/17.1.0/3rdparty"
},
"libs": {
  "knockout": {
      ...
  },
...
```
    Oracle JETのCLIは、ローカルのpath_mapping.jsonファイルにエントリを追加することで、アプリケーションのサードパーティ・ライブラリの管理に役立ちます。
    
    path_mapping.jsonファイルのlibsマップにリストされているライブラリごとに、ビルド時に次の2つのアクションが実行されます。最初に、1つ以上のファイルがどこか(通常はappRootDir/node_modules)からappRootDir/web出力フォルダにコピーされます。次に、ライブラリへのパスを表すためにrequireJSパス値が作成されます。このパス値は、ビルドされたmain.jsファイルまたは最適化されたバンドルに挿入されます。TypeScriptを使用する場合、これは、ライブラリからのインポートの設計時に使用するパス名と同じである必要があります。
    次の例では、persistライブラリの既存のパス・マッピング・エントリを示します。これを分析して、各属性の処理内容と、上で定義した2つのビルド時のアクションとの関連について説明します。
```
1  | "persist": {
2  |   "cdn": "3rdparty",
3  |   "cwd": "node_modules/@oracle/oraclejet/dist/js/libs/persist",
4  |   "debug": {
5  |     "cwd": "debug",
6  |     "src": [
7  |       "**"
8  |     ],
9  |     "path": "libs/persist/debug",
10 |     "cdnPath": "persist/debug"
11 |   },
12 |   "release": {
13 |     "cwd": "min",
14 |     "src": [
15 |       "**"
16 |     ],
17 |     "path": "libs/persist/min",
18 |     "cdnPath": "persist/min"
19 |   }
20 | },
```
    - 行1: libsマップ・エントリの名前(この場合は"persist")です。この名前は、作成されるrequireJSパス・エントリの名前として使用されるため、インポート・パスでもあります。ビルドされたアプリケーションのappRootDir/web/js/libsフォルダの下に作成されるフォルダには、同じ名前が使用されます。
      
      ノート:
      アプリケーションでTypeScriptを使用する場合は、同じ名前のtsconfig.jsonファイルのpathsエントリも必要になります。
    - 行2 (オプション): cdn属性は、このライブラリの場所のCDNルートの名前を設定します。この場合、値は3rdpartyに設定され、Oracle CDN内の特定の場所にマップされます。自分で追加するサード・パーティ・ライブラリ(つまり、Oracle CDNに存在しないライブラリ)には、ライブラリを配置できる独自のCDNインフラストラクチャを維持しないかぎり、cdnまたはcdnPath値は指定しないでください。
    - 行3: ビルド時の各パス・マッピング・エントリの最初の役割は、ファイルをコピーすることです。この行のcwd属性は、ツールでコピーを開始する場所を示し、後続のパスはこのルートに対して相対的になります。これは通常、appRootDir/node_modules/<library>の下のフォルダです。
    - 行4から12: ここでのdebugセクションとreleaseセクションは同じですが、通常のビルドを行う場合はdebugセクションの仕様に従い、--releaseビルドを行う場合はreleaseセクションの仕様に従うという点が異なります。たとえば、後者のケースでは、リリース用に最適化されたアセットのみのコピーを許可できます。
    - 行5 (オプション): デバッグ・ビルドまたはリリース・ビルドのコンテキストでは、この2番目のcwd属性によって、後続のすべてのものについてコピー・ルートがさらに絞り込まれます。たとえば、persistライブラリの通常(デバッグ)ビルドを実行する場合、コピー・ルートはappRootDir/node_modules/@oracle/oraclejet/dist/js/libs/persist/debugで、デバッグのcwd値が最上位のcwd値に追加されます。また、このフォルダ名は出力で使用され、コピーされたファイルはappRootDir/web/js/libs/persist/debugディレクトリに配置されます。この属性はオプションです。省略すると、すべてのコピーはルートのcwdの場所に対する相対パスからコピーされ、宛先フォルダのルートに配置されます。
    - 行6: src属性には、ルートの場所からビルドされたアプリケーション(つまり、実行時に実際に必要なすべてのファイル)にコピーするすべてのファイルの配列が含まれます。ここで追加するパスは、特定のファイル名にすることも、グロブを使用して複数のファイルを一度に一致させることもできます。前述の例では、グロブ**が使用され、/debugフォルダ(サブフォルダを含む)からすべてがコピーされます。フォルダ構造は、/webディレクトリの下にコピーされた出力に保持されます。
    - 行9: path属性は、各パス・マッピング・エントリによって実行される2番目の役割に使用されます。この属性は、main.jsファイルに挿入されるrequireJSパスの値を定義します。前述の例では、requireJSパス・マッピングは"persist":"libs/persist/min"で、これはrequireJSロード・ルート(通常はappRootDir/web/js)に対する相対パスです。
    - 行10 (オプション): cdnPath属性はオプションであり、ライブラリのコピーをCDNに実際に配置した場合にのみ使用する必要があります。その場合、path_mapping.jsonファイルのuse属性が"local"ではなく"cdn"に設定されていると、生成されるrequireJSパス文では、path値(行9)ではなくこのcdnPath値が使用されます。このパスは、CDNに割り当てられ、そのライブラリのcdn属性で使用される別名によって定義されたCDNルートに対する相対パスです。“use”が“cdn”に設定されているが、ライブラリにCDN情報が含まれていない場合、ビルドはライブラリのローカル・コピーの使用にフォールバックされ、それに応じてrequireJSパスが設定されます。
  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属性はビルド・バージョンの格納先をそれぞれ指しています。
    
    path_mapping.jsonファイルで独自のライブラリ・エントリを定義する場合は、ojet buildコマンドを実行してそれをテストし、必要なすべてのファイルがappRootDir/web/js/libsディレクトリにコピーされていること、およびrequireJSパス・マッピングがビルドされたappRootDir/web/js/main.jsファイルに挿入されていることを確認する必要があります。
    
    ノート:
    
    コピーして変更する既存のライブラリ・エントリに"cdn": "3rdparty",が含まれている場合は、ライブラリの新しく作成されたエントリからその行を削除します。この行は、Oracleによって管理されるコンテンツ配布ネットワーク(CDN)上のOracle JETサードパーティ領域を参照します。ライブラリはそこでホストされないため、この行を残しておくと、存在しないURLにライブラリのパスをマップすることで、実行時にリリース・ビルドが失敗します。
    
    CDNを使用する場合は、CDNのURLをcdnPath属性のエントリに追加します。CDNからロードされたライブラリの使用の詳細は、「パス・マッピング・スクリプト・ファイルと構成オプションの理解」を参照してください。
3. プロジェクトでTypeScriptを使用する場合は、tsconfig.jsonファイルにpathsエントリを定義して、実行時に使用するのと同じパス名を設計時に使用してライブラリをインポートできるようにする必要もあります。該当するライブラリで、使用するタイプも提供されている場合は、パスでそのタイプを指し示して、エディタがそのライブラリの使用に対してTypeScriptサポートを提供できるようにする必要があります。次に、コマンドライン・ツールで作成されたOracle JETアプリケーションの既存のpathsエントリの例を示します。
```
"paths": {
  "ojs/*": [
    "./node_modules/@oracle/oraclejet/dist/types/*"
],
...
```
アプリケーションの作成にコマンドライン・ツールを使用しなかった場合は、次のステップを実行してツールまたはライブラリを追加します。
1. アプリケーションのjs/libsディレクトリに新しいディレクトリを作成し、このディレクトリに新しいライブラリおよび付随するファイルを追加します。
  
  たとえば、my-libraryというライブラリ名の場合は、my-libraryディレクトリを作成してmy-library.jsファイルおよび必要なファイルを追加します。使用可能な場合は縮小バージョンを追加していることを確認します。
2. RequireJSブートストラップ・ファイル(通常はmain.js)で、requirejs.config()定義のパス・マッピング・セクションにライブラリ・ファイルのパスを追加します。
  
  たとえば、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',
    ...
    'text': 'libs/require/text',
    'my-library': 'libs/my-library/my-library
  },
  require(['knockout', 'my-library'],
  // this callback gets executed when all 
  // required modules are loaded
  function(ko) 
  {
      // Add any start-up code that you want here
  }
);
```
  RequireJSを使用したアプリケーションのモジュールの管理の詳細は、「モジュラ開発に対するRequireJSの使用」を参照してください。
3. プロジェクトでTypeScriptを使用する場合は、tsconfig.jsonファイルにpathsエントリを定義して、実行時に使用するのと同じパス名を設計時に使用してライブラリをインポートできるようにする必要もあります。該当するライブラリで、使用するタイプも提供されている場合は、パスでそのタイプを指し示して、エディタがそのライブラリの使用に対してTypeScriptサポートを提供できるようにする必要があります。次に、コマンドライン・ツールで作成されたOracle JETアプリケーションの既存のpathsエントリの例を示します。
```
"paths": {
  "ojs/*": [
    "./node_modules/@oracle/oraclejet/dist/types/*"
 ],
...
```

サードパーティのツールおよびライブラリの追加のトラブルシューティング

ほとんどの場合、サード・パーティ・ツールまたはライブラリをOracle JETアプリケーションに追加するとき、次の3つのいずれかの状況で障害が発生します。

ブラウザ・ツールのネットワーク・パネルでの404エラー。
これが発生した場合、コピーしたセットからファイルが漏れていたか、選択したライブラリにダウンストリーム依存関係がある可能性があるため、追加のサード・パーティ・ライブラリを定義する必要があります。
ブラウザ・コンソール上のエラー・ダンプ。
これは、多くの場合、ライブラリの形式が正しくないことを示しています。詳細は、次の一般的な問題のリストを参照してください。
ライブラリの使用の失敗。

サード・パーティ・ライブラリとの統合の問題を診断する際、次の問題が頻繁に発生します。

ライブラリがブラウザ・ライブラリではありません。
開発者は、ブラウザではなく、Node.jsでの使用を想定したライブラリを使用することを選択する場合があります。ライブラリのドキュメントを読み、それがブラウザ・ライブラリであることを確認します。
ライブラリの形式が間違っています。
JavaScriptエコシステムには複数のライブラリ形式があり、ブラウザでの使用を目的としたものとそうでないものがあります。見つけたライブラリの形式が正しくないため、ロードできない可能性があります。

パス・マッピング・エントリで、使用可能な形式オプションのうちライブラリの正しいディストリビューションが使用されていることを確認します。実行時に使用するには、AMDまたはUMD形式のモジュールが必要です。または、外部ツールを使用して、あるモジュール形式から別のモジュール形式に変換することもできます。
ライブラリにランタイム依存関係があります。
ライブラリでは、必要なすべてのパスおよびモジュールを実行時に使用できるように、複数の依存関係をpath_mapping.jsonファイルに含めることが必要な場合があります。実行時にライブラリをロードする際、404エラーは多くの場合、ダウンストリーム依存関係が欠落していることが原因です。

ライブラリのドキュメントを読み、ライブラリ自体のpackage.jsonファイルを調べ、404エラーを詳細に確認してエラーを把握してください。
ライブラリには、特定のRequireJSパス名が必要です。
使用しているライブラリは、特定のパス名からロードされることが想定されているか、同じ方法で依存関係が設定されることが想定されている可能性があります。リソースをロードしようとすると、404エラーになります。

GETリクエストで送信されたパスから、何が起きているかを把握できるはずです。作成する必要があるパスの名前を設定してpath_mapping.jsonファイルを構成できるため、これをメタデータで修正して、すべてが機能するようにできます。
ライブラリには、コードをロードするためのスクリプト・タグが必要です。

ほとんどのライブラリはモジュール・ローダー・システムと互換性があり、AMD互換であると仮定すると、import文またはdefine()およびrequire()メソッドで機能します。ただし、場合によっては、モジュール・ローダーでコードをロードするのではなく、ページで<script>タグを使用してコードをロードする必要があります。

<script>タグを使用する必要があるのは、使用するJavaScriptライブラリがESM形式でのみ使用可能な場合です。AMD形式に変換しない場合は、<script>タグを使用してプロジェクトのルート・レベル(appRootDir/src/index.htmlファイル)にインポートします。

このような<script>タグを必要とするコードは、最新のモジュール開発と互換性のない方法でグローバルJavaScriptコンテキストと相互作用する可能性が高いため、注意してください。このような場合、ライブラリのドキュメントが、正しい方向へと導くのに役立ちます。

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アプリケーションのパフォーマンスの最適化」を参照してください。