@costellodev/biscuit-bar v1.0.2

Biscuit Bar - Docs

Welcome

Welcome to the documentation for Biscuit Bar for Angular! This library provides a component that allows users to specify their cookie preferences for the application they are using. This README file provides an overview of the component's features, its available inputs, and how to use them.

The library emits the most up-to-date preferences via an observable available in the service exposed to the user named BiscuitBarService.

The bar assumes two states:

• Expanded: Before any interaction with the cookie preferences form and making a selection.
• Condensed: Once selection has been made and allowing the user to revise it at any time.

Important!

This library is only meant to compliment your data privacy compliance workflow if you think it's appropriate for your product's needs. It should not be perceived as a comprehensive solution for all your data privacy requirements. The responsibility for understanding and assessing your data privacy obligations remains solely with you.

Installation

This tutorial assumes you’ll be using a .tgz archive containing the library files.

1. Copy the .tgz archive to your location. You might consider keeping it alongside other files within your workspace, so that it comes within the scope of your repository.

2. Open a terminal window and navigate to the root directory of the destination project.

3. Install the library in the terminal with the command:

npm install /path/to/biscuit-bar.tgz

4. Biscuit Bar (as biscuit-bar) package will be installed and added to the dependencies section of the package.json file in your project.

5. In the consumer app’s AppModule, import the library’s module at the top and include it in the imports array:

import { BiscuitBarModule } from '@Costello-dev/biscuit-bar';



//...



imports: [

/...

BiscuitBarModule,

],

6. In the consumer app’s AppComponent.ts file, create a new BiscuitBarConfig instance and provide the configuration for the library.

The most minimal, workable BiscuitBarConfig looks like this:

myBiscuitBarConfig = new BiscuitBarConfig(
  {}, // Appearance Config

  [] // Cookie Types conforming to type ```CookieTypes```
);

7. In the consumer app’s AppComponent HTML Template, add the biscuit-bar component.

Remember to include your BiscuitBarConfig instance in the [configInstance] input.

<biscuit-bar [configInstance]="config"></biscuit-bar>
<div>
<app-toolbar></app-toolbar>
<router-outlet></router-outlet>
/...

</div>

8. You may use BiscuitBarService across your app to interact with the library outside of the static configuration. It comes with a number of useful functions and works just like any other Angular service - just include it in your component's constructor:

constructor(private biscuitBarService: BiscuitBarService) {}

Define Your Cookie Types

There are no cookie types defined by default - the library's cookie preference form will show an empty grid.

The configuration should be provided as an array.

Constructing an object representing a cookie type

BiscuitBarCookieTypes - This type represents an array of pre-defined cookie type. It includes the following properties:

Here's the table for the CookieType type:

Including Custom Template in Blank Spaces

You can customise the bar even further by including your own template. You may, for instance, have a link to your privacy policy. Include the attributes expanded and condensed in your template to make sure it's displayed in the relevant state.

No text is included by default without anything else; however:

• If you have included the value for preferencesGuidanceLong in the appearance config (more below) and without supplying the template, that string of text will be displayed in the bar's empty space in its expanded state.
• If you have included preferencesGuidanceShort without supplying the template, that string of text will be displayed in the bar's empty space in its condensed state.

The following example is just for demonstration of the technical ability to display a template.

<biscuit-bar [configInstance]="config">

  <div expanded>
    <p>
      We need your consent for using cookie files. Read our
      <a>Privacy Policy</a> to learn more.
    </p>
  </div>

  <div condensed>
    <a>Privacy Policy</a>
  </div>

</biscuit-bar>

Configuring Appearance

The library comes with default styling based on css tokens (e.g. --some-colour-one).

If your consumer app uses an Angular Material version injecting tokens as part of the app's theming (tested with AM ver. 16+), Biscuit Bar will integrate those Material colour values and adjust its own theming accordingly.

Alternatively, you can always take advantage of the AppearanceConfig and granularly customise the look of the library.

AppearanceConfig accepts the following values:

• Colours as you'd define them in your stylesheet (e.g. HEX values, CSS colour names, etc.)

• Font-family names for typography as you'd define them in your stylesheet.

• Your own tokens for colours or font-family names available across your app (e.g. --my-primary-colour).

• Strings of text to be shown in critical places across the library.

• Strings of text or boolean values representing a determinate configuration value (e.g. 'bottom' for positioning).

The BiscuitBarAppearanceOptions type combines the following properties. Each one is optional and can be used to adjust a specific aspect of the library's appearance.

Packaging of New Builds

1. In the main directory of the canvas workspace type in ng build biscuit-bar which will create a build folder with the library.

2. Navigate to the dist folder where the contents of the build are located and open it in terminal.

3. Type in npm pack which will generate a .tgz package (without publishing it online).

4. The .tgz package is fully portable and you can place it wherever you might need it.

Troubleshooting

NodeJS.Timeout - Wrong namespace?

1. Navigate to tsconfig.app.json within your destination app.

2. Add node to your types array:

/* To learn more about this file see: https://angular.io/config/tsconfig. */



{

"extends": "./tsconfig.json",

"compilerOptions": {

"outDir": "./out-tsc/app",



// *** THIS ONE ***

"types": ["node"]

},

"files": ["src/main.ts", "src/polyfills.ts"],

"include": ["src/**/*.d.ts"]

}

3. Restart your app to apply the new changes.