README.md

ngOnboarding

ngOnboarding is a tooltip tutorial / onboarding framework for Angular.js that can help give your user a better onboarding experience. The API is still in flux and it is not well-tested, so be aware before using it in production.

Dependencies

This library requires Angular.js 1.2 or greater along with any recent version of jQuery.

Demo

You can find a very simple example of ngOnboarding here.

The Basics

To use the library, add the JS and CSS file, then include the module in your app

app = angular.module("myApp", ["ngOnboarding"])

Next, you'll need to configure the steps for the onboarding experience. The configuration is an array of objects, each representing a single popover. Here is an example configuration containing 2 popovers:

$scope.onboardingSteps = [
  {
    title: "Welcome!",
    position: "centered",
    description: "Welcome to my app!",
    width: 300
  },
  {
    title: "Account Setup",
    position: "right",
    description: "This is the form for configuring your account.",
    attachTo: "#account_form",
    position: "bottom",
    onNext: function (currentStep) { alert('Next button clicked, current step ' + currentStep);     },
    onPrev: function (currentStep) { alert('Previous button clicked, current step ' + currentStep); }
  }
];

The directive itself is called onboarding-popover. There are 2 required inline attributes.

• enabled should be set to a boolean scope variable that controls whether the onboarding UX is displayed.
• steps should point to the steps configuration.

There are also 2 optional inline attributes.

• onFinishCallback should point to a function that will be called when the user either clicks the Close or Done button. This is a good place to set a cookie to disable showing the on-boarding UX every time.
• stepIndex is an integer that controls the current step being shown. It will default to 0 if not set explicitly.

<onboarding-popover enabled="onboardingEnabled" steps="onboardingSteps" on-finish-callback='myCallbackFunction()' step-index='onboardingIndex'></onboarding-popover>

Step Configuration Options

There are a number of options that can be passed to each step in your on-boarding process. These are set in the array of step objects, as shown above.

Option	Default
Title	null	Title of the popover
description	null	Content of the popover. May contain HTML.
attachTo	null	CSS selector for the element to attach to. Optional
position	null	Position of the tooltip relative to the attached element. Optional. Accepted values are 'left', 'right', 'top', 'bottom', or 'centered', All but centered require that attachTo is set.
width	null	Width of the popover. Defaults to the width of the content.
height	null	Height of the popover. Defaults to the height of the content.
top, right, bottom, left	null	Set the positioning of the popover explicitly.
height	null	Height of the popover. Defaults to the height of the content.
xOffset	null	Offset the horizontal position of the popover relative to the attached element.
yOffset	null	Offset the vertical position of the popover relative to the attached element.

Overriding Directive Defaults

You can also pre-configure some options during your app's configuration phase.

app.config(function(ngOnboardingDefaultsProvider) {
  ngOnboardingDefaultsProvider.set('option', 'value');
  // Or with a hash
  ngOnboardingDefaultsProvider.set({option: 'value', option2: 'value2'});
})

Option	Default
overlay	false	Use a modal overlay for popovers by default
overlayOpacity	0.6	Opacity of the modal overlay
showbuttons	true	Show the next and previous buttons
showDoneButton	true	Show a 'Done' button on the last popover
showStepInfo	true	Shows 'Step X of Y' text on each popover
closeButtonText	X	Text/HTML used for the close button

The CSS classes used in the HTML are also configurable. Please see the source for more info.

Browser Support

So far, it has only been tested in Chrome. There is some CSS that is not compatible with with older browsers, including IE9.

Future Updates

1. Test coverage
2. Ability to add an enter and leave callback to every step.

Contributing

Contributions are welcome. Whenever possible, please include test coverage with your contribution.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

To get the project running, you'll need NPM and Bower. Run npm install and bower install to install all dependencies. Then run grunt in the project directory to watch and compile changes. And you can run karma start to watch for changes and auto-execute unit tests.

Credit

Much of the CSS consists of tweaked versions of several Bootstrap components. The API was partially inspired by a jQuery plugin called Guiders.js, though none of its code was used. And the styling was partially inspired by Tourist.js, though again, no code was used.