Grit Universal

This guide explains how to setup and begin using Grit Universal in your project.

Install Grit Universal

Grit Universal and associated libraries built by the FrontEnd Solutions team live both in Progressive Leasing internal Artifactory npm repository and the public npm registry https://www.npmjs.com/package/@progleasing/grit-universal.

If you need to work with a prerelease branch you will need to point to progressive's internal registry. You might follow the next step for it.

Installing the package with npm

Just run npm i @progleasing/grit-universal

Configuring the package

• Vanilla Js

With a framework:

In order to apply all global styles add reference to the following files into your app.

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Material+Icons&family=Lato:wght@300;400;700&family=Montserrat:wght@300;400;500;600;700;800&display=swap"
  rel="stylesheet"
/>

<link
  rel="stylesheet"
  type="text/css"
  href="node_modules/@progleasing/grit-universal/dist/grit-webcomponents/grit-webcomponents.css"
/>

<script type="module">
  import { defineCustomElements } from './node_modules/@progleasing/grit-universal/loader';
  defineCustomElements();
</script>

Without a framework, it's as easy, but it will only work with what's published in the public npm registry, you can do like so:

Make sure to change <version> for the current version you need.

<link
  rel="stylesheet"
  type="text/css"
  href="https://cdn.jsdelivr.net/npm/@progleasing/grit-universal@<version>/dist/grit-webcomponents/grit-webcomponents.css"
/>

<script type="module">
  import { defineCustomElements } from 'https://cdn.jsdelivr.net/npm/@progleasing/grit-universal@<version>/loader/index.es2017.js';
  defineCustomElements();
</script>

• Angular Version 9-10-11-12

In Angular, you can install our stencil angular wrapper running npm i @progleasing/grit-universal-angular which will provide helpful utilities and types out of the box.

Next step would be to add GritUniversalModule to the modules imports that will be using the web component.

import { GritUniversalModule } from '@progleasing/grit-universal-angular';

@NgModule({
  declarations: [ButtonComponent, FieldComponent, ...,
  imports: [
    GritUniversalModule.forRoot(),
    ...
  ]
})

Include in your index.html file the following stylesheets

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Material+Icons&family=Lato:wght@300;400;700&family=Montserrat:wght@300;400;500;600;700;800&display=swap"
  rel="stylesheet"
/>
<link
  rel="stylesheet"
  type="text/css"
  href="{installed package location}/grit-webcomponents.css"
/>

Then edit your angular.json under the "styles" property and add this entry.

"styles": [
    ...
    {
        "input": "node_modules/@progleasing/grit-universal/dist/grit-webcomponents/grit-webcomponents.css"
    }
]

Enabling SCSS functions and mixins in Angular

In your angular.json file add the following:

"styles": ["src/styles.scss"],
"stylePreprocessorOptions": {
  "includePaths": [
    "node_modules/@progleasing/grit-universal/dist/grit-webcomponents",
    "src/assets"
  ]
},

and in your src/styles.scss add:

@import 'global/global';

After doing this changes you can include any of the scss files from Grit Universal from doing @import "global/{someFileName}"; and have access to any of the scss mixins or functions without doing directory hunting.

Trying it out

Now in any HTML file or Angular component you can put a Grit Universal Components like this and you should be seeing the default face icon from Material Icons

<grit-wc-icon>face</grit-wc-icon>

Google Analytics with Google Tag Manager

The library allows the usage of Google Tag Manager through a simple initialization when you application loads.

To do so you need to call the GoogleAnalytics service and call it's static init method like so

// or
import {
  GoogleAnalytics,
  IGoogleAnalyticsInit,
} from '@progleasing/grit-universal'; // or '@progleasing/grit-universal-angular'

const gtmOptions: IGoogleAnalyticsInit = {
  gtmId: uniqueId,
  eventCategory: 'Application name',
  flowType: 'App flow type',
  flowName: 'App flow name',
  version: 'App version, flow version',
  logPageViews: true,
};

GoogleAnalytics.init(gtmOptions);

This will set all actionable component in the library to push an event to the dataLayer of Google Tag Manager with information containing a context label and the action taken button click, checkbox checked, etc.

In case logPageViews is set to true, the application will also log and push to the dataLayer all the history.location changes occurring.

New properties on all components!

All components in the library right now have the analyticsEnabled property, which disables GTM on that specific instance if set to false. The pii property which ensures there is no PII sent to the dataLayer, and the analyticsCustomObj which allows you to sent completely custom objects to the dataLayer. To see any example you can check any demo component.

I'm already using GTM, will this cause issues?

If your application already has a GTM loaded, the library won't add a new instance and instead will use the dataLayer already declared in the window object.

I'm already using GTM and Grit Universal, will this cause issues?

In this case, you might have repeated events on all used components. This can be fixed refactoring your internal usage of GTM or adding the property analyticsEnabled set to false on all Grit Universal components.

Browsers supported

| Browser | PC/Mac | Android | iOS | | ------- | :----: | :-----: | :-: | | Chrome | +86 | +10 | +11 | | Firefox | +81 | +10 | N/A | | Safari | +14 | N/A | +11 | | Edge | +86 | N/A | N/A |