consort v1.2.0

The Socius Shared Angular Library

A shared component library which can be used in Angular projects.

The library is built with gulp which creates a lib directory that can be linked to and used by another project.

Table of contents

1. Development Setup
2. Current work
3. Set up a project to use this library
4. Using components
5. A data model class
6. A UI component
7. Using a service
8. Extending a component
9. Development

Development Setup

Install the dependencies to build the project in the following manner:

$ npm i gulp gulp-sass run-sequence gulp-minify-css gulp-sourcemaps gulp-typescript typescript gulp-inline-ng2-template

Build the project like this:

$ gulp build

This will build the project into the lib directory.

Current work

This project will finally get used for what it was meant for. It will used in Loranthifolia, Teritifolia and Conchifolia projects to hold common front end code. The back-end code uses the Curator project as a shared lib for the back end code.

First we will move some constants and data models, as well as some vanilla JavaScript functions. It would be nice to use Angular 6's Elements for new UI components.

Set up a project to use this library

Without using the npm ecosystem, we can link the lib to a project in the following way.

Package linking is a two-step process.

First, in the project lib directory:

$ npm link 

This will create a globally-installed symbolic link from prefix/package-name to the current folder.

Next, in the node_modules of the project where you want to use this lib:

$ npm link socius

A symlink will be created from the local node_modules to the socius lib.

Using components

There are three types of components in the library. The first type is a simple class, for example, the data model. The second type is a UI component.
The third type is a service, or provider as they are called these days. These types require different methods for usage.

A data model class

To use a class from the library, for example the Pattern object, in the class where you would like to use it, you only have to import the part that you want:

import { Pattern } from 'socius';

You can then create a member variable like this:

pattern: Pattern;

A UI component

To use a UI component, for example, the notification object, we need to add it to the app.module.ts file.

import * as socius from 'socius/lib/components/notification.component';

@NgModule({
  declarations: [
    socius.NotificationComponent

The notification component has a title and content.
These variables need to be created in the class. (Note there is no need to import the class here):

export class DashboardPage {
  title: string;
  content: string;
  
  constructor(
    public navCtrl: NavController,
    public authService: Auth) {
      this.title = 'Hi there';
      this.content = 'You have notifications waiting.';
  }

And in the template:

<notification [title]="title" [content]="content"></notification>

Using a service

Using a provider service requires a slightly different method. Import the service in the app.module.ts file with the path to the file. This example shows how to use the Wikidata service. You must also put it in the providers array like this:

import { Wikidata } from 'socius/lib/providers/wikidata';
  ...
  providers: [ Wikidata ],

In the class where you want to use the service you must also use the same import as shown above. In the constructor, include the reference and use it like this:

  constructor(wikidata: Wikidata) {
    let result = wikidata.getData('quadcopter');
  }

Extending a component

Another option is extending a component using the method this article on Component Inheritance. An important thing to note about this method is that Component inheritance does not cover templates and styles. Shared DOM or behaviours must be re-created.

The example shows this code example:

export class MyPaginationComponent extends SimplePaginationComponent

The original template does this:

<button (click)="nextPage()" [disabled]="!hasNext()">{{ nextText }}</button>

The extended template, which now uses a link does this:

<a (click)="nextPage()" [class.disabled]="!hasNext()" href="javascript:void(0)" >{{ nextText }}</a>

Development

To add a class to the library, first, create the class somewhere within the src directory. Import it into the socius.module.ts file:

import { Result } from './models/result';

Add it two both the exports and declaration arrays:

    exports: [
            NotificationComponent,
            Result,
            ...
    ],
    declarations: [
            NotificationComponent,
            Result,
            ...

Then also add an export reference in the index.ts file:

export * from './models/result'

Run gulp build and Robert will become a close family relative.