# 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.

```html
<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.

```html
<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.

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

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

Include in your index.html file the following stylesheets

```html
<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.

```json
"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:

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

and in your `src/styles.scss` add:

```scss
@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

```html
<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

```js
// 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 |