bitergo-common
v0.0.1
Published
*# Bitergo Common Purpose of this package is to help to develop Bitergo webapps and reduce code duplication.
Downloads
4
Readme
*# Bitergo Common Purpose of this package is to help to develop Bitergo webapps and reduce code duplication.
Installation
In order to install the bitergo-common
can be used next command:
npm i bitergo-common
After that, BitergoCommonModule
need to be imported to module, using forRoot
static method:
import { NgModule } from '@angular/core';
...
import { BitergoCommonModule } from 'bitergo-common';
@NgModule({
declarations: [...],
imports: [
...,
BitergoCommonModule.forRoot()
],
providers: [..],
bootstrap: [...]
})
export class AppModule { }
BitergoCommonModule
forRoot
static method has no any configuration input, for now.
Overview
The bitergo-common
library includes 2 services and 1 pipe:
HTMLTagService
Allows to append html tag/scripts with tiny amount of efforts in declarative
ProviderService
Allows to append or remove html tag/scripts or run the actions, depends on boolean indicator, in concrete order with waiting until scripts will be loaded.
SafePipe
Allows to use DomSanitizer
in html template with specifying type of resource.
HTMLTagService
The service provides quick interface to append and remove html tags or scripts, with possibility to wait until they will be loaded.
Using service, can be called next public methods:
append(input: HtmlAppendOptions): number | undefined
appendAndLoad(options: HtmlAppendOptions): Promise<number | undefined>
remove(id?: number): void
Methods append
and appendAndLoad
are doing almost the same, but second one is waiting until loading is finished and returns Promise
.
Both appends html tag, and in case of success they return number - id of created HtmlElement
inside the service.
Result
id
ofappend
andappendAndLoad
methods is NOT the same asid
attribute of theHtmlElement
.
Result id
can be used ONLY for removing html element from DOM, using remove
method.
As the input for the append methods, can be used HtmlAppendOptions
interface:
interface HtmlAppendOptions {
// name of tag to append
element: keyof HTMLElementTagNameMap;
// query to parent container, that will be used to append HTML tag
// default: 'head'
parentQuery?: string | typeof head | typeof body;
// any HTML tag attributes, like className, src, or whatever
attributes?: Record<string, string>;
// whether need to append tag on server side too.
allowInSSR?: boolean;
// the same as 'style' attribute of the 'HTMLElement'
style?: Partial<CSSStyleDeclaration>;
}
ProviderService
This service is using HTMLTagService
to append/remove script/tag or run some action.
It can be done by some condition, in chainable way, with possibility to rebuild everything on some events.
It provides only one public method update
with input of interface ProviderServiceOptions
.
Service is suitable to use when exists next conditions:
- there is a need to append some scripts, sequentially and wait when every script is loaded;
- need to remove scripts from DOM when some condition is changed;
- need to run some action on different conditions changed;
- need to append/remove html tags depends on events or conditions;
The idea behind the service is next:
- input contains
providers
andevents
properties; events
are rxjs Subject objects;providers
are the set ofactions
(means any function),scripts
ortags
(furtherprovider item
);- actions consists from
onAllow
and 'onDisallow' function; - each
provider item
can have others sets of provider items (actions',
scriptsor
tags`); - generally it can be created tree with provider items;
- every
provider item
hasisAllowedPredicate
input function to determine current state; - when
update
function executes and:
-isAllowedPredicate
returns true
(build process) - scripts or tags
will be added to DOM, actions
will call onAllow
function;
-isAllowedPredicate
returns false
(destroy process) - scripts or tags
will be removed from DOM, actions
will call onDisallow
function;
- before every build process will be executed destroy process;
update
will be executed (and destroy and build or destroy processes) everytime when event fromevents
is fired;- initially
update
will be executed once, no matter was any event fired or not;
Example
import { Component } from '@angular/core';
import { ProviderService } from 'bitergo-common';
import { CookieStatusNotificationService } from 'langs-cookie-consent';
import { providers } from './langs-cookie-consent.configuration';
import { MatomoTracker } from 'ngx-matomo';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.scss']
})
export class AppComponent {
tagManagerScriptSource = 'https://www.googletagmanager.com/gtag/js?id=AW-12312321321';
gtagScriptSource = '/assets/scripts/gtag.js';
linkedInScriptSource = '/assets/scripts/linkedin.js';
linkedInNoScriptSource = 'https://px.ads.linkedin.com/collect/?pid=32132132&fmt=gif';
get isMatomoAllowed() {
return this.cookieStatus.isProviderAllowed(providers.matomo);
}
get isGoogleAddsAllowed() {
return this.cookieStatus.isProviderAllowed(providers.google_ads);
};
get isLinkedInAllowed() {
return this.cookieStatus.isProviderAllowed(providers.linked_in);
}
constructor(
private matomo: MatomoTracker,
private providerService: ProviderService,
private cookieStatus: CookieStatusNotificationService,
) {
const { accepted, closed, rejected } = this.cookieStatus;
this.providerService.update({
isEnabledLogging: true,
providers: [
// first provider
{
isAllowedPredicate: () => this.isMatomoAllowed,
actions: [{
onAllow: () => this.matomo.rememberConsentGiven(),
onDisallow: () => this.matomo.forgetConsentGiven(),
tags: [{
tagName: 'div',
attributes: { 'className': 'test' }
}]
}]
},
// second provider
{
isAllowedPredicate: () => this.isGoogleAddsAllowed,
scripts: [
{
src: this.tagManagerScriptSource,
scripts: [{
src: this.gtagScriptSource,
removeQueries: [
'body script[src*=googleadservices]',
'body iframe[src*=doubleclick]'
]
}]
}
]
},
// third provider
{
isAllowedPredicate: () => this.isLinkedInAllowed,
scripts: [
{
src: this.linkedInScriptSource,
tags: [{
tagName: 'img',
attributes: {
src: this.linkedInNoScriptSource,
alt: 'None',
width: '1',
height: '1'
},
style: { display: 'none' },
removeQueries: ['body script[src^="https://snap.licdn.com"]']
}]
}
]
}
],
events: [accepted, closed, rejected]
})
}
}
Example explanation
In example above we want to keep the state of scripts according with Cookie Consent banner.
In the banner we have three sliders: Matomo, Google Ads and Linked.
Depends on slider state - provider scripts/actions/tags should be added or removed. We want also update that state when Cookie Consent banner is accepted, closed or rejected.
In first scenario, if Matomo slider is toggled on (isMatomoAllowed
getter):
onAllow: () => this.matomo.rememberConsentGiven()
will be exectuted;- Then
div
tag withclass
test
will be added;
In second scenario, if Google Adds slider is toggled on (isGoogleAddsAllowed
getter):
- Will be loaded script
tagManagerScriptSource
; - Then will be loaded
gtagScriptSource
script;
If Google Adds slider is toggled off - after removing gtagScriptSource
script - will be removed all tags that matched queries:
removeQueries: [
'body script[src*=googleadservices]',
'body iframe[src*=doubleclick]'
]
The only one difference in the third scenario: after script is loaded - will be loaded tag image
with attrbites and styles.
Count of nested provider items
or amount of them is not limited.
Interfaces
import { Subject } from 'rxjs';
export interface ProviderNextOptions {
scripts: ScriptOptions[];
tags: TagOptions[];
actions: ActionOptions[];
}
export interface ProviderRemoveTagOptions {
removeQueries: string[];
}
export interface ProviderCommonTagOptions {
parentQuery: string;
}
export interface ScriptOptions extends
Partial<ProviderNextOptions>,
Partial<ProviderRemoveTagOptions>,
Partial<ProviderCommonTagOptions> {
src: string;
}
export interface TagOptions extends
Partial<ProviderNextOptions>,
Partial<ProviderRemoveTagOptions>,
Partial<ProviderCommonTagOptions> {
tagName: keyof HTMLElementTagNameMap;
attributes?: Record<string, string>;
style?: Partial<CSSStyleDeclaration>;
}
export interface ActionOptions extends Partial<ProviderNextOptions> {
onAllow: () => void;
onDisallow: () => void;
}
export interface ProviderOptions extends Partial<ProviderNextOptions> {
isAllowedPredicate: () => boolean;
}
export interface ProviderServiceOptions {
providers: ProviderOptions[];
events?: Subject<any>[];
isEnabledLogging?: boolean;
}
export interface ProviderRemoveOptions {
index?: string;
element?: string;
removeAction?: () => void;
next: Partial<ProviderNextOptions> & Partial<ProviderRemoveTagOptions>;
}