@c8y/options/src/ApplicationOptions.d.ts

Cumulocity application options

import { IApplication, VersioningMatrix } from '@c8y/client';

/*
 * -----------------------------WARNING---------------------------------
 * This file has is an interface for packages/ngx-components/core/common/ApplicationOptions.
 * Any changes to this file must be reflected there, too.
 */
export interface ApplicationOptions {
  /** Application name (saved to the server). */
  name: string;
  /** Application context path (saved to the server). */
  contextPath: string;
  /** Application key (saved to the server). */
  key: string;
  /** The version of the application */
  version: string;
  /** The version of the used WebSDK version */
  webSdkVersion?: string;
  /** The description of the application */
  description?: string;
  /** The author of the application */
  author?: string;
  /** The license of the application */
  license?: string;
  /**
   * Set to `true` if the application is hybrid and uses Angular and AngularJS simultaneously.
   */
  upgrade?: boolean;
  /**
   * Path to the branding entry file. (Set it to false to disable any styling. You can handle the styling then on your own e.g. in an angular.json file using ng-cli)
   */
  brandingEntry?: string | boolean;
  /**
   * Enables all preview features in the application.
   */
  enableAllPreviewFeatures?: boolean;
  /**
   * Hides the feature preview section in the right drawer.
   */
  hidePreviewFeature?: boolean;
  /**
   * URL to dynamically fetched options.
   * If set to `true` or left undefined, an URL will be used based on the applications contextPath.
   * If set to `false`, no dynamic options will be fetched.
   * */
  dynamicOptionsUrl?: string | boolean;
  /** URL to favicon. */
  faviconUrl?: string;
  /** URL to `*.css` file which will replace default branding. */
  brandingUrl?: string;
  /** Enables the branding preview mode. If set to true, the `dynamicOptionsUrl` will be polled regularly for changes. In case the `lastUpdated` field of the dynamic options changes, the page is reloaded in order to apply the new branding. */
  brandingPreview?: boolean;
  /** Object with properties that will be converted to CSS custom variables. */
  brandingCssVars?: BrandingCssVars;
  /**
   * Allows for adding or overriding languages available in the application.
   *
   * Its keys are language codes and its values are objects with the following properties:
   *
   * - **name:** English name of the language,
   * - **nativeName:** native name of the language,
   * - **url:** full URL to JSON file with compiled translations;
   *    if not defined, translations will be loaded from `${localePath}/${langCode}.json.
   *
   * ```json
   * "languages": {
   *   "de": {
   *     "name": "German",
   *     "nativeName": "Deutsch",
   *     "url": "/apps/public/ui-assets/de.json"
   *   }
   * }
   * ```
   */
  languages?: Languages;
  /**
   * Allows for adding custom translations. It is an optional property.
   *
   * Its keys are language codes (https://cumulocity.com/docs/section/getting_started/#a-name-languages-a-available-languages)
   * and its values are objects with key-value pairs, where the key is the original string in English and the value - its translation.
   *
   * - **Home:** "Startseite"
   *
   * For example, you can add the translation of your custom cookie banner configured in the branding settings:
   * ```json
   * "i18nExtra": {
   *   "de": {
   *     "About cookies on Cumulocity IoT": "Informationen zu Cookies in Cumulocity IoT",
   *     "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."
   *   }
   * }
   * ```
   */
  i18nExtra?: I18nExtra;
  /** Array of URLs to additional `*.css` files to be loaded at runtime. */
  extraCssUrls?: string[];
  /** Stylesheet (CSS) that will be added at runtime. The string should actually contain the CSS not a path or URL to it. */
  extraCss?: string;
  /** Documentation links settings. */
  docs?: Docs;
  /** Application icon to be displayed in app switcher and header bar. */
  icon?: Icon;

