ng-onboarding v0.1.7

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"
  }
];

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.

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'});
})

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.