Urbanite UI Template

This repository contains Urbanite UI Template. This template is built starting from NGX-Admin, an open source dashboard based on Angular, Nebular with Eva Design System.

Table of Contents

• Urbanite UI Template
  • Table of Contents
  • Requirements
  • Install
  • Build & Deploy
  • Docker
    • Docker-compose
  • Development
    • Create a Module
    • Create a Component
    • Create a Service
    • Manage Routing
      • URBANITE-UI routing
      • Module routing
    • Add Sidebar entry
    • Run the template

Requirements

To properly install and start the template, the following tools should be installed:

• Git
• Npm
• Angular CLI

Install

To properly install the template, follow these steps:

$ git clone https://git.code.tecnalia.com/urbanite/wp5-integration-and-devops/urbanite-ui-template.git
$ cd urbanite-ui-template
$ npm install

Build & Deploy

To build and deploy the template, follow these steps:

$ cd urbanite-ui-template
$ ng build --prod

This command generates a dist folder within the urbanite-ui-template folder. To properly deploy the application, the content of the dist folder should be placed within a server for instance: Nginx or Apache HTTP Server.

Please, refer to the official documentation for furhter details:

• Angular basic deployment to a remote server
• Server configuration

Docker

Build docker image:

$ cd urbanite-ui-template
$ docker build -t urbanite/urbanite-ui .

Run docker image:

$ cd urbanite-ui-template
$ docker run -it -p 80:80 urbanite/urbanite-ui

Docker-compose

The provided docker-compose.yml build and deploy the application with an instance of the IDM (Keycloak).

Run the following command to use the docker-compose:

$ cd urbanite-ui-template
$ docker-compose up

Development

This section summarizes the basic commands and configurations needed to integrate a new tool into the URBANITE-UI.

It is suggested to fork the repository or to create a specific branch for any new tool to be integrated. To "skip" the autentication process only for development purpouses change in /src/assets/config.json

"enableAuthentication":false

To push back to the repository

$ git push --no-verify

Create a Module

An Angular module should be created, for any new tool to be integrated. To properly create a new module, execute the following command:

$ cd urbanite-ui-template
$ ng generate module pages/<MODULE_NAME> --routing

Replace <MODULE_NAME> with the name of the new module.

This command will generate a new folder within the pages folder with the specific module and routing files. The routing file is mandatory if the new module is expected to contain more than one components.

Create a Component

An Angular component manages the views. At least a component should be created for any new tool to be integrated. To create a new component, execute the following command:

$ cd urbanite-ui-template
$ ng generate component pages/<MODULE_FOLDER>/<COMPONENT_NAME>

Replace <MODULE_FOLDER> with the path of the folder to the new module. Replace <COMPONENT_NAME> with the name of the new component. This command will generate a new folder within the pages/<MODULE_FOLDER> folder with the component details.

Create a Service

An Angular service is used, for instance, to build a REST client. To create a new service, execute the following command:

$ cd urbanite-ui-template
$ ng generate service pages/<MODULE_FOLDER>/<SERVICE_NAME>

Replace <MODULE_FOLDER> with the path of the folder to the new module. Replace <SERVICE_NAME> with the name of the new service.

Please, refer to the angular official documentation to build a REST client.

Manage Routing

To visualize the content for any new module the developer needs to manage routing. In the urbanite-ui-template there are two levels of routing:

• URBANITE-UI routing
• Module routing

Refer to the official routing documentation for additional details.

URBANITE-UI routing

To allow the a module to be accessed, the developer should open the urbanite-ui-template/src/app/pages/pages-routing.module.ts file with the configured IDE and add the following entry:

const routes: Routes = [{
  path: '',

  component: PagesComponent,
  children: [
    {
      path: 'home',
      loadChildren: () => import('./home/home.module')
        .then(m => m.HomeModule),
    },
    ...
    {
      path: '<module>',
      loadChildren: () => import('./<MODULE_FOLDER>/<MODULE_NAME>.module')
        .then(m => m.<MODULE_NAME>),
    },
    ...

The path represents how the module will be accessible through the browser url. Replace <MODULE_FOLDER> and <MODULE_NAME> with the specific values.

Module routing

To allow to access the components defined within each module, the developer should open and edit the urbanite-ui-template/src/app/pages/<MODULE_FOLDER>/<MODULE_ROUTING>.module.ts

Please, replace <MODULE_FOLDER> and <MODULE_ROUTING> with the corresponding paths.

const routes: Routes = [{
  path: '',
  children: [{
    path: '<COMPONENT_1_URL>',
    component: <COMPONENT_1>,
  },
  {
    path: '<COMPONENT_2_URL>',
    component: <COMPONENT_2>,
  },
  ...
  ],
}];

Each path, of the above, represents how the component will be accessible through the browser url. The component is the component name created within the module.

Add Sidebar entry

To add a sidebar entry, the developer should open and edit the urbanite-ui-template/src/app/pages/pages-menu.ts and add the following entry:

export const MENU_ITEMS: NbMenuItem[] = [
  {
    title: 'SERVICES',
    group: true,
  },
  {
    title: 'Home',
    icon: 'home-outline',
    link: "/pages/home",
    data:{
      name:"home"
    }
  },
  ...
  {
    title: '<MODULE_TITLE>',
    icon: '<MODULE_ICON>',
    link: "/pages/<MODULE>",
    data:{
      name:"<MODULE>"
    }
  },
  ...

The title is the label that would be added to the sidebar. Replace in the link and in the name the value defined for the path variable on URBANITE-UI routing. About the icon, please select an icon among the following and put its identifier.

Run the template

To start the application, follow these steps:

cd urbanite-ui-template
ng serve

The application will be available at http://localhost:4200