  // These are the old options
  /** Hide application in app switcher (saved to the server). */
  noAppSwitcher?: boolean;
  /** HTML page title. */
  globalTitle?: string;
  /** Hide "powered by" and version info at the bottom of the navigator and in the right drawer. */
  hidePowered?: boolean;
  /** Hides the header bar */
  hideHeader?: boolean;
  /** Hides the "Platform information" in the right drawer, will overrule the "hidePowered" option */
  hidePlatformInformation?: boolean;
  /** Shows the link to support page. Accepts values:
   * false, hide the link
   * string, value of url to be shown
   */
  supportUrl?: boolean | string;
  /**
   * Replacement string for `user` field in audit logs for actions performed by a support user
   * (available placeholders: `{{support_user}}`, `{{supported_user}}`).
   */
  supportUserString?: string;
  /**
   * Disables realtime updates on the map widget and maps in general.
   */
  mapWidgetRealtimeDisabled?: boolean;
  /**
   * Allows to adjust the default pagesize of 100 items of the map widget and maps in general.
   */
  mapWidgetPageSize?: number;
  /**
   * Allows to hide the hint that there are more devices with geo coordinates then displayed on the map widget and maps in general.
   */
  mapWidgetHideMaxDeviceOnMapHint?: boolean;
  /** Enable or disable the right drawer. */
  rightDrawer?: boolean;
  /** Enable or disable breadcrumbs in the header for groups and devices (default: false). */
  breadcrumbs?: boolean;
  /** Collapse navigator on initial load. */
  hideNavigator?: boolean;
  /** Show tabs horizontally or vertically. */
  tabsHorizontal?: boolean;
  /** Additional link to display on login screen. */
  loginExtraLink?: LoginExtraLink | LoginExtraLink[];
  /** Enable or disable storage limitation feature. */
  storageLimitationFeatureEnabled?: boolean;
  /** Name of company handling support requests from app users (displayed in notification message). */
  companyName?: string;
  /** URL template for documentation links (default: `'${docsBaseUrl}${partialUrl}'`). */
  guideHrefTemplate?: string;
  /** Base URL for documentation links (include `{{ version }}` placeholder, if you want versioned links). */
  docsBaseUrl?: string;
  /** CSP string to be applied to `index.html` by replacing default values. */
  contentSecurityPolicy?: string;
  /** Enables cloud sensor wizard */
  sensorPhone?: boolean;
  /** Show or hide a newsletter subscription checkbox in edit user modal. */
  newsletter?: boolean;
  /** Cookie Banner configuration */
  cookieBanner?: CookieBannerConfiguration;
  /** Cookie preferences configuration. Here you can enable or disable cookie categories */
  cookiePreferences?: CookiePreferencesConfiguration;
  /** Message Banner configuration */
  messageBanner?: MessageBannerConfiguration;
  /** A key for the product experience software Gainsight. */
  gainsightKey?: string;
  /** Disable user tracking */
  disableTracking?: boolean;
  /** NgModule export for plugins. */
  exports?: PluginsExports[];
  /** List of imported remote plugins. */
  remotes?: RemotePlugins;
  /** If set to true, only remotes defined in the `remotes` query parameter will be loaded. */
  forceUrlRemotes?: boolean;
  /**
   * Defines if the application is a package. Packages can be distributed as blueprint or allow plugins.
   */
  isPackage?: boolean;
  /**
   * Defines what is contained in the package.
   */
  package?: 'plugin' | 'blueprint';
  /** The package source a application origins from as IApplication or simply the id of the source */
  source?: string | number | IApplication;
  /**
   * Allows to enable or disable context help, or to override the default base URL used to load its contents.
   * By default, the context help uses the same base URL as defined in the `docsBaseUrl` option
   * (if this option is undefined, then the following value will be used: `https://cumulocity.com`).
   * Alternatively, if a string is provided here, it'll be used as the base URL
   * and any `{{ version }}` placeholder will be replaced with the relevant docs version.
   */
  contextHelp?: boolean | string;
  /**
   * By default, cockpit and devicemanagement use the onlyRoots query to resolve root nodes. This
   * could lead to performance issues, if a customer has a lot of root nodes. Therefore you can disable
   * the use of this query with this flag.
   */
  disableOnlyRootsQuery?: boolean;
  /**
   * Allows to force showing the setup wizard.
   */
  forceSetup?: boolean;
  /**
   * Indicates if the application needs to show the setup wizard.
   */
  isSetup?: boolean;
  /**
   * By default a WebSDK app requires the user to be logged in.
   * In case you would like to develop just a static application, that does not require any kind of access to the backend,
   * you can use this flag to disable the login screen.
   * NOTE: not all WebSDK components support this, some might require the user to be logged in and won't work.
   */
  noLogin?: boolean;
  /**
   * Allows to opt out of supporting/loading plugins for this application.
   */
  noPlugins?: boolean;
  /**
   * Allows to opt out of the version warning which is shown in the dev tools.
   */
  noVersionWarning?: boolean;
  /**
   * Link to the sensor app.
   */
  sensorAppOneLink?: string;
  /**
   * Allows to set the map layers. If not set, defaults to open street map layer.
   */
  mapLayers?: MapTileLayer[];
  /**
   * Allows to set default configurations on the maps.
   */
  mapConfig?: MapDefaultConfig;
  /**
   * The URL used to lookup geo coordinates for a user provided address via [nominatim API](https://nominatim.org/release-docs/develop/api/Search/).
   * Can be set to empty to disable the find address feature on the location tab.
   * Uses: `https://nominatim.openstreetmap.org/search?format=json&q={searchTerm}` if not set.
   */
  mapNominatimUrl?: string;
  /**
   * The name of the root element. By default c8y-bootstrap.
   */
  rootTagName?: string;
  /**
   * Hides possibility to create typed dashboards for assets (and groups). If true, typed dashboards can be created only for devices.
   * It is true by default.
   */
  hideTypeDashboardForAssets?: boolean;
  /**
   * A matrix of versions indicating which versions of the application (key) are dependent on which version of a cumulocity component (API version and Web SDK version of the shell application currently supported, indicated by the value).
   * The versions of the dependent components can be indicated by a semver range.
   * ```json
   * {
   *  "1.0.0": {
   *    "sdk": ">=1016.0.0 <1017.0.0",
   *    "api": ">=1016.0.0 <1017.0.0"
   *  },
   *  "2.0.0": {
   *    "sdk": "~1017.0.0",
   *    "api": "~1017.0.0"
   *  },
   *  "3.0.0": {
   *    "sdk": ">=1018.0.0",
   *    "api": ">=1018.0.0"
   *  },
   * }
   * ```
   */
  versioningMatrix?: VersioningMatrix;
  /**
   * Is used for plugins to indicate their owner. Cumulocity plugins are marked with OFFICIAL label.
   */
  label?: string;
  /**
   * Defines the type of refresh mechanism used for alarms in the application.
   *
   * - **realtime:** Utilizes a realtime mechanism for updating alarms.
   * - **interval:** Utilizes HTTP polling at regular intervals to refresh the alarms.
   *
   * This setting allows to switch between realtime and interval-based refresh methods.
   */
  alarmsRefreshType?: 'interval' | 'realtime';
  /**
   * A map of import paths to their corresponding URLs.
   * This is used to resolve module paths when loading remote modules
   * (e.g. in the HTML-Widget). The keys are the import paths and the values are the URLs.
   *
   * You can also add a js file but need to copy it. Or you can add a node module name but
   * this need to have a single entry point. Otherwise you need to copy the files. A url can also
   * be used but you need to ensure that the CSP rules are not blocking the loading of the file.
   *
   * ```
   * {
   *  'my-widget': 'https://example.com/path/to/widget.js',
   *  'node-module': '@scope/my-node-module',
   *  'local-js': './my-local-file.js'
   * }
   * ```
   */
  importMap?: {
    [key: string]: string;
  };
  /**
   * Defines to which path the user will be redirected in case he is not logged in yet.
   *
   * This needs to be used for e.g. people who embed the application in an iframe in order to redirect to a none index.html file.
   */
  loginRedirectPath?: string;
}

