Things Cloud Web SDK アプリケーション構成

アプリケーション構成

Web SDK で作成されたすべてのアプリケーションは、カスタムビルドを通じて完全にカスタマイズ可能です。アプリケーションを構築せずにブランディングと構成オプションを活用することをお勧めします。これにより、この構成を複数のアプリケーション間で共有できるようになります。このセクションでは、まず「ビルドなしのオプション」について概説し、その後、構築されたアプリケーションをカスタマイズする方法を詳しく説明します。

アプリケーションオプション

アプリケーションをカスタマイズする最も簡単なオプションは、アプリケーションオプションです。これはすべての Web SDK アプリケーションに適用され、継承を使用することで、すべてのアプリケーションに同じ構成を適用できます。設定の一例としては、hideNavigator があります。これは、アプリケーションの起動時にナビゲータを表示するかどうかを構成するシンプルなフラグです。これは 3 つの方法で構成できます。

URL パラメータ
動的パブリックオプション
静的プライベートオプション

継承に関しては、「URL パラメータ」オプションが最も高い権限を持ち、次に「動的パブリックオプション」と「静的プライベートオプション」が続きます。特定のオプションをテストするには、アプリケーションに URL パラメータを追加するだけです。例えば、ナビゲータを非表示にするには、URL apps/<<your-app-name>>/index.html?hideNavigator=true#/route を使用します。URL パラメータは、#ハッシュナビゲーションの前に設定する必要があります。

動的なパブリックオプションは、各 Web SDKベースのアプリケーションの起動時にリクエストされます。このオプションのデフォルトの取得 URL は dynamicOptionsUrl に保存され、デフォルトでは "/apps/public/public-options/options.json" に設定されています。コンテキストパスからわかるように、デフォルト設定はテナントにデプロイされたアプリケーションを指しています。このアプリケーションを独自に作成するには、public-options.zip という zip ファイルを作成し、options.json を追加します。

{
  hideNavigator: true
}

このアプリケーションをテナントにアップロードし、少なくとも 1 つのサブテナントに登録すると、すべての Web SDK ベースのアプリケーションはナビゲータがデフォルトで非表示になります。

備考

エンタープライズテナント（親テナント）のお客様の場合、このオプションを操作する最も簡単な方法は、管理のブランディングマネージャーを使用することです。これにより、JSON ファイルを手動で生成してアプリケーションをアップロードすることなく、ほとんどの設定を行うことができます。

静的プライベートオプションは、カスタムアプリケーションによってのみ定義できます。これは最下位レベルのオプションであり、上位のオプション (1 および 2) によって上書きできます。これらはプライベートであり、適用されている現在のアプリケーションにのみ適用されます。これらのオプションは、cumulocity.config.ts ファイルの runTime フラグメントに追加することで定義できます。

[...]
export default {
  runTime: {
    [...]
    hideNavigator: true
  },
}
[...]

cumulocity.config.ts ファイル内のオプションは、環境変数にアクセスすることでビルド時に動的に設定することもできます。

[...]
export default {
  runTime: {
    [...]
    hideNavigator: process.env.C8Y_HIDE_NAVIGATOR === 'true'
  },
}
[...]

環境変数 C8Y_HIDE_NAVIGATOR を true に設定してから ng build を介してアプリケーションをビルドすると、アプリケーションの動作を調整できます。Linux システムでは、次のように環境オプションを設定してビルドコマンドを実行できます。

C8Y_HIDE_NAVIGATOR=true ng build

例えば、アプリケーションに複数の「フレーバー」がある場合、cumulocity.config.ts 内の環境変数を使用して、異なるフレーバーを切り替えることもできます。

const flavor = process.env.C8Y_APP_FLAVOR || 'default';
let standardOptions: ConfigurationOptions = {
  runTime: {
    // [...]
    rightDrawer: true,
  },
  buildTime: {
    // [...]
  }
};

standardOptions.buildTime.brandingEntry = `./branding/branding-${flavor}.less`;
switch (flavor) {
  case 'customerA':
    standardOptions.runTime.hideNavigator = true;
    break;

  case 'customerB':
    standardOptions.runTime.hideNavigator = false;
    break;
}

export default standardOptions;

