UI Module

Objective

UI Modules are graphical interfaces that offer the ability to send and retrieve information to the services APIs. They are located in soajs.dashboard under folder ui/modules/. SOAJS UI Dashboard is built on top of AngularJS which makes it a Single Page Applications (SPAs). The modules inside the UI are built to be loaded on demand and their controllers are registered upon loading.

This space will show you:

How to create a module
How to install a module
Module Controllers
Module Service
Module Directives
Module Permissions
Full Example

Creating a Module

Start by installing t he SOAJS dashboard.

Navigate to soajs.dashboard/ui/modules/ folder

Create your module by adding a folder myModule
Create the installation file and name it install.js

Folder Schema:

$ cd soajs.dashboard/ui/modules/ && ls -l
# output
drwxr-xr-x  5 root  wheel   170 May 29 19:19 myModule

$ ls -l myModule
# output
drwxr-xr-x  3 root  wheel   102 May 29 19:07 directives
-rw-r--r--  1 root  wheel   484 May 29 19:19 install.js
-rw-r--r--  1 root  wheel  1335 May 29 19:17 controller.js
-rw-r--r--  1 root  wheel  1335 May 29 19:17 service.js

$ ls -l myModule/directives
# output
-rw-r--r--  1 root  wheel  116 May 29 18:37 list.tmpl

Installing a Module

Every module has an installation file install.js, that tells the main application about the location of the module's scripts, directives & services, the permissions to be applied and which menu the module is accessible from. Installing a UI module does not mean that its information is stored in the database, the UI only loads the information and adds it to its navigation granting the user access to that module.

The installation file contains an array of entries that point to the module's pages. Following the same concept of SPAs, a module should have at least One page meaning One entry in the array. The following table explains the content of one entry in the installation array:

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
id	String	YES	HTML Id of a module's page
label	String	YES	Module page label used by the Menu(s) & the Tracker
url	String	YES	Module's page link ( should always start with "#/" )
scripts	Array	YES	The location of the javascript files this page requires, each entry refers to one file
tplPath	String	YES	The location of the module's page default html directive
checkPermission	Object	NO	This object contains the module's page permission, the user's ACL is matched against this entry to determine if the page is accessiblew
pillar	Object	YES	Define which pillar this module belongs to as well as the position inside that pillar.
icon	String	NO	An optional icon that shows up in the menu(s), given to the default page of the module.
tracker	Boolean	NO	If set to true, then breadcrumbs are enabled and displayed above the module
ancestor	Array	NO	If tracker is set to true, displays the list of parent breadcrumbs based on this array, up to the module's page
mainMenu	Boolean	NO	If set to true, the module has an entry in the main menu
footerMenu	Boolean	NO	If set tot true, the module has an entry in the footer menu
userMenu	Boolean	NO	If set tot true, the module has an entry in the user menu (this menu shows up for logged in members only)
guestMenu	Boolean	NO	If set tot true, the module has an entry in the guest menu (this menu shows up for non logged in members only)

install.js sample

var myModuleNav =[
    {
        'id': 'myModules',
        'label': 'My Module',
        'url': '#/mymodule',
        'scripts': ['modules/myModule/controller.js'],
        'tplPath': 'modules/myModule/directives/list.tmpl',
        'checkPermission':{
            'service':'mymodule',
            'route':'/list'
        },
        'pillar': {
            'name': 'operate',
            'label': 'Operate',
            'position': 4
        },
        'icon': '',
        'mainMenu': true,
        'tracker': true,
        'ancestor': ['Home']
    }
];

//add the module to the dashboard navigation
navigation = navigation.concat(myModuleNav);

Once you create the install.js file, edit the soajs.dashboard/ui/index.html file and point out its location in the <head> tag. Refresh the page and the Dashboard UI will pick up your module's location, once the main controller starts, it will load your module.

Note

Add the entry of modules/myModule/install.js before the dashboard main controller entry app/controller.js.

<head>
    <!-- html head code goes here -->

    <!-- my module install.js file-->
    <script src="modules/myModule/install.js"></script>

    <!-- html head code goes here -->

    <!-- dashboard main controller file-->
    <script src="app/controller.js"></script>

    <!-- html head code goes here -->
</head>