Key Concepts #

This section covers all the basics needed to understand Portal, including information about the web app, configurations, and the build system.

The Web App #

The Pragma Portal web app is a single page application created with Vue.js, and the UI is built with the ant.d component library. In development, all the pages and styles are loaded directly and individually by the browser for faster builds and ease of debugging. For production, all the scripts and styles are bundled and minified.

The Portal can be found at the following locations when the engine is built and running.

Location #

The default Portal is located in web/portal/dist. The platform is pre-configured with default settings which can be built on and customized.

The Portal location is configured with portalSource:

game:
  pluginConfigs:
    GameOperatorGatewayNodeService.routePlugins:
      plugins:
        Portal:
          class: "pragma.gateway.FilePortalModulePlugin"
          config:
            portalSource: "web/portal/dist"
social:
  pluginConfigs:
    SocialOperatorGatewayNodeService.routePlugins:
      plugins:
        Portal:
          class: "pragma.gateway.FilePortalModulePlugin"
          config:
            portalSource: "web/portal/dist"

Non-managed customers will need to add configurations per shard that determine where the Portal should be served from. If the default Portal is being used, that location is web/portal/dist. If custom work has been added to the Portal, the correct location will need to be configured, such as 5-ext/portal/dist.

Pragma automatically handles updates for managed customers who customize Portal.

Commands #

commanddescription
make portal-initinitialize a Portal overlay for custom development
make portal-setupset up dependencies for Portal development
make portal-packagebuild the Portal for production
make portal-startstart a local development HTTP server
make portal-testrun unit tests

Authentication and Identity Providers #

Operators can log into the Portal using the Unsafe Provider. This login is intended as a test-only authentication source, and should not be used in production settings. Once other authentication methods have been configured, the Unsafe Provider method should be disabled by setting the canAuthenticate config value on the Unsafe Identity Provider to false.

social:
  serviceConfigs:
    UnsafeIdentityDaoConfig:
      canAuthenticate: false
      ...

Authentication identity providers can be enabled for portal login. For a full example of a valid configuration, look at the dropdown under Engine Configuration.

social:
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Discord:
          class: "pragma.account.DiscordIdentityProviderPlugin"
          config:
            operatorLoginEnabled: true
            showPortalLoginButton: true

Additional authentication providers can be added by configuring them to work with Pragma Engine and then setting the operatorLoginEnabled and showPortalLoginButton config properties to true on the provider’s config. For more information on configuring identity providers, visit the Identity Providers page.

Styles and Assets #

The .css and .less files that are found under /src/lib and /src/portlets are automatically loaded and served to the browser. Style declarations are global, so we recommend limiting the scope by using class wrappers or specific selectors.

Support for Less.js is enabled by default, and all .less files are automatically parsed and converted to CSS.

CSS and Less.js files that start with an underscore are considered partials and are ignored.

The src/assets folder contains static scripts and styles that need to be loaded by the browser before the app is started. This is usually used for JavaScript libraries or CSS frameworks that need to be globally available.

Assets should be manually added to the config using the assets.js and assets.css options. The file paths are relative to the src/assets folder and files are loaded in the specified order.

Example: Portal assets configuration
module.exports = {
  common: {
    "assets.js": [
      "js/lodash.js",
      "bootstrap/bootstrap.min.js"
    ],
    "assets.css": [
      "bootstrap/bootstrap.min.css"
    ],
  },
};

The Build System #

The Portal is built by combining a base layer with an overlay.

The base layer consists of the core pragma library, the Portal web app code, and default portlets.

  • pragma library: a globally available library
  • default portlets: services–full list found in /web/portal/src

The overlay layer is built on initialization when the make portal-init call is made. The overlay is created by default in 5-ext/portal/src, and contains everything needed to customize the Portal. Learn more about customizing the portal by visiting the Customization section.

Configurations #

Engine Configuration #

The dropdown below contains the full list of possible configuration options for the Portal. These should be registered in the relevant YAML file as needed.

Example: Default config
game:
  pluginConfigs:
    GameOperatorGatewayNodeService.routePlugins:
      plugins:
        Portal:
          class: "pragma.gateway.FilePortalModulePlugin"
          config:
            portalSource: "web/portal/dist"
            modules:
              1: "PlayerSupport"
              2: "GameServerManagement"
              3: "ContentCatalogs"
              4: "ContentCatalogsEditor"
            defaultModule: "PlayerSupport"
            redirectSignInToSocial: false
social:
  pluginConfigs:
    SocialOperatorGatewayNodeService.routePlugins:
      plugins:
        Portal:
          class: "pragma.gateway.FilePortalModulePlugin"
          config:
            portalSource: "web/portal/dist"
            modules:
              1: "Accounts"
              2: "GameTitleManagement"
            defaultModule: "Accounts"
            redirectSignInToSocial: false
    AccountService.identityProviderPlugins:
      plugins:
        Google:
          class: "pragma.account.GoogleIdentityProviderPlugin"
          config:
            operatorLoginEnabled: true
            showPortalLoginButton: true
            ...
        Discord:
          class: "pragma.account.DiscordIdentityProviderPlugin"
          config:
            operatorLoginEnabled: true
            showPortalLoginButton: true
            ...

Portal Configuration #

The Portal build system relies on the default base.js configuration file unless an override is found. This file contains detailed descriptions of all possible Portal configurations.

Users can override these settings by adding content to src/config/default.js. This file is created once the Portal initialize command is called. Implementing default.js will cause the Portal to override the default configuration and instead use the configurations found in this file.

The local-dev.js can be used as an overwrite for local development only.

Glossary #

termdescription
overlayA collection of files that extend, update, and configure the Portal. The overlay has a predefined folder structure which is created on init.
portletThe internal term used for a Portal service. Portlets can be found under the Services menu in the browser.
Builder Functions for portlet and pageThe definition of a portlet or a page, which is a simple JavaScript function that applies a dedicated API on the one parameter it receives–the portlet or the page object.
extensionA JavaScript file that exports a configuration object that defines a set of updates to existing Portal functionality and existing portlets.
UI componentsPlain Vue.js components defined with the Vue Composition API. The page builder allows inserting any number of components to a page and each component can import and use other components.
swappable componentsUI components that are marked as swappable and can be replaced by their respective ID using an extension.
the pragma libraryA global JavaScript library made available to all the .js scripts in the overlay, which exports functionality and components of the base Portal engine.
Development ToolsAn administrative section of the Portal, accessed by clicking the question mark icon in the top right of the screen or manually navigating to /#/development-tools.