ott-cwl

v0.0.49

Published

a year ago

Ottawa Common Web Library

Downloads

349

0High
0Medium
0Low

walkerjam

Ottawa Common Web Library

This library produces a collection of Web Components that can be used to quickly build web applications that use the City of Ottawa's common look and feel.

The design documents (Digital Services Toolkit) can be found here: https://github.com/CityofOttawa/OttStyleGuide (live version here: https://app06dev.ottawa.ca/dev/ottstyleguide).

This library is hosted as an npm package here: https://www.npmjs.com/package/ott-cwl.

Development environment

Setup

Before running anything else, fetch the dependencies:

npm i

Run the demo

The demo page has an assortment of components to see at a glance. Run it using the collowing command:

npm run start

This demo page is hot-reloaded, so if you make changes to any of the components (or add new ones), you'll be able to see them immediately.

Run the Storybook

Storybook is a tool that facilitates rendering and testing components in isolation, as "stories". Run the storybook for this library with the following command:

npm run storybook

The storybook is hot-reloaded and tracks any changes to the components (with stories setup), scss files and the stories themselves.

The storybook is also available to view online: https://app06.ottawa.ca/dev/cwl.

There's a jenkins job to update it - this runs anytime the dev branch is updated.

Using this library in your project

There are several ways to consume the artifacts produced by this library. Depending on your needs, one method may be simpler than another.

Note that some of the typography styles depend on a 3rd-party font "Mulish", your application server must accept resources from the following origin:

https://fonts.gstatic.com

Using static assets

If you simply want to use the CSS from this lib, you can just reference the CSS file inside your HTML:

<link rel="stylesheet" href="https://unpkg.com/ott-cwl/dist/ott-cwl/ott-cwl.css">

Note that you can (and probably should) use a specific version of the asset by providing it in the URL:

<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/ott-cwl/ott-cwl.css">

If you're just starting out developing your application, you'll likely want to use the latest version available. If you're updating an existing application, be sure to test the latest version of this lib in a Dev or QA environment as there may be breaking changes between versions.

If you use the static assets method, you will need to use the plain HTML markup you see in the storybook examples. However, if you'd also like to make use of the Web Components, you can also include some javascript:

<script type="module" src="https://unpkg.com/ott-cwl/dist/ott-cwl/ott-cwl.esm.js"></script>
<script nomodule src="https://unpkg.com/ott-cwl/dist/ott-cwl/ott-cwl.js"></script>

So here's a working example with the CSS and JS:

<!DOCTYPE html>
<html dir="ltr" lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0">
  <title>Ottawa Common Web Library</title>
  <link rel="stylesheet" href="https://unpkg.com/ott-cwl/dist/ott-cwl/ott-cwl.css">
  <script type="module" src="https://unpkg.com/ott-cwl/dist/ott-cwl/ott-cwl.esm.js"></script>
  <script nomodule src="https://unpkg.com/ott-cwl/dist/ott-cwl/ott-cwl.js"></script>
</head>
<body>
  <ott-main>
    <ott-h1>Top level heading</ott-h1>
    <p>The following buttons are in a cluster:</p>
    <ott-cluster>
      <ott-button>Click me</ott-button>
      <ott-button-outline>Click me too!</ott-button-outline>
    </ott-cluster>
  </ott-main>
</body>
</html>

Note that our JS file seems to be included twice. That pattern is used to supply an optimized bundle to modern browsers (Chrome, Firefox, Safari), and a polyfilled bundle to older browsers (IE 11).

Using with a Vue.js application

The Stencil.js docs explain this quite well, but here's a recap:

Import the node module into the project
Use a Vue config element so the compiler will not try to parse our custom elements
Make the custom elements available in the window object

Essentially, once you've created your Vue.js application, get the module from :

npm i ott-cwl

Then in the main.[jt]s file, you should add something similar to the following:

import Vue from 'vue'
import App from './App.vue'

import 'ott-cwl/dist/ott-cwl/ott-cwl.css'
import { applyPolyfills, defineCustomElements } from 'ott-cwl/loader'

Vue.config.productionTip = false

// Tell Vue to ignore all components defined in our custom library
// and bind the custom elements to the window object
Vue.config.ignoredElements = [/ott-\w*/]
applyPolyfills().then(() => {
  defineCustomElements()
})

new Vue({
  render: h => h(App),
}).$mount('#app')

Now, you can use the custom elements in your component templates:

<template>
  <div>
    <ott-h1>This is a demo of the Ottawa Common Web Library</ott-h1>
  </div>
</template>

Development

The following guidelines should help while developing the library. For contribution guidelines, see CONTRIBUTING.md.

Creating new components

Stencil provides a convenient way to add new components, simply run:

npm run generate

You'll be asked for the component name (it should start with ott-), and what you'd like the command to generate for you.

Be sure to add relevant tests, stories, and documentation (the readme.md file will be auto-generated the first time you run npm run build).

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Ottawa Common Web Library

Development environment

Setup

Run the demo

Run the Storybook

Using this library in your project

Using static assets

Using with a Vue.js application

Development

Creating new components