以下のコマンドで、さまざまなフレーバーをビルドできます。

C8Y_APP_FLAVOR=customerA ng build

オプションの動作を確認するには URL オプションを使用するか、または、プラットフォーム全体（ブランディング）でオプションを設定するには動的オプションを使用し、カスタムアプリケーションのデフォルトを設定するにはプライベート静的オプションを使用することをお勧めします。

利用可能なすべてのオプションを確認するには、アプリケーションのブランディングを参照してください。

アプリケーションのブランディング

ブランディングは、すべてのアプリケーションに必ず適用する必要があります。そのため、アプリケーションのブランディングには、動的なパブリックオプションを使用することをお勧めします。 brandingCssVars アプリケーションオプションに適切なデザイントークンを設定する必要があります。これらは、Things Cloud のすべてのデフォルトスタイルシートに適用される CSS 変数であり、あらゆる Web SDK アプリケーションにカスタムブランディングを表示します。 options.json は次のようになります。

{
  "brandingCssVars": {
    "--brand-primary": "#B10F2E",
    "--brand-complementary": "#DE7C5A",
    "--brand-dark": "#280000",
    "--brand-light": "#DE7C5A",
    "--palette-status-realtime" : "#f0f"
  }
}

hideNavigator などの他のオプションを追加したり、独自の CSS ファイルを追加したりすることもできます。

{
  "brandingCssVars": {
    "--brand-primary": "#B10F2E",
    "--brand-complementary": "#DE7C5A",
    "--brand-dark": "#280000",
    "--brand-light": "#DE7C5A",
    "--palette-status-realtime" : "#f0f"
  },
  "hideNavigator": true,
  "extraCssUrls": "./custom.css",
}

CSS ファイルには、独自のスタイルを追加できます。

h1 {
  color: #00f;
}

次の手順に従ってください。

ファイルを zip ファイルに圧縮し、ラッピングフォルダなしで zip のルートに配置します。
zip ファイル名を public-options.zip にします。
管理 > エコシステム > アプリケーション で、Web アプリケーションとしてアップロードします。
テナント > サブテナント で、アプリケーションをいずれかのテナントに登録します。

その後、アプリケーションの詳細ビューで新しい変数を使用して既存のアプリケーションを更新できます。

備考

エンタープライズテナント（親テナント）のお客様の場合、このオプションを操作する最も簡単な方法は、管理のブランディングマネージャーを使用することです。このフォームでは、JSON ファイルを手動で生成したりアプリケーションをアップロードしたりすることなく、ほとんどの設定を行うことができます。

@c8y/style の拡張によるスタイル設定

アプリケーションのスタイルには、LESS で作成されたグローバル CSS が使用されています。元の LESS ソースは npm パッケージの @c8y/style で配布されています。既存のスタイルを拡張することによって、アプリケーション設定の詳細まで変更できますが、多くの開発者は色やロゴ、フォントなど数個の変数を置き換えるだけで簡単に実現したいと思っているでしょう。

変数を上書きするには、Custom CSS Properties（CSS Variables とも呼ばれます）を利用できます。これにより、実行時またはビルドプロセス中に構成が可能になります。

プロジェクトが Angular CLI に基づいていることを確認してください（アップグレード版でも、最初から作成したものでも構いません）。
@c8y/style パッケージがインストールされていることを確認してください。インストールされていない場合は、次のコマンドを使用して npm から基本スタイルをインストールできます。

@import '~@c8y/style/main.less';

この例では、次のファイル構造を使用しています。

my-application
|   ...
│   angular.json
│   package.json
|   ...
└───src
    │   styles.less
    │   favicon.ico
    │   ...
    └─── assets
         │   logo.jpg
         │   ...

styles.less がすでに存在する場合、ファイルの先頭に @import '~@c8y/style/main.less' の行を追加します。存在しない場合は、作成して上記の行を追加します。また、プロジェクトエントリの下にある angular.json の styles エントリにも含めます。
cumulocity.config.ts ファイルで、buildTime エントリに brandingEntry: './src/styles.less' を追加します。

styles.less とは別の場所にある別のファイルを使用している場合、前の手順で説明したようにパスを調整してください。angular.json の brandingEntry と styles エントリの両方を正しく設定してください。

カスタマイズ例

