6 Oracle JETアプリケーションへのサード・パーティ・ツールまたはライブラリの追加
Oracle JETアプリケーションにサード・パーティ・ツールまたはライブラリを追加できます。これを行うステップは、アプリケーションの作成に使用した方法によって異なります。
Oracle JETコマンドライン・ツールを使用してアプリケーションをスキャフォールドした場合は、ライブラリをインストールしてappRootDir/path_mapping.json
を変更します。他の方法でアプリケーションを作成し、RequireJSを使用している場合は、ライブラリをアプリケーションに追加してRequireJSブートストラップ・ファイル(通常はmain.js
)を更新します。
ノート:
このプロセスは、Oracle JETの開発者の利便性のために提供されています。Oracle JETでは追加のツールまたはライブラリをサポートしていないため、それらがOracle JETのその他のコンポーネントまたはツールキット機能で正しく機能することを保証できません。
Oracle JETアプリケーションにサード・パーティ・ツールまたはライブラリを追加するには、次のいずれかの手順を実行します。
-
コマンドライン・ツールでアプリケーションを作成した場合は、次のステップを実行します:
-
アプリケーションのルート・ディレクトリで、ターミナル・ウィンドウに次のコマンドを入力し、NPMを使用してライブラリをインストールします:
npm install library-name --save
-
新規ライブラリをパス・マッピング構成ファイルに追加します。
-
appRootDir/path_mapping.json
を編集するために開きます。ファイルの一部を次に示します。
{ "use": "local", "cdns": { "jet": "https://static.oracle.com/cdn/jet/17.0.0/default/js", "css": "https://static.oracle.com/cdn/jet/17.0.0/default/css", "config": "bundles-config.js" }, "3rdparty": "https://static.oracle.com/cdn/jet/17.0.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
パスが設定されます。
-
-
"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
属性のエントリに追加します。
-
- プロジェクトでTypeScriptを使用する場合は、
tsconfig.json
ファイルにpaths
エントリを定義して、実行時に使用するのと同じパス名を設計時に使用してライブラリをインポートできるようにする必要もあります。該当するライブラリで、使用するタイプも提供されている場合は、パスでそのタイプを指し示して、エディタがそのライブラリの使用に対してTypeScriptサポートを提供できるようにする必要があります。次に、コマンドライン・ツールで作成されたOracle JETアプリケーションの既存のpaths
エントリの例を示します。"paths": { "ojs/*": [ "./node_modules/@oracle/oraclejet/dist/types/*" ], ...
-
-
アプリケーションの作成にコマンドライン・ツールを使用しなかった場合は、次のステップを実行してツールまたはライブラリを追加します。
-
アプリケーションの
/libs
ディレクトリに新しいディレクトリを作成し、このディレクトリに新しいライブラリおよび付随するファイルを追加します。たとえば、
my-library
というライブラリ名の場合は、my-library
ディレクトリを作成してmy-library.js
ファイルおよび必要なファイルを追加します。使用可能な場合は縮小バージョンを追加していることを確認します。 -
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 } );
- プロジェクトでTypeScriptを使用する場合は、
tsconfig.json
ファイルにpaths
エントリを定義して、実行時に使用するのと同じパス名を設計時に使用してライブラリをインポートできるようにする必要もあります。該当するライブラリで、使用するタイプも提供されている場合は、パスでそのタイプを指し示して、エディタがそのライブラリの使用に対してTypeScriptサポートを提供できるようにする必要があります。次に、コマンドライン・ツールで作成されたOracle JETアプリケーションの既存のpaths
エントリの例を示します。"paths": { "ojs/*": [ "./node_modules/@oracle/oraclejet/dist/types/*" ], ...
-