1. 仮想DOMアーキテクチャを使用したOracle JETアプリケーションの開発
  2. Oracle JETアプリケーションへのサード・パーティ・ツールまたはライブラリの追加

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

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

Oracle JETコマンドライン・ツールを使用してアプリケーションをスキャフォールドした場合は、ライブラリをインストールしてappRootDir/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/path_mapping.jsonを編集するために開きます。

        ファイルの一部を次に示します。

        {

  "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属性のエントリに追加します。

    3. プロジェクトでTypeScriptを使用する場合は、tsconfig.jsonファイルにpathsエントリを定義して、実行時に使用するのと同じパス名を設計時に使用してライブラリをインポートできるようにする必要もあります。該当するライブラリで、使用するタイプも提供されている場合は、パスでそのタイプを指し示して、エディタがそのライブラリの使用に対してTypeScriptサポートを提供できるようにする必要があります。次に、コマンドライン・ツールで作成されたOracle JETアプリケーションの既存のpathsエントリの例を示します。
      "paths": {
  "ojs/*": [
    "./node_modules/@oracle/oraclejet/dist/types/*"
],
...

  • アプリケーションの作成にコマンドライン・ツールを使用しなかった場合は、次のステップを実行してツールまたはライブラリを追加します。

    1. アプリケーションの/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
  }
);
    3. プロジェクトでTypeScriptを使用する場合は、tsconfig.jsonファイルにpathsエントリを定義して、実行時に使用するのと同じパス名を設計時に使用してライブラリをインポートできるようにする必要もあります。該当するライブラリで、使用するタイプも提供されている場合は、パスでそのタイプを指し示して、エディタがそのライブラリの使用に対してTypeScriptサポートを提供できるようにする必要があります。次に、コマンドライン・ツールで作成されたOracle JETアプリケーションの既存のpathsエントリの例を示します。
      "paths": {
  "ojs/*": [
    "./node_modules/@oracle/oraclejet/dist/types/*"
 ],
...