export interface MapDefaultConfig {
  /**
   * The default zoom level to set on each new map.
   */
  zoomLevel?: number;
  /**
   * The default center position of each new map.
   */
  center?: [number, number];
}

export interface MapTileLayer {
  /**
   * The layer url in the specific leaflet format.
   */
  layerUrl: string;
  /**
   * Additional options. Note this options are not typed as leaflet should not be by default included. The type from leaflet is L.TileLayerOptions.
   */
  options: any;
  /**
   * A label to show to the end user.
   */
  label: string;
  /**
   * Define the order of the layers to be shown to the user. Highest priority first.
   */
  priority?: number;
  /**
   * Indicates whether the layer is an overlay layer or an base layer. Default is false.
   */
  isOverlay?: boolean;
}

export interface RemotePlugins {
  /**
   * A key value pair, while the value is an array of modules to load and the
   * key is the context path.
   * ```js
   * {
   *    'cockpit': ['HomeDashboardModule', 'DataExplorerDashboard'],
   *    'widget-package@1.0.0': ['ExtendedMapWidget']
   * }
   * ``
   */
  [key: string]: string[];
}

export interface PluginsExports {
  /**
   * The name of the plugin.
   */
  name: string;
  /**
   * The name of the Angular module class.
   */
  module: string;
  /**
   * The file path to the module typescript file.
   */
  path: string;
  /**
   * The path to the README file of the plugin.
   */
  readmePath?: string;
  /**
   * An short description about what the module does.
   */
  description?: string;
  /**
   * Allows to scope the plugin to certain applications.
   * Default is undefined, which means every application can import this plugin.
   *  - Use `self` to limit the plugin to the current application.
   *  - The `global` is atm not used, but planned for allowing this plugin to all applications at the same time.
   *  - The `self-optional` is used to add it as a possible plugin to the current application, without it being imported by default.
   */
  scope?: PluginsExportScopes;
}