現時点では、必要に応じて好きな変数を変更することが可能です。これらの変更を実装するには、次の例に従い、指定されたコードを styles.less ファイルに追加してください。

例として、ブランディングで最も重要な brand-primary と呼ばれるメインカラーを変更してみましょう。

それぞれの CSS 変数を新しい色に変更することでメインカラーを変更できます。

:root {
  --brand-primary: red;
}

ボタンや有効になっているナビゲーションノード、有効になっているタブ、ホバー状態のボタンのようなユーザーインターフェース要素が赤色に変化しました。

ブランドロゴを変更するには、次のコードを使用します。

:root {
  --brand-logo-img: url('/apps/<applicationContextPath>/assets/logo.jpg');
  --brand-logo-img-height: 48%;
}

applicationContextPath には、プラットフォームにアップロードした logo.jpg ファイルを含む任意のアプリケーションを指定できます。

言語のカスタマイズ

言語の国際化に使用されているプラットフォーム UI 文字列は、gettext に保存されています。プラットフォームに新しい言語を追加したい場合、これらのファイルを編集するソフトウェアが必要です（Poedit など）。

翻訳されている各カタログは JSON 形式で実行時に読み込まれます。.po（gettext）拡張子のファイルを .json ファイルに変換するには、最初の手順でインストールした @angular/cli を使用します。

ビルド時に独自翻訳の追加方法

@c8y/ngx-components@1004.0.6/locales/locales.pot から文字列カタログをダウンロードします（バージョン1004.0.6以降では、latest を現在使用しているバージョンに変更することができます）。
ダウンロードした locales.pot テンプレートファイルを、任意の .pot ファイルエディタにロードし、そこから新しい翻訳を作成します。翻訳対象言語（Afrikaansなど）を選択し、各文字列を翻訳します。必要な数の言語について、このプロセスを繰り返します。この手順の成果物として、各言語の .po カタログファイルができ上がります。これらのファイルは後続のバージョンで文字列を更新するときに使うため、安全な場所に保存しておいてください。
c8ycli を利用して、新しく作成された .po ファイルを .json ファイルへ変換します。

c8ycli locale-compile path/to/language.po

ui-assets フォルダへ生成された .json ファイルをコピーします。
public-options/options.json の language フラグメントを更新します。

languages?: {
  [langCode: string]: {
    name: string;
    nativeName: string;
    url: string;
  }
}

リポジトリにダウンロード可能なサンプルコードでは、次のようなウクライナ語への翻訳例があります。

[...]

export default {
  runTime: {
    [...]
    languages: {
      uk: {
        name: "Ukraine",
        nativeName: "українська",
        url: "/apps/public/ui-assets/uk.json"
      }
    }
  },
  buildTime: {
    [...]
  }
}
[...]

ログイン後、UI でインポートした言語を変更できます。これを行うには、右上のユーザーアイコンをクリックし、メニューから「ユーザー設定」を選択して、表示されるウィンドウで目的の言語を選択します。

実行時に独自翻訳の追加方法

特定の文字列を実行時に翻訳することができます。つまり、ビルドに含める必要はなく、単にアプリケーションオプションに追加するだけです。しかし、この考え方では、新しい言語を追加することはできません。新しい文字列を既存の言語に追加するか、特定の翻訳を既存の言語に揃えることしかできません。特定キーを翻訳するためには、アプリケーションオプションに次の構造を追加する必要があります。

  i18nExtra?: {
    [langCode: string]: {
      [key: string]: string;
    };
  };

例：
次のようにすると、独自のCookieバナーが翻訳されます。

[...]

export default {
  runTime: {
    [...]
    i18nExtra: {
      de: {
        "About cookies on Things Cloud": "Informationen zu Cookies in Things Cloud",
        "Click Agree and Proceed to accept cookies and go directly to the platform or click on Privacy Policy to see detailed descriptions of the used cookies.": "Klicken Sie auf Zustimmen und fortfahren, um Cookies zu akzeptieren und direkt zur Plattform zu gelangen, oder klicken Sie auf Datenschutzrichtlinie, um detaillierte Beschreibungen der verwendeten Cookies anzuzeigen."
      }
    }
  },
  buildTime: {
    [...]
  }
}
[...]