ngx-onboarding

An onboarding library for Angular applications.

Overview

The onboarding library gives you the possibility to add a tutorial directly into your angular application. After that users learn easily how to use your application and the learning curve is not so high.

You can specify an onboarding element on every html element you want.

Features

• Definition of several steps on each view.
• Highlighting of every step.
• Configurable on which position (top, bottom, left or right) the information text should be displayed.
• Multiple language support
• If onboarding is enabled, buttons are visible to switch to the next step or turn off onboarding
• If a user has seen the onboarding of a view, it will be stored per default to the local storage of the browser.
• Possibility to reset and turn on again the onboarding.

Installation

The library is published as a scoped NPM package in the NPMJS Rosen-Group account

npm install --save @rosen-group/ngx-onboarding

Peer Dependencies

• angular-material
• @angular/cdk

For detailed information how to use Angular material please have a look at the Angular material getting started page and follow the installations instructions.

Usage

Add the rosen-onboarding-component anywhere to your main component, e.g. app.component

<rosen-onboarding></rosen-onboarding>

Add the material icons reference to the index.html

<link href="//fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">

The onboarding library contains a button component which provides a context menu for resetting and turning on/off the onboarding feature. Place this button into your application where you want.

<rosen-onboarding-button title="ONBOARDING"></rosen-onboarding-button>

Add the OnboardingModule and it's dependencies to your module, e.g.

    imports: [
        BrowserModule,
        BrowserAnimationsModule,
        HttpClientModule,
        MatIconModule,
        MatButtonModule,
        OnboardingModule
    ]

Add some styles, e.g. to your app.component.css ()

@import "~@angular/material/prebuilt-themes/indigo-pink.css";

And don't forget to bundle it to your output, e.g. in your angular.json

"styles": [
 "src/styles.css",
 "node_modules/@angular/material/prebuilt-themes/indigo-pink.css"
]

The messages will be configured in JSON files.

Place the JSON file(s) where you are able to load them during application runtime. For example if you are using angular-cli, copy them in an assets subfolder and add the folder to your assets array in the angular.json config file.

Example for JSON configuration file containing onboarding messages

[
    {
        "selector": "#logo-img",
        "group": "example0",
        "position": "top",
        "headline": "Angular Logo",
        "details": "This is the angular logo",
        "descriptions": [
            {
                "language": "de",
                "headline": "html tag headline de",
                "details": "htmp tag details de"
            }
        ]
    },
    {
        "selector": "#button-that-needs-onboarding",
        "group": "example1",
        "position": "right",
        "textAlign": "left",
        "headline": "What is behind me?",
        "details": "You have to learn a lot about this button",
        "descriptions": [
            {
                "language": "de",
                "headline": "html tag headline de",
                "details": "htmp tag details de"
            }
        ]
    }
]

(Use a selector that exists in your application, e.g. h2 in a plain Angular-CLI application)

Property descriptions

Inject the OnboardingService into your component and load the configuration JSON file.

export class AppComponent implements OnInit, OnDestroy {
     private unregisterOnboarding: Function;
    
     constructor(private onboardingService: OnboardingService,
                 private httpClient: HttpClient) { 
     }
     
     public ngOnInit() {
         this.httpClient.get('assets/onboarding/example.json').subscribe((onboardingItems: Array<OnboardingItem>) => {
             this.unregisterOnboarding = this.onboardingService.register(onboardingItems);
         }, (error) => {
             // do your error handling
         });
     }
     
     public ngOnDestroy() {
         if (this.unregisterOnboarding) {
             this.unregisterOnboarding();
         }
     }
 }

Translations (I18N)

See I18N instructions

Browser Support

• Chrome
• Firefox
• Edge
• Internet Explorer 11 (with polyfills)

For Contributors

See CONTRIBUTING