Appcatalyst-core-example NPM

AppCatalyst - Core

Angular library containing the AppCatalyst core components and services

This repository contains the AppCatalyst core library and development environment.

This repository features:

Core library: The @appcatalyst/core library resides in the lib directory and is packaged with ng-packagr.
Example implementation: The minimum working example resides in the src directory and is an Angular CLI application.

To run the example, perform the following steps:

$ npm install
$ npm run start

Library Development

While developing the @appcatalyst/core library, it is recommended that you build and test new features and updates in the example implementation residing in the src directory.

This will allow us to maintain a running example of the library implementation and usage.

Run example

To run the example, perform the following steps:

$ npm run start

Versioning

Both the library and the example implementation utilize Semantic Versioning. Please be sure to update the version number accordingly before publishing any new builds.

The version may be easily edited with the npm version tool:

$ npm version [major | minor | patch]

Be sure to update the appropriate package configuration file: The library and example implementation each have their own package file, and thus, their own version number and dependencies.

Compilation

To build the Angular Library, simply use ng-packagr as follows:

# Build library
$ npm run build:lib

Before building for deployment, be sure to follow the rules as specified in the Versioning section.

Instead of using a symbolic link for local testing (which commonly has side effects), simply pack the distributable and import it by relative path.

# Package local distributable (optional)
$ npm run pack:lib

Usage

Create a new Angular project

Start by creating a new Angular project using the angular-cli:

$ ng new example-implementation --style=scss

Notice the optional --style=scss flag.

Install Dependencies

Once the project has been created, install the library and its peer dependencies:

$ npm install @appcatalyst/core --save

The browser will notify you of missing peer dependencies to install.

npm WARN @appcatalyst/core requires a peer of @ng-bootstrap/ng-bootstrap but none is installed. You must install peer dependencies yourself. ...

TODO: add font-awesome and medical-font as peer-Dependencies in library

Configure `angular-cli.json`

Add styles references:

"styles": [
  "../node_modules/bootstrap/scss/bootstrap.scss",
  "../node_modules/font-awesome/scss/font-awesome.scss",
  "styles.scss"
],
"stylePreprocessorOptions": {
  "includePaths": [
    "../node_modules/bootstrap/scss/"
  ]
},

Add Stage Environment to environments.

"environments": {
  "dev": "environments/environment.ts",
  "prod": "environments/environment.prod.ts",
  "stage": "environments/environment.stage.ts"
}

Set development port (localhost:3000) in the defaults property for CORS support with Auth Server 1.1.

"defaults": {
  "serve": {
    "port": 3000
  },
  "styleExt": "scss",
  "component": {}
}

Configure `tsconfig.json`

"compilerOptions": {
  ...
  "suppressImplicitAnyIndexErrors": true,
  "baseUrl": "src",
  "paths": {
    "@angular/*": ["../node_modules/@angular/*"],
    "@core/*": ["app/core/*"],
    "@cms/*": ["app/cms/*"],
    "@environments/*": ["environments/*"]
  }
},
"include": [
  "src/**/*",
  "node_modules/moment/moment.js"
]

Configure environment variables

Create the additional staging environment file at src/app/environments/environment.stage.ts.

Each environment should provide the following properties (e.g. of environment.ts),

export const environment = {
  title: 'AppCatalyst Core Library',
  authUrl: 'https://auth.appcatalyst.com/1',
  resourceUrl: 'https://auth.appcatalyst.com/1',
  description: 'AppCatalyst Core Library Example Implementation',
  production: false
};

Be sure to include these properties in environment.prod.ts, environment.stage.ts and environment.ts (development).

Import styles

Add imports to styles.scss and add padding for navbar-fixed-top. For our new theme you could copy the color palette also out of styles.scss.

@import "_functions";
@import "_variables";
@import "bootstrap";

body {
  padding-top: 80px;
}

.btn-warning, .btn-warning:hover, .badge-warning {
  color: white;
}

.portal-header {
  @extend .mt-3;
  @extend .mx-auto;
  @extend .text-center;
  max-width: 600px;
  .portal-logo,
  .portal-logo img {
    line-height: 120pt;
    margin-left: auto;
    margin-right: auto;
    border-radius: 50%;
    height: 150pt;
    width: 150pt;
    background-color: #B0C4DC;
    @media screen and (max-width: 768px) {
      height: 120pt;
      width: 120pt;
    }
  }
  i {
    font-size: 80pt;
    color: #fff;
    margin-top: 36pt
  }
}

.ng-touched.ng-invalid:not(form) {
  @extend .is-invalid;
}

.ng-valid[required], .ng-valid.required  {
  @extend .is-valid;
}

// in bootstrap 4 beta 2 the feedback has to be immediately following the input for it to show up
.invalid-feedback {
  display: block;
}

Add a logo

Add a logo to the assets/img/ directory. This logo will be displayed on the HomeComponent.

The default logo uses a 780 × 240 image asset.

Update Responsive Meta Tag

Per bootstrap recommendation, update the responsive meta tag in your index.html file.

<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

Require Core Module and dependencies

Import the AppCatalyst library and vendor dependency in your app.module.ts.

Optional configuration settings can be included in the CoreModule.forRoot() constructor.

import { NgbModule } from '@ng-bootstrap/ng-bootstrap';
import { RouterModule } from '@angular/router';

import { CoreModule } from '@appcatalyst/core';
import { CoreRoutingModule } from '@appcatalyst/core';

import { CmsModule } from '@cms/cms.module';
import { environment } from '@environments/environment';
...
  imports: [
    ...
    RouterModule,
    NgbModule.forRoot(),
    CoreModule.forRoot({
      title: environment.title,
      authUrl: environment.authUrl,
      resourceUrl: environment.resourceUrl,
      description: environment.description,
      registerButton: false
    }),
    CmsModule,
    CoreRoutingModule
  ]

See core-config.service.ts for a list of configuration options.

Require App Component (optional)

In your app.module.ts, you may choose to reuse the core module's app component.

import { AppComponent } from '@appcatalyst/core';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    ...
  ],
  providers: [],
  bootstrap: [AppComponent]
})

Be sure to delete the default app.component.** files angular-cli created for you.

Require App Routing Module (optional)

In your app.module.ts, you may choose to reuse the core module's app component.

This import must be included after CoreModule and any other feature module imports.

import { AppRoutingModule } from '@appcatalyst/core';
...
  imports: [
    ...
    AppRoutingModule
  ]

If you otherwise do not choose to reuse the core module's app routing module, you will need to create your own.

Create your new module

Typically, the next step will be creating a module for the custom web application components. Typically we name this module as cms.

ng generate module `module-name`