/**
 * Tells how a plugin is scoped.
 *
 * - `'self'`: Limit the plugin to the current application. It is imported by default.
 * - `'global'`: Allows to add the plugin to a global scope, meaning it is imported to all applications at the same time.
 *   This is not used at the moment but planned to be implemented in the new branding editor.
 * - `'self-optional'`: Limit the plugin to the current application. The plugin is not imported by default.
 * - `''`: Like undefined, the plugin is available for any private application.
 */
export type PluginsExportScopes = 'self' | 'global' | 'self-optional' | '';

export interface CookieBannerConfiguration {
  /** Here you can set the title of Cookie Banner */
  cookieBannerTitle?: string;
  /** Here you can set the Text of Cookie Banner */
  cookieBannerText?: string;
  /** Here you can set the policyUrl of Cookie Banner */
  policyUrl?: string;
  /** Here you can set the version of the cookie policy. In case the version changes, users will need to re-accept the cookies. */
  policyVersion?: string;
}

export interface MessageBannerConfiguration {
  /** Content of message banner */
  messageBannerContent?: string;
  /** Enable or disable message banner */
  messageBannerEnabled?: boolean;
  /** Type of message banner */
  messageBannerType?: 'success' | 'warning' | 'danger' | 'info' | 'system';
}

export interface CookiePreferencesConfiguration {
  /** This category includes e.g. cookies related to logging in  */
  required?: boolean | string;
  /** This category includes e.g. tracking cookies  */
  functional?: boolean | string;
  /** This category includes e.g. cookies related to advertising  */
  marketing?: boolean | string;
}

export interface LoginExtraLink {
  url: string;
  label: string;
}

export interface Icon {
  class?: string;
  url?: string;
}

export interface Docs {
  /** Hide default links to documentation. */
  noDefault?: boolean;
  /** List of regex strings. Matching default docs URLs will be hidden. */
  excludeDefault?: string[];
  /** Additional links to be displayed. */
  links?: Links[];
}

export interface Links {
  /** Icon classes with `c8y-icon`, e.g. `c8y-icon c8y-icon-add-user` or `c8y-icon c8y-icon-device-connect`. */
  icon: string;
  label: string;
  url: string;
  type: 'doc' | 'quicklink';
}

export interface I18nExtra {
  [langCode: string]: I18nExtraLangCode;
}

export interface I18nExtraLangCode {
  [key: string]: string;
}

export interface Languages {
  [langCode: string]: LanguagesLangCode;
}

export interface LanguagesLangCode {
  name: string;
  nativeName: string;
  url?: string;
}

export interface BrandingCssVars {
  [key: string]: string;
}