Web Components for Imagine

Here's where we'll have all of the components for Imagine, they're to be written in Stencil and deployed to it's own npm module to be used on our projects

Running the project

To run project first clone it to your local hard drive. Then run the following commands:

npm install
npm start

You can now access it on http://localhost:9009

Versioning

• The patch version of the web components is incremented automatically when a PR is merged.
• If a breaking change is being introduced in the project, adding the 'major' label to the PR will increment the major version.
• If a new feature is being introduced in the project, adding the 'minor' label to the PR will increment the minor version.

Creating a new component

Step 1

First find the component in the Zeplin project (request access in the closed #newux channel on Slack). The component will be in a screen named either:

• Complex Components
• Simple Components
• Structure Components

Locate which screen the component is on.

Step 2

In the folder src/components/{screen-name} create a new folder: im-{component-name}.

Step 3

Create 3 new files inside this folder:

{tag}.stories.js

import { storiesOf } from "@storybook/polymer";
const stories = storiesOf("{section}|{component-name}", module);

{tag}.tsx

import { Component } from "@stencil/core";

@Component({
   tag: "{tag}",
   styleUrl: "{tag}.scss"
})
export class {tag | pascal-cased} {

   render() {
      return (<div></div>);
   }
}

{tag}.scss

Step 4

Start developing!

Using the components in our projects

This needs to be done on every project where the components are to be used, regardless of library.

Step 1

Get access to our organisation on https://npmjs.com, create a token for you profile and set it as an environment variable on you machine, with the name NPM_TOKEN.

Step 2

Create a file in the root of your project: .npmrc

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Step 3

Install the dependency: npm install --save @k3imagine/web-components.

Step 4

Update the Dockerfile so that the NPM_TOKEN variable is exposed and the .npmrc file is copied over.

FROM node:latest as builder

ARG NPM_TOKEN

WORKDIR app

COPY .npmrc ./

Using the components in an Angular project

For projects that use Angular 2+ follow these steps:

Step 1

In your angular.json file, in the array projects.architect.build.options.assets add the following entry:

{
  "glob": "**/*",
  "input": "./node_modules/@k3imagine/web-components/dist/collection/assets",
  "output": "./assets/"
}

Step 2

In your src/main.ts file add the following import:

import { defineCustomElements } from "@k3imagine/web-components/dist/loader";

At the bottom of the file, add the following line:

defineCustomElements(window);

Step 3

In the module you want to use the Stencil components add the CUSTOM_ELEMENTS_SCHEMA import from @angular/core. Then add the following property to the options inside the NgModule decorator:

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  ...
})

Step 4

Start developing with the components!

Using the components in an AngularJS project

For projects that use Angular 1.x follow these steps:

Step 1

Update the package.json file to only have the new components under dependencies, with the rest being on devDependencies:

{
  "dependencies": {
    "@k3imagine/web-components": "^0.4.5"
  },
  "devDependencies": {
    "...the rest of the libraries": "Go here"
  }
}

Step 2

Install the library used to copy the files npm install --save-dev gulp-npm-dist

Step 3

Add a new command into gulp to copy the component library into the public folder:

gulp.task("copy:libs", function () {
  return gulp
    .src(npmDist(), { base: "./node_modules" })
    .pipe(gulp.dest("./public/libs"));
});

Then you can add it into the build flow like so:

gulp.series(
  "clean:public",
  "sass",
  gulp.parallel("copy:html", "copy:assets", "copy:libs")
);

Step 4

Add a reference the component library on the project's index.html headers

<script src="/libs/@k3imagine/web-components/dist/components.js"></script>

Steps 5

Start developing with the components!

Examples

Here are some examples on how to use the components on both Angular and angularJS

Angular (2+)

<im-data-table
  [model]="model"
  [data]="data"
  (action)="action($event)"
></im-data-table>

AngularJS (1.x)

<im-data-table
  ng-prop-model="$ctrl.model"
  ng-prop-data="$ctrl.data"
  ng-prop-options="$ctrl.options"
  ng-on-action="$ctrl.action($event)"
></im-data-table>

Upgrade to v1.0+

As part of the update to v1.0 of the web components was the addition of a new top and sidebar, as well rectifying some issues and warnings that were showing up in the build logs around the use of reserved and conflicting properties. When upgrading in a ui project that was using the web components prior to v1.0 the following properties would need to be changed in the UI project if they have been binded.

im-picklist

1. The event "error" has been renamed "componentError"

im-sidebar-old

1. The event "error" has been renamed "componentError"

im-sidebar

1. The event "error" has been renamed "componentError"

im-button

1. The event "onClick" has been renamed "buttonClick"

im-icon

1. The event "onClick" has been renamed "iconClick"

im-number-picker

1. The event "error" has been renamed "componentError"

im-input

1. The event "error" has been renamed "componentError"

im-title

1. The property "id" has been renamed "tileId"

The implementation of the sidebar and topbar can be found in the readme files found in each of the new component directories "src/components/complex/im-sidebar" and "src/components/complex/im-top-menu"