There was a problem loading the comments.

UI Modules Configuration

Support Portal  »  Knowledgebase  »  Viewing Article

  Print

UI Modules Configuration

Overview

The Prime Customer Portal is an application shell which allows installing pluggable modules - pages and reusable services. In fact most of the functionality is moved into separate modules which are a combination of Express controllers (packaged with npm) and AngularJS modules (packaged with Bower).

How To Toggle Modules On/Off

You can toggle Prime modules on/off by running:

npm run configure

This will run our application configurator CLI which will offer you the opportunity to choose the modules you want to activate or disable. After you have chosen the modules you want to be activated, you will be presented with a summary of what npm and Bower packages will be installed or uninstalled. You have to confirm you want to save your configuration, otherwise no changes will be persisted. After you have saved your changes, you have to run npm install && bower install in order to download/remove the newly declared dependencies. You should also run the build process: npm run build (for production) or npm run ng:dev (for development) in order for the changes in the configuration to take effect in the application.

The CLI configurator will make changes to the following files:

  • modules.config.json - will toggle the active property to true or false according to your choice. No entries will be removed from the file automatically.
  • package.json - will add or remove Prime modules dependencies
  • bower.json - will add or remove Prime modules dependencies

It's not recommended to edit the modules.config.json file manually if you don't know what you are doing!

Configuration File Structure

The available modules are declared in the modules.config.json file. It contains a simple JSON array which has module declarations as its elements.

Here is an explanation for all of the module declaration properties:

{
  "name": "Cart", // the module name
  "description": "Provides shopping cart functionality", // the module description (optional)
  "active": true, // wheter the module is active or not
  "ui": { // the UI (AngularJS) configuration
    "package": "cart", // the Bower package name
    "version": "~0.2.0", // the Bower package version
    "group": "Payment", // the group name (section in the main menu)
    "lazyLoad": false, // wheter the module should be lazy-loaded or not
    "route": { // the UI-Router route definition
      "state": "cart", // the UI-Router state name
      "url": "/cart" // the root URL for the module,
    },
    "navigation": { // the navigation configuration (optional)
      "label": "Shopping cart", // the button label
      "icon": "shopping_cart", // the Material Icon name
      "badge": { // badge information (optional)
        "condition": "cart.total_items > 0", // when to display the badge
        "value": "cart.total_items" // what the badge value should be (evaluaded from the current scope)
      }
    }
  },
  "backend": { // backend (Node.js) configuration
    "controllers": [ // a list of API controllers (optional)
      {
        "package": "cart", // npm package name
        "version": "~0.1.0", // npm package version (you can prepend ~ and ^, otherwise the exact version will be used)
        "route": "/cart" // root API endpoint for the module
      },
      {
        "package": "product-suggestion",
        "version": "~0.1.0",
        "route": "/product-suggestion"
      },
      {
        "package": "payments",
        "version": "~0.1.0",
        "route": "/payment"
      }
    ],
  "websockets": [ // a list of WebSockets packages (optional)
      {
        "package": "live-chat", // npm package name
        "version": "~0.1.0" // npm package version
      }
    ]
  },
  "dependencies": [ // module dependencies (optional)
    "CustomerProducts" // list of module names
  ]
}

All of the Prime modules' npm and Bower package names match a certain pattern:

  • Bower: /^prime-customer-portal-.+-module$/
  • npm: /^apihawk-prime-customer-portal-.+-(controller|ws)$/

That's why you only have to provide the .+ part of the module name in the configuration. For example, if you want to include the apihawk-prime-customer-portal-awesome-controller, you should declare it like this:

  "package": "awesome"

Note: Dependency checking is not implemented yet.

Developing New Modules

If you are a developer and you want to extend the functionality of the Prime Customer Portal, you can create your own pluggable modules.

You can use the start project templates for AngularJS and Node.js where everything is configured to work with the Customer Portal project.

While you are developing the module, you can use bower link and npm link to link your packages with the main project. After you are done with developing the module, you have to publish your packages to npm and Bower.

There are some things you should keep in mind before you declare your module in the configuration file:

  • the module name should be in CamelCase
  • always include a description
  • you can only have one UI module declared in ui

    • UI modules are just AngularJS modules.
    • lazyLoad should be true if your module is a separate page which has its own routing and which doesn't expose any global functionality. For modules which are used globally, like the Cart one, you should set lazyLoad to false. Actually all of the modules are loaded separately from the main bundle, no matter if lazily (loaded on page navigation) or not (loaded just after the application is bootstrapped). In order to use an external module, you have to wait for it to be loaded first. You can do that wil the $ocLazyLoad service:

      \\n $ocLazyLoad.load("Cart").then(() => {\\n // Cart module is loaded, you can safely use it here\\n var $cart = $injector.get('$cart');\\n });\\n

    • you should define the navigation property only if your module will expose a link to itself from the main side navigation (the app-drawer)

      • you should always add a label and a material icon name
      • you can define a badge object inside of the ui.navigation property - this will add a small badge on the link to page which is useful if you want to display a counter, e.g. products count in the shopping card. It accepts a condition which will decide wheter to render the badge and value which will be an expression evaluated against $rootScope.
    • the route object exposes a regular UI Router state definition - state and url. These should match the root state declared in your module's route configuration!
    • group should only be provided if you expose a navigation object. It is used to group items by its value. It's useful if you want to group links in the navigation by category, e.g. Help Center and Live Chat should be in the group "Support", while Shopping Cart and Orders should be in "Payments".

  • you can have multiple backend packages in one module (you can also skip the back-end altogether)

    • you can add both controllers and websockets
    • all your API routes will be prefixed with /api, so if you declare your route as /awesome, the actual endpoint will be /api/awesome.
    • controllers items have an optional property api in which you can specify the API connector instance to pass into the controller constructor, e.g. "api": "helpCenter".

Share via

Related Articles

© ApiHawk