@thogan/core-ui-template v1.0.0

CoreUI Template Angular NPM Module

Description

This NPM moodule wraps the CoreUI Bootstrap template from http://coreui.io, so that it can be installed into an existing Angular 4+ project as a module.

The module is currently hosted on BitBucket, at https://bitbucket.org/richf_princeton/core-ui-template, but will eventually be moved to our internal Nexus repository.

Installation

To install the template into your project, use either 'npm install' or 'yarn add' from the command line at the root of your Angular project:

npm install --save git+https://richf_princeton@bitbucket.org/richf_princeton/core-ui-template.git

or

yarn add git+https://richf_princeton@bitbucket.org/richf_princeton/core-ui-template.git

Either of these commands will update your package.json file with a reference to the new module, and then download the module to your project's node_modules folder, making it available for use by your project.

Usage

To use the template, you must import the core-ui Angular module into your project, use the template's root tag in the location where you want the template to appear, and then provide content to the template.

1. Import the template module

Edit your application's src/app/app.module.ts file, add an import for the core-ui-template module, and add the CoreUiTemplateModule to the AppMdoule's imports section, e.g.:

import {NgModule} from '@angular/core';
import {HashLocationStrategy, LocationStrategy} from '@angular/common';
import {BrowserModule} from '@angular/platform-browser';
import {AppRoutingModule} from './app.routing';
import {AppComponent} from './app.component';

// add this import statement
import {CoreUiTemplateModule} from 'core-ui-template';

@NgModule({
  	imports: [
    	BrowserModule,
		AppRoutingModule,
		
		// import the CoreUiTemplateModule into the AppModule
		CoreUiTemplateModule</b>
	],
	declarations: [
		AppComponent
	],
	providers: [
		{provide: LocationStrategy, useClass: HashLocationStrategy}
	],
	bootstrap: [AppComponent]
})
export class AppModule {
}

2. Use the template's root tag

The template could be applied to any component in your application, but in most, if not all cases, will be applied to your AppComponent. By default, in a new project, your AppComonent's template will be in app.component.ts

Remove all of the existing content from app.component.html and replace it with:

<app-core-ui-template>
</app-core-ui-template>

This will insert the output of the core-ui template into the root of the application's HTML Document. At this stage, if you compile and run the application, you should see a header, a left-side navigation bar, and a footer.

However, since we have not provided any content yet, each of these areas will be blank.

3. Provide Content to the Template

The core-ui template defines 'slots' where you can insert your application's content.
Each slot has an associated custom HTML attribute. To provide content to the slot, surround your content with an ng-container tag that has the slot's attribute. All of the ng-container tags shown in the following examples should be included in the same <app-core-ui-template> tag. The order of the ng-container tags is not significant.

Top Bar (Left)

The template's slot for content for the left side of the top bar is marked by the core-ui-template-topbar-nav attribute, so add an <ng-container> tag inside the <app-core-ui-template> tag, add the attribute to the ng-container tag, and place your content within it.

Individual items in the top bar are expected to be list items with a nav-item class.

Navigation links within navigation items are expected to have a nav-link class.

For example:

<app-core-ui-template>
	<ng-container core-ui-template-topbar-nav>
		<li class="nav-item">Hello, top-left</li>
		<li class="nav-item">
		  <a class="nav-link" [routerLink]="['/']">Home</a>
		</li>
	</ng-container>
<app-core-ui-template>

Top Bar (Right)

The template's slot for content for the left side of the top bar is marked by the core-ui-template-topbar-nav-right attribute, but is otherwise identical to the top-bar's left-justified content, as explained above.

Left Navigation Bar

The template's slot for content for the left navigation bar is marked by the core-ui-template-sidebar-nav attribute, so add an <ng-container> tag inside the <app-core-ui-template> tag, add the attribute to the ng-container tag, and place your content within it.

As with the Top Bar, each item here is expected to be a list item with the nav-item class (<li class="nav-item"></li> ), and any links are expected to have the "nav-link" class. For example:

<ng-container core-ui-template-sidebar-nav>
	<li class="nav-item">
		<a class="nav-link" routerLinkActive="active" [routerLink]="['/dashboard']">Dashboard</a>
	</li>
	<li class="nav-item">
		<a class="nav-link" routerLinkActive="active" [routerLink]="['/autocomplete']">AutoComplete</a>
	</li>
	<li class="nav-item">
		<a class="nav-link" routerLinkActive="active" [routerLink]="['/data-grid']">Data Grid</a>
	</li>
</ng-container>

Main Content

The template's slot for the application's main content is marked by the core-ui-template-content attribute.

An Angular application's main content is typically produced inside a <router-outlet> tag. So, to insert the application's main content into the template's main content slot, you will typically use:

<ng-container core-ui-template-content>
	<router-outlet></router-outlet> 
</ng-container>

Footer

The template's slot for the footer is marked by the core-ui-template-footer attribute. Content within the footer is free-form. Example:

<ng-container core-ui-template-footer>
    &copy; <a href="http://princeton.edu">Princeton University</a> 2017
        <span class="float-right">Version 1.0.0</span>
</ng-container>