yamazaki93/ngy-tutorial

An Angular plugin that gives your app a "getting started" tutorial

ngy-tutorial

Ngy-Tutorial is an Angular plugin that gives your Angular app a built-in, customizable, user-friendly, literally "getting started" 🤓 tutorial.

So you've got your killer UI that's intuitive, slick and responsive, but will everyone know how to use it? What about some nice shortcuts or features that you want to highlight? Or maybe some UI changes that you want the users to be aware of? No one really wants to read through a long readme file, so how about an interactive, in-app tutorial? Ngy-Tutorial literally adds a step-by-step "tutorial" to your app so you can highlight your cool UI and give every user a head start.

Check out the Demo Site!

Change Notes:

0.1.5:

• Added support for small screen/mobile devices, the prompt now enlarge to the screen size on smaller devices.
• Added detection of covered and out of view element. If the element of interest in the viewing window is covered significantly by the prompt or it is out of the viewing area, the next button will be automatically enabled. This prevents un-finishable tutorial, especially in smaller screens.

Highlghts

• Customizable steps that allows you to add and remove steps on the fly.
• Per-step adjustable "viewing window" that hightlights any revelant element by DOM id.
• Ability to allow/disallow interaction with your app while the tutorial is progressing.
• Programmatic navigation and control allows you to customize the tutorial experience to your need.
• Customizable prompt and button styling.

Built With

Demo page is built with Argon Dashboard from CreativeTim and IonIcons

Installation

Add the library by using npm with npm install ngy-tutorial or yarn with yarn add ngy-tutorial

Tested under Angular 6

Getting Started (even the tutorial needs a tutorial)

1. Install the package with npm or yarn.

2. Add the module to your root module with NgyTutorialModule.forRoot() under imports in your app.module.ts.

       @NgModule({
       declarations: [
           AppComponent
       ],
       imports: [
           BrowserModule,
           NgyTutorialModule.forRoot()
       ],
       providers: [],
       bootstrap: [AppComponent]
       })
       export class AppModule { }

3. Place element <lib-ngy-tutorial></lib-ngy-tutorial> in your app.

4. You can now inject and use NgyTutorialService service to control the tutorial, see the API for available commands and options.

FAQ and Notes

• Note, scrolling in the viewing window: The viewing window allows all interaction including scrolling, which means user can scroll the intended element away during the tutorial. Your app should disable scrolling during the tutorial if scrolling is not desired.
• The tutorial doesnt start? Try calling NgyTutorialService.showTutorial() in or after ngOnInit.
• Some elements are overlaying on top of the prompt? Try setting the z-index of <lib-ngy-tutorial></lib-ngy-tutorial> to be higher than other elements. This issue can happen if you already elements with z-indices. Also be sure to place <lib-ngy-tutorial> towards the end of your page.

Current Limitations & Future Plans

There are currently few limitations of Ngy-Tutorial and some will be improved in the future.

• Changing window size during tutorial is buggy: Changing window size during tutorial currently will cause issues.
• Scrolling support: The tutorial currently is limited to single-view layout tutorials. In the future it is planned to support scrolling to element.
• Square view window only: Because of the way how "covers" are layed out, the preview window that hightlight an element is square only.