Quick-Start Guide to ngx-admin Angular Dashboard Template

header-image

Today, most of you would agree that the best way to develop a dashboard for your B2B or even B2C application’s admin panel is undoubtedly Single Page Application frameworks like Angular, React or Vue. All three of these frameworks have been growing rapidly and more companies are adopting it day by day. When it comes to Angular, ngx-admin is a free open-source template which provided by akveo which can get you started in no time.

This article means to act as a cheatsheet on how to get the most out of the template in the fastest time possible. ngx-admin does come up with pretty good documentation but I personally felt it doesn’t directly explain the whole architecture of how different components and modules are arranged and takes a few hours to get accustomed to it.

Bonus: You can clone the scaled down starter-kit branch to get started with your project. As it is just a git branch which you gotta checkout to get started, you can get started by just using the flag –single-branch starter-kit while cloning your project using git.

Index

  1. The Architecture of ngx-admin Template
  2. Modifying and Navigating using Sidebar
  3. Customizing theme colors
  4. Creating pages & components
  5. Using Nebular components and EVA icon pack

1. The Architecture of ngx-admin Angular Template

When you clone the template, you will be greeted with a sophisticated folder structure which might look like following:

[-] ngx-admin-template   <-------------------------- Project Root
    [+] e2e
    [+] node_modules
    [-] src
        [-] app
            [+] @core   <--------------------------- Services, Mock APIs &amp; Models
            [+] @theme  <--------------------------- Theme styling &amp; generic module-independent components like header, footer and directives
            [+] pages   <--------------------------- UI modules divided in multiple pages
             -  app-routing.module.ts
             -  app.component.ts
             -  app.module.ts
        [+] assets
        [+] environments
         -  favicon.ico
         -  index.html
....
....     

So the template is simple, inside the app folder where usually the Angular app resides, you get three major folders:

@core
The core folder is the place where you should place your primary logic behind the application like all the models, mock APIs, your actual APIs and other utility services. One nice pattern used by the mock API services inside ‘mock’ folder are that they are inherited by the abstract data classes present in the ‘data’ folder.

@theme
Well as the name identifies, the folder contains all theme specific and module-independent custom layouts, components, directives, pipes, etc.

The one column layout is by default used inside the application, you can check the code inside src/app/pages/pages.component.ts file.

pages
This is where the crux of the application lies. The application is designed in a manner in which every single item in navigation menu at the left navigates to a different page or sub-page component on the right section. All the pages are defined inside the ‘pages’ folder.

The primary navigation inside the application is handled by src/app/pages/pages-routing.module.ts file. All the other page modules are being lazy loaded. More information about routing in angular can be found here on the blog.

The left sidebar is going to be the primary navigation medium for the application. The ngx-admin theme uses Nebular Angular UI Library in the background developed again by akveo. The sidebar is powered by NbMenuComponent of Nebular. Its a pretty flexible and easy to use Menu component. All navigation items are defined in src/app/pages/pages-menu.ts. The JSON structure of the file is very simple and self-explanatory. The sample can be seen below:

import { NbMenuItem } from '@nebular/theme';

export const MENU_ITEMS: NbMenuItem[] = [
  {
    title: 'Dashboard',
    icon: 'home-outline',
    link: '/pages/dashboard',
    home: true,
  },
  {
    title: 'FEATURES',
    group: true,
  },
  {
    title: 'Auth',
    icon: 'lock-outline',
    children: [
      {
        title: 'Login',
        link: '/auth/login',
      },
      {
        title: 'Register',
        link: '/auth/register',
      },
      {
        title: 'Request Password',
        link: '/auth/request-password',
      },
      {
        title: 'Reset Password',
        link: '/auth/reset-password',
      },
    ],
  },
];

Hint: You can use EVA icon cheat-sheet to define icons.

3. Customizing theme colors

The template comes with 4 pre-defined themes which can be switched at runtime or also configured at compile time as required. The default themes are as follows:

  1. default
  2. corporate
  3. cosmic
  4. dark

To switch between the themes, just go to src/app/@theme/theme.module.ts and change NbThemeModule.forRoot as highlighted below.

@NgModule({
  imports: [CommonModule, ...NB_MODULES],
  exports: [CommonModule, ...PIPES, ...COMPONENTS],
  declarations: [...COMPONENTS, ...PIPES],
})
export class ThemeModule {
  static forRoot(): ModuleWithProviders {
    return <ModuleWithProviders>{
      ngModule: ThemeModule,
      providers: [
        ...NbThemeModule.forRoot(
          {
            name: 'default',
          },
          [ DEFAULT_THEME, COSMIC_THEME, CORPORATE_THEME, DARK_THEME ],
        ).providers,
      ],
    };
  }
}

More custom changes can be incorporated by modifying variables in src/app/@theme/styles/themes.scss. A detailed documentation is available here. I recommend using EVA Color generator tool to define colors for your custom theme.

4. Creating pages & components

All of your pages should go under src/app/pages folder. If its a primary navigation menu item, create a new module dedicated to the page and also enable routing if more sub-pages are expected by using following Angular CLI command.

ng g m <module_name> --routing=true --module=pages.module.ts

Creating the pages in their own module helps you in making your application faster by using lazy-loading functionality where the required module is only loaded when it is navigated to.

Reminder: Remember to include a <router-outlet> inside the primary component of the module while routing. Example here.

The generic components which are used by multiple pages need to land outside the ‘pages’ folder into the ‘@core‘ folder as also explained above.

5. Using Nebular components and EVA icon pack

Nebular Components
The best part of using ngx-admin is the underlying Nebular UI library and EVA design framework developed by the company. The Nebular components whose support should be available out-of-the-box are detailed here in the Nebular documentation. These components by default have support for the themes and colors making the customization pretty easy.

The Nebular UI library also has a powerful Authorization Module which can be used out-of-the-box to support OAuth login flows. More details can be found in the documentation.

The Icon Pack
The Nebular Icon component by default supports eva icon pack, font-awesome icon pack and ionicons. Choosing your icon style is a simple one line code as described here:

<nb-icon icon="icon-name" pack="eva"></nb-icon> <!-- For EVA Icon Pack -->
<nb-icon icon="icon-name" pack="far"></nb-icon> <!-- For Font-Awesome Icon Pack -->
<nb-icon icon="icon-name" pack="ion"></nb-icon> <!-- For Ionicons Icon Pack -->

Conclusion

I think this might be enough to get you started. ngx-admin is one of the best theme to get you started to create a admin template. As mentioned above, you can get started by using ‘starter-kit‘ branch of the template. Is there anything else which should be covered in the quick start? Use the contact us page to drop down your suggestions and feedback.

License Information: The ngx-admin is licensed under MIT License which allows you to free of cost and unrestricted private commercial usage. More information can be found here.

You May Also Like

About the Author: Gaurav Chouhan

Gaurav is an independent senior software consultant and trainer based out of India with more than 5 years of experience in cloud computing specifically on Microsoft Azure, full-stack development on .net core and angular and mobile programming on Android and UWP. For business opportunity, please use the contact section.

Leave a Reply

%d bloggers like this: