For step-by-step instructions, check out our Implementation and Style Guides
For live demos and code samples, check out our Examples Page and Github Page

Quick Start

1

Sign up for an Onboarded account.


2

Include our Onboarded javascript in the <head> of your document:

1
<script src="https://d237d8mq680mpf.cloudfront.net/onboarded-js/latest/onboarded-js.min.js"></script>

3

Insert your project token, and implement your Onboarded flow:

1
2
3
4
5
6
7
8
9
10
11
12
<div data-onboarded-token="PROJECT-TOKEN" style="display: none;">
  <div data-onboarded-flow="My Awesome New Flow">
        <div data-step="Welcome">
            <!-- Step 1 content -->
            <button data-name="Go To Second Step" data-action-next="Second Step">Go to 2nd step</button>
        </div>
        <div data-step="Second Step">
            <!-- Step 2 content -->
            <button data-name="End Flow" data-action-complete>Finish</button>
        </div>
    </div>
</div>

Requirements

  • jQuery 1.7 or newer (Loaded asynchronously by the onboarded-js javascript, unless you’ve manually included it)
  • the Onboarded jQuery Plugin (Loaded asynchronously by the onboarded-js javascript)
  • Your markup is HTML5

Onboarded Basics

Starting A Project

The Onboarded Javascript will auto load some dependencies required to setup the your flow. Just include it in the <head> of your document, as shown in the Quick Start and Javascript Usage. It is easily configurable and customizable via data-attributes. See Configuration Options for more details.

The markup defining any flow must be contained inside html tags with a data-onboarded-token attribute.

The value of this attribute is a Public Project Token. This token is generated for each project you create and can be found on the introductory setup page for your project. You can also retrieve it later on your project settings page (accessible via the projects menu in your logged in dashboard).

The data-onboarded-token attribute and Public Project Token value are required in order to render your flow on the page and for communication with the Onboarded API.

Example:

1
2
3
<div data-onboarded-token="PROJECT-TOKEN">
  <!-- Some Flow Content -->
</div>

Specifying Users

By default, the API will assign a random unique identifier for each distinct visitor of your Onboarded project.

Optionally, you can specify your own unique identifier for a known user, e.g. a logged in user’s email address, username, etc. While the specified identifier must be unique within a project, it will be used across any flows defined for that project.

Example:

1
2
3
<div data-onboarded-token="PROJECT-TOKEN" data-onboarded-user="UNIQUE-ID">
  <!-- Some Flow Content -->
</div>

Defining Flows

All flows must be contained inside html tags with a data-onboarded-token attributes, as specified above.

Each flow is defined by adding html tags with the data-onboarded-flow attribute. The value of the attribute should be a unique label or identifier for that flow.

Example:

1
2
3
4
5
6
7
<div data-onboarded-token="PROJECT-TOKEN">

  <div data-onboarded-flow="my-flow">
    <!-- Some Content -->
  </div>

</div>

You may place as many flows as you’d like inside a project:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<div data-onboarded-token="PROJECT-TOKEN">

  <div data-onboarded-flow="first-flow">
     <!-- Some Content -->
  </div>

  <div data-onboarded-flow="second-flow">
    <!-- Some Other Content -->
  </div>

  <div data-onboarded-flow="an-awesome-flow">
    <!-- Some Awesome Content -->
  </div>

</div>

Adding Steps

Once a flow is defined, it can contain any number of steps.

A step is defined by adding a data-step attribute to any html element contained inside the flow tags. The attribute value should specify a label or identifier for that step. This step label should be unique within a flow.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
...
  <div data-onboarded-flow="awesome-flow">
    <div data-step="first">
      <!-- Some Content -->
    </div>

    <div data-step="second">
      <!-- Some Awesome Content -->
    </div>

    <div data-step="third">
      <!-- Even More Awesome Content -->
    </div>
  </div>
...
Completion Content

In addition to steps, a special completion content block may optionally be defined on a flow. If defined, the completion content will render for a user who has completed the flow. If left undefined, a completed flow will be hidden from the user.

A flow may only have one defined completion content block.

NOTE: A completion content block is not a step. As it is not intended to be submitted, no data from a completion content block is tracked.

Example:

1
2
3
4
5
6
7
8
9
10
11
...
  <div data-onboarded-flow="awesome-flow">
    ...
    <!-- Some Steps -->
    ...

    <div data-complete>
      <!-- Content For a Completed Flow -->
    </div>
  </div>
...

Adding Content

The content you add to a step is completely up to you. We provide a set of data-attributes to specify the action(s) available for the user to take, and the named data, if any, to keep track of.

Actions

It is important to note that the action taken for a given step is also defines the sequence of steps in a flow. Therefore, every step must have at least one action. For more complex flows, like branching decision trees, you may use multiple actions.

There are two types of actions: next and complete. A next action is specified with the data-action-next attribute, and should have a value that points to another step label in the flow. A complete action is specified with the data-action-complete attribute, and will complete a flow.

NOTE: In order to mark a flow as completed over the API (and receive analytics on flow completions), you must have have a data-action-complete attribute defined for that flow.

If a flow has a defined completion content block with the data-complete attribute mentioned in the Adding Steps section above, then the data-action-complete completion action will render that content.

1
2
3
4
5
6
7
8
9
10
11
...
  <div data-step="first">
    <!-- Some Content Here -->
    <button data-action-next="another">Next Step</button>
  </div>

  <div data-step="another">
    <!-- Some Other Content Here -->
    <button data-action-complete>Finished</button>
  </div>
...
Named Data

Named data is sent back to the our API as a user interacts with a flow / step, is used to generate analytics, and is persisted for later retrieval.

To track actions, you should specify a data-name attribute on all actions as well.

When a user first visits a step, the named data hash will be initialized with false values and sent back to the Data API. Similarly, when a user proceeds to the next step (or completion step), the named data hash is updated with the user provided values, and sent back to the Data API.

Inputs

To collect input from a user, use html input tags and specify the data-name attribute to add the input to the named data hash for your Onboarded flow.

Supported html input types are:
text, textarea, checkbox, radio, select, multiselect, button, submit

Button and Submit inputs will track with true or false, just as html button tags do.

Example:

1
2
3
4
5
6
7
...
  <div data-step="first">
    <input type="text" data-name="text-prompt">
    <input type="textarea" data-name="description">
    ...
  </div>
...

In addition to tracking user inputs, you may track user clicks. Simply add a data-name attribute to a link or a button. The value will be tracked as true or false in the named data hash.

1
2
3
4
5
6
7
8
...
  <div data-step="first">
    <a href="#" data-name="example-link">A Link</a>
    <button data-name="example-button">A Button</button>

    <a href="#" data-name="proceed" data-action-complete>Continue...</a>
  </div>
...

Advanced

Forms

In addition to tracking user inputs in a standalone manner, you can place entire html forms inside your steps. It is important to note, all form submissions will be disabled. Instead, the form data is serialized and added to the named data hash. Specify inputs to be tracked with the data-named attribute as before, or alternatively the html input name attribute.

If you want to receive your form data, you may use the javascript events to send the data asynchronously to wherever you’d like. See Send Step Data Anywhere for more details.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
...
  <div data-step="step-with-a-form">
    <form action="DOESN'T MATTER; MAY BE OMITTED">
      <input type="text" data-name="first-name">
      <input type="text" name="last-name">
      <select name="favorite-color">
        <option>Red</option>
        <option>Green</option>
        <option>Blue</option>
      </select>
      <input type="submit" name="send" value="Send" data-complete>
    </form>
  </div>
...
Branching Flows

In addition to simple linear flows, you can specify more complex branching flows. Just add extra actions to a given step, as specified in the Actions documentation.

Examples:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
...
  <div data-onboarded-flow="complex-example">
    <section data-step="start">
      <h2>Choose a side!</h2>

      <button data-name="hero" data-action-next="hero">I'm a Hero</button>
      <button data-name="villain" data-action-next="villain">I'm a Villain</button>
    </section>

    <section data-step="hero">
      <h2>Hero Details:</h2>

      <input type="text" name="hero[name]" placeholder="Name of Hero:">
      <input type="text" name="hero[color]" placeholder="Color of Mask:">

      <button data-name="hero[save_the_world]" data-complete>Save The World</button>
    </section>

    <section data-step="villain">
      <h2>Villain Details:</h2>

      <input type="text" name="villain[name]" placeholder="Name of Villain:">
      <input type="text" name="villain[color]" placeholder="Color of Mask:">

      <button data-name="villain[destroy_the_world]" data-complete>Destroy The World</button>
    </section>

    <section data-complete>
      <h2>You've completed your registration!</h2>
    </section>
  </div>
...
Data attributes for controlling specific steps
Focus an element on the page

Use these data attributes to add a focus class to selected elements on the page. Useful for highlighting specific page elements on any given step in a flow.

If no elements matching the selector are found in the DOM, the attribute is ignored.

HTML5 data-attribute Default Description
data-focus-selector   Add the focus classname to the element(s) matched by the CSS selector.
data-focus-classname onboarded-focused The class to add to the matched element(s).

Example Usage:

1
2
3
4
5
<div data-step="first"
     data-focus-selector="#awesome-div"
     data-focus-classname="highlight">
  <!-- Some Content Here -->
</div>
Scrolling the page

The scrollTo data attribute will scroll the page to the first element on the page matched by the selector. Currently, only vertical scrolling is supported.

If no elements matching the selector are found in the DOM, the attribute is ignored.

HTML5 data-attribute Default Description
data-scrollTo-selector   Scroll the page to the element(s) matched by the CSS selector.
data-scrollTo-offset ‘0’ The scroll offset, in pixels. A negative value offsets up the page.

Example Usage:

1
2
3
4
5
<div data-step="first"
     data-scrollTo-selector="#awesome-div"
     data-scrollTo-offset="10px">
  <!-- Some Content Here -->
</div>
Positioning a step on the page

The position data attribute allows for positioning of a rendered step within the current viewport. Positioning is accomplished be specifying a target element on the page, and defining the edges of the target element and the step which should be positioned together. An optional offset can be specified to adjust the exact positioning of the two elements.

HTML5 data-attribute Default Description
data-position-selector   Position the rendered step relative to the first element matched in the DOM by the CSS selector.
data-position-target ‘top left’ The side of the selected target element to position against the step.
data-position-step ‘top right’ The side of the rendered step to position against the target element.
data-position-offset ‘0px 0px’ The scroll offset, in pixels or percent. The offset is specified as verticalOffset horizontalOffset. A negative value offsets up or to the left of the page, respectively.

The positioning of the selected target and the rendered step can be as follows:

  • The positioning should be specfied as a string in the format of 'verticalPosition horizontalPosition'
    • verticalPosition can be any of 'top', 'middle', 'bottom'
    • horizontalPosition can be any of 'left', 'center', 'right'

Example Usage:

1
2
3
4
5
6
7
<div data-step="first"
     data-position-selector="#awesome-div"
     data-position-target="bottom right"
     data-position-step="top left"
     data-position-offset="10px 2%">
  <!-- Some Content Here -->
</div>
NOTE: When using the positioning feature, keep the following to things in mind:
  • Positioned steps are relocated in the DOM to be direct children of the <body> node.
  • Positioned steps will have their style set to position: fixed.

Attribute Overview

Data Attribute Description
data-onboarded-token An Onboarded container must have a project token to communicate with the API server.
data-onboarded-user An Onboarded flow can optionally have a user set to a unique identifier; if none is provided, one will be randomly generated by the API.
data-onboarded-flow An Onboarded flow should have a unique label/identifier, and it should contain any number of steps.
data-step An Onboarded step should have a unique label/identifier
data-complete A completed step, to show when all other steps are complete. (Optional)
data-action-next The label of the next step to go to.
data-action-complete The next step completes the flow
data-name Step data to send back to the api

OnboardedJs

The OnboardedJs library simplifies how developers can use Onboarded. OnboardedJs asynchronously loads all necessary javascripts from a CDN, while providing a simple set of configuration options. A ‘convention over configuration’ approach is utilized, so your flows will work with no configuration at all.

Javascript Usage

There are two ways to use the OnboardedJS library. The first, and simplest, is to configure the script tag where it is sourced with data-* attributes, and let everything autoload. The second is to disable the autloading feature, and instead pass the configuration options as JSON into the OnboardedJs.configure() method.

See Configuration Options for a listing of possible options.

Method 1:

Place the following snippet in the <head> of your html document:

1
2
3
4
<script src="https://d237d8mq680mpf.cloudfront.net/onboarded-js/latest/onboarded-js.min.js"
        data-verbose="true"
        data-style="false">
</script>

Make sure you have defined a flow (See Onboarded Basics) on your page, and thats it.

You may update data-attributes (like the data-verbose) to change the configuration.

Method 2:

Alternatively, you can configure the library with a JSON options hash. For this to work, you must disable the autoloading functionality with a data-autoload="false" attribute in the source script.

Place the following snippet in the <head> of your javascript:

1
2
3
4
5
6
7
8
<script src="https://d237d8mq680mpf.cloudfront.net/onboarded-js/latest/onboarded-js.min.js" data-autoload="false"></script>
<script>
    // Asynchronously load and instantiate Onboarded Javascripts
    OnboardedJs.configure({
        verbose: "true",    // Show extra logging in the console
        style: false        // Disable the default styling
    });
</script>

Make sure you have defined a flow (See Onboarded Basics) on your page, and thats it.

Finished Loading Callback

It is possible to have a callback function execute once the javascripts are loaded in the DOM.

NOTE: The following three methods, are functionally equivalent. You may choose which style best suits your needs.

Setting a Callback via HTML5 Data Attributes

If using the loader script with auto-loading See Method 1, define a function in the global namespace, and set a data-finished-loading attribute on the loader script:

1
2
3
4
5
6
7
8
9
<script src="https://d237d8mq680mpf.cloudfront.net/onboarded-js/latest/onboarded-js.min.js"
        data-finished-loading="myCallback">
</script>

<script>
  window.myCallback = function () {
    // Some behavior to run when done loading the plugin and its dependencies.
  }
</script>
Setting a Callback Using Javascript

If using a JSON options hash to manually load the jquery plugin and its dependencies See Method 2, there are two ways to specify a finishedLoading callback function. You can either provide a callback function as a second parameter to the OnboardedJs.configure() method, or you can specify the callback function inside the OnboardedJs.configure() options hash. These callbacks can be anonymous functions, or declared named functions.

With the OnboardedJs configure() method call

Pass an anonymous callback as the second parameter to the OnboardedJs.configure() method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<script src="https://d237d8mq680mpf.cloudfront.net/onboarded-js/latest/onboarded-js.min.js"
        data-autoload="false">
</script>

<script>
    // Asynchronously load and instantiate Onboarded Javascripts,
    // running a callback when finished loading.
    OnboardedJs.configure({
        // Some configurations options
    }, function () {
        // Some behavior to run done loading
        // the plugin and its dependencies.
    });
</script>
With the OnboardedJs configure() options hash

Declare a finishedLoadingCallback option inside the config hash when calling OnboardedJs.configure():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<script src="https://d237d8mq680mpf.cloudfront.net/onboarded-js/latest/onboarded-js.min.js"
        data-autoload="false">
</script>

<script>
    // Asynchronously load and instantiate Onboarded Javascripts,
    // running a callback when finished loading.
    OnboardedJs.configure({
      finishedLoadingCallback: function () {
          // Some behavior to run done loading
          // the plugin and its dependencies.
        }
        // Some other configurations options
    });
</script>

Configuration Options

General Options:

data-attribute / JSON Type Default Description
data-autoload
autoload
Boolean true Automatically load the jQuery plugin and its dependencies.
data-verbose
verbose
Boolean false Show extra logging information in the javascript console.
data-protocol
protocol
String undefined Sets the protocol (either http or https) over which to load the javascripts. If left undefined, the protocol will be autodetected.
data-finished-loading
finishedLoadingCallback
Function undefined A callback function to execute when the javascript loading is finished. See Finished Loading Callback for more information.

Style Options

The styling of the flow can be specified with the style config option. That is, the data-style attribute if configured inline, or style option key if configured with JSON. If you wish to style things on your own, set the style to false and write your own stylesheet. Below is a table of possible styles:

Style Type Default Description
false   The flow will be un-styled. Use this option to create your own stylesheet. Check out the Style Guides for details on how to style your flows.
'overlay' The flow will be rendered as a modal window with a darkened overlay in the background. See the Overlay Style Options table below for extra configuration parameters specific to the Overlay style.
Overlay Style Options
data-attribute / JSON Type Default Description
data-style-overlay-dismissable
styleOverlayDismissable
Boolean false Setting this option to true will dismiss the modal window when clicking on the overlay, or pressing the <ESC> key.
data-style-overlay-id
styleOverlayId
String 'overlay' The element ID of the overlay div.
data-style-overlay-class-name
styleOverlayClassName
String 'overlay' The element class of the overlay div. Use a space-separated string to set multiple classes.

Flow Options

data-attribute / JSON Type Default Description
data-flow-auto-start
flowAutoStart
Boolean true Automatically start the flow when the javascripts are asychronously loaded. If this option is set to false, then the flow should be manually instantiated, as described in the Onboarded Plugin section.
data-flow-label
flowLabel
Boolean false Set the label option for the Onboarded plugin startFlow() method. By default, the first defined flow in the DOM is started. The label option is used to specify a specific flow to start. If there is only one flow defined, it is started and this option does nothing.
data-flow-skip-api-check
flowSkipApiCheck
Boolean false Set the skipApiCheck option for the Onboarded plugin startFlow() method. This option skips checking the API when starting a flow, to determine the given user’s state in the flow. See the startFlow() documentation for more information on when to use this option.
data-flow-reset
flowReset
Boolean false Set the reset option for the Onboarded plugin startFlow() method. This options resets the flow to the beginning when starting. See the startFlow() documentation for more information on when to use this option.

Onboarded Plugin

As described in the Quick Start and OnboardedJS, you should first load the latest onboarded-js library on your page. Alternatively, you may choose to manually load jQuery from your favorite source, and then include the latest Onboarded jQuery plugin. The information below is intended to serve as an overview of how to use the jQuery plugin.

Plugin Dependencies

  • jQuery, version 1.7 or greater.

Convenience Methods

Onboarded.load()

jQuery.Onboarded

The Onboarded.load() convenience method instantiates the jQuery plugin on the document body. It should be used when the DOM is ‘ready’. It returns the instance of the plugin. Instantiating the plugin actually parses the DOM for a flow, and is required before using Onboarded.

Example:

1
2
3
  jQuery(document).on( 'ready', function () {
    var ob = Onboarded.load();
  });

Onboarded.unload()

Boolean

The Onboarded.unload() convenience method removes the instantiated plugin from the document body. It returns true if the instance was removed, and false if there was no instance found.

1
2
3
  jQuery(document).on( 'ready', function () {
    Onboarded.unload(); // => true || false
  });

Onboarded.retreive()

jQuery.Onboarded | Boolean

The Onboarded.retreive() convenience method will return an existing instance of the Onboarded plugin, or false if there is none.

1
2
3
  jQuery(document).on( 'ready', function () {
    var ob = Onboarded.retrieve(); // => an Onboarded instance || false
  });

Instance Methods

Once you have an instance of the plugin, you can use the following methods to work with your Onboarded flows.

plugin.startFlow( [ ObjectLiteral start_options ] )

jQuery.Onboarded.Flow

The startFlow() method is used to start a flow.

1
2
3
4
  var ob = Onboarded.retrieve();

  // Starts the first flow defined in the DOM
  ob.startFlow();

It receives optional start_options argument. This is an object literal containing either one or both of the following keys:

Option Description
label The label of the flow to start (defaults to the first defined in the DOM).
skipApiCheck Whether or not to query the API for the steps the user has already completed for that flow (defaults to false). This does NOT reset the flow. As long as a user has not refreshed the page, then the flow will resume from where the user left off.
reset If set to true in conjunction with the skipApiCheck option, then the flow WILL be reset, and it will start from the beginning.

Sometimes you might have multiple flows defined on the same page. While the startFlow() method tries to be smart by defaulting to the first defined flow, to start a different flow use the label option:

1
2
3
4
5
6
  var ob = Onboarded.retrieve();

  // Starts a flow labeled 'myFlow'.
  ob.startFlow({
    label: 'Another Flow'
  });

To resume a dismissed flow from where the user left off, start without checking the API for completed steps:

1
2
3
4
5
6
  var ob = Onboarded.retrieve();

  // Starts or resume a flow without checking the API for completed steps.
  ob.startFlow({
    skipApiCheck: true
  });

It is sometimes useful to have a repeating flow, that restarts every the page is visited. To set a repeating flow, start a flow without checking the API for completed steps, and reset it to the beginning:

1
2
3
4
5
6
7
  var ob = Onboarded.retrieve();

  // Starts or reset and restart a flow from the begining.
  ob.startFlow({
    skipApiCheck: true,
    reset: true
  });

plugin.getFlow()

jQuery.Onboarded.Flow

The getFlow() method receives no parameters, and returns the Flow object for the currently started flow, if any. If no flow is started, then it returns false.

1
2
3
4
5
6
  var ob, fl;
  ob = Onboarded.retrieve();
  ob.startFlow({label: 'Awesome Flow'});

  // Get the Flow object for 'Awesome Flow'
  fl = ob.getFlow();

plugin.setCurrentFlow( [ label ] )

String

This method sets the current flow pointer for the plugin. It optionally receives a flow label. If the flow label is omitted, it defaults to the first defined flow in the DOM. It returns the label of the flow that it just set to the pointer.

Note that this method only updates the current flow pointer for the plugin; it does not render anything.

1
2
3
4
5
  var ob;
  ob = Onboarded.retrieve();

  // Set the flow pointer of the plugin to the first flow.
  ob.setCurrentFlow();

plugin.dismissFlow()

jQuery.Onboarded

The dismissFlow() method dismisses a started flow by emptying the renderContainer and hiding it in the DOM. To start the flow again, simply call startFlow() on the plugin instance. This method returns the plugin instance, to allow for easy method chaining.

Additionally, this method triggers the onboarded:flow:onDismissal and onboarded:flow:afterDismissal events on the DOM around the actual dismissal. See Plugin Events for more information on handling events.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
  var ob;
  ob = Onboarded.retrieve();
  ob.startFlow({label: 'Awesome Flow'});

  // Dismiss the started 'Awesome Flow'
  ob.dismissFlow();

  // Restart the flow from where left off
  ob.startFlow({label: 'Awesome Flow'});

  // Dismiss and restart the already started 'Awesome Flow'
  ob.dismissFlow().startFlow({
    label: 'Awesome Flow',
    skipApiCheck: true,
    reset: true
  });
plugin.resetFlow()

jQuery.Onboarded

This method resets the current flow. Internally, it calls the flow.reset() method on the flow. This method returns the plugin instance, to allow for easy method chaining.

Like flow.reset(), this method triggers the onboarded:flow:onDismissal and onboarded:flow:afterDismissal events on the DOM around the actual dismissal.

See Plugin Events for more information on handling events.


plugin.getProjectToken()

String

This method returns the project token as parsed from the DOM when the plugin was initialized.

1
2
  var ob = Onboarded.load();
  ob.getProjectToken(); // => 'w8_3rmHljXnwt-04nBcC'

plugin.getParsedUser()

String | Boolean

This method returns the user identifier as parsed from the Onboarded project definition in the markup. If no user is defined, then it returns false.


plugin.getUser()

String | Boolean

This method returns the user-project-registration token received by the API when the plugin was initialized. The user-project-registration token should be used when manually starting a flow by calling start on a flow object.

If there is no user-project-registration token, then it returns the parsed user identifier.

See Advanced Usage and flow.start() for more info.

1
2
  var ob = Onboarded.load();
  ob.getUser(); // => 'Nisy4hx7aD-nc62oaG_y'

plugin.updateRenderContainer( String content )

jQuery.Onboarded

This method updates the renderContainer with the content given. This method will trigger the onboarded:onRender and onboarded:afterRender events on the DOM. See Plugin Events for more information on handling events.

1
2
3
4
5
  var ob = Onboarded.load();
  ob.startFlow();

  // Add custom content to the renderContainer
  ob.updateRenderContainer("Some Custom Content");

Be careful with this method, as you can set content to the render container without any actions bound to it, breaking your flow. If this happens, you could recover by dismissing the flow and starting it again (not restarting it).

1
2
3
  // Dismiss and start the default flow,
  // resuming at the first incomplete step.
  ob.dismissFlow().startFlow();

plugin.getState()

String

This method returns the state of the plugin. This will either be ready if the plugin is instantiated, or started if the plugin is instantiated and a flow is started.

1
2
3
4
5
6
  var ob = Onboarded.load();

  ob.getState(); // => 'ready'

  ob.startFlow();
  ob.getState(); // => 'started'

Plugin (Advanced)

For more advanced usage, you may need to retrieve the registered user-project token from the Onboarded Plugin instance and provide it to the Onboarded Flow instance.

Flow Methods

flow.startCheckAndGetContentFor( String userProjectRegistrationToken )

jQuery.Promise

This method starts or resumes a flow from a Flow object, checking the API for the steps a user has already completed. It receives the user-project-registration token to check against the API. It returns a jQuery.Promise()object that follows the Deferred / Promise pattern. See jQuery: Deferred Object Documentation for more information.

This method triggers the onboarded:flow:onStart and onboarded:flow:afterStart events on the DOM. See Plugin Events for more information on handling events.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
  var ob, flow, token, promiseForContent;
  ob = Onboarded.load();

  flow  = ob.getFlow();
  token = ob.getUser();

  // Start the flow checking the API for the user, and receive a promise
  promiseForContent = flow.startCheckAndGetContentFor(token);

  // Handle the content, when the promise is resolved
  promiseForContent.done( function doneStarting(content) {
    // Do something with the content
    ob.updateRenderContainer(content);
  });

flow.startAndGetContent()

jQuery.Promise

This method starts or resumes a flow from a Flow object. Unlike flow.startCheckAndGetContentFor, it does NOT check the API for any existing steps completed. It returns a jQuery.Promise() object that follows the Deferred / Promise pattern. See jQuery: Deferred Object Documentation for more information.

This method triggers the onboarded:flow:onStart and onboarded:flow:afterStart events on the DOM. See Plugin Events for more information on handling events.

1
2
3
4
5
6
7
8
9
10
11
12
  var ob, flow, promiseForContent;
  ob   = Onboarded.load();
  flow = ob.getFlow();

  // Start the flow and receive a promise
  promiseForContent = flow.startAndGetContent();

  // Handle the content, when the promise is resolved
  promiseForContent.done( function doneRestarting(content) {
    // Do something with the content
    ob.updateRenderContainer(content);
  });

flow.reset()

jQuery.Onboarded.Flow

This method resets a flow. It internally resets the completed steps counter and sets the current step to the first step of the flow. It returns the flow instance for method chaining.

Additionally, it triggers the onboarded:flow:onReset and onboarded:flow:afterReset events on the DOM around the flow reset. See Plugin Events for more information on handling events.

1
2
3
4
5
6
  var ob   = Onboarded.retrieve();
  var flow = ob.getFlow();

  // Resets the current flow to the begining,
  // triggering callback events on the DOM.
  flow.reset();

flow.dismiss()

jQuery.Onboarded.Flow

This method dismisses the current flow. Internally, it calls the plugin.dismissFlow() method. It returns the flow instance for method chaining.

Additionally, this method triggers the onboarded:flow:onDismissal and onboarded:flow:afterDismissal events on the DOM around the actual dismissal. See Plugin Events for more information on handling events.

Note that dismissing a flow, is only temporary. Calling plugin.startFlow() again will resume the flow where left off when dismissed.

1
2
3
4
5
6
  var ob   = Onboarded.retrieve();
  var flow = ob.getFlow();

  // Dismisses the current flow, triggering
  // callback events on the DOM.
  flow.dismiss();

flow.getContent()

String

This method gets the content for the current step or completion view. It returns a string.

1
2
3
4
  var ob   = Onboarded.load();
  var flow = ob.getFlow();

  flow.getContent(); // => 'Some content'

flow.getStep()

jQuery.Onboarded.Step

This method gets the current step of the flow object. It returns a Step object.

1
2
3
4
5
  var ob   = Onboarded.load();
  var flow = ob.getFlow();

  // Get the Step object for the current step.
  flow.getStep();

flow.setCurrentStep( [ label ] )

String

This method sets the current step pointer for a flow. It receives an optional label for the step. If the label is omitted, then it defaults to the first incomplete step on the flow.

Note that this method does not actually trigger a rendering of the step specified, it only updates the internal current step pointer.

1
2
3
4
5
6
7
8
  var ob   = Onboarded.load();
  var flow = ob.startFlow();

  // Set the flow's step pointer to another step.
  flow.setCurrentStep('a-very-specific-step');

  // Set the flows step pointer back to the first uncompleted step.
  flow.setCurrentStep();

flow.setComplete()

jQuery.Onboarded.Flow

This method sets internal pointers on the flow to mark it as a completed flow. It also triggers the onboarded:flow:onComplete and onboarded:flow:afterComplete events on the DOM. See Plugin Events for more information on handling events.

Note that this method does NOT send any data back to the API, regarding the completion of a step. Resetting the flow, will reset this completion state.

Like the flow.setCurrentStep() method, this will not actually affect any rendering.

1
2
3
4
5
  var ob   = Onboarded.load();
  var flow = ob.startFlow();

  // Sets flow as completed.
  flow.setComplete();

Step Methods

step.start()

String

This method starts a given step and returns the content. Internally this method uses the plugin instance to send the initial step data back to the API.

This method triggers the onboarded:step:onStart and onboarded:step:afterStart events on the DOM. Specifically, the onboarded:step:onStart event is triggered prior to the API POST and provides access to the step data so that it can be manipulated. See Plugin Events for more information on handling events.

1
2
3
  var ob   = Onboarded.load();
  var flow = ob.getFlow();
  var step = flow.getStep();

step.getData( [ key ] )

Object Literal

This method returns the raw object literal with the step data. It optionally receives a key parameter to return a specific node of the object literal.

1
2
3
4
5
6
  var ob   = Onboarded.load();
  var flow = ob.getFlow();
  var step = flow.getStep();

  // Get the step data object literal
  step.getData();

step.getContent()

jQuery Object

This method retrieves a deep clone of the step content, replicating the entire DOM hierarchy as defined in the DOM. That way the step content is wrapped in the flow container and the project container, so to preserve the selector hierarchy.

Since the returned content is a deep clone, all the DOM events and DOM data are duplicated. Altering the content will NOT affect the original source definition.

1
2
3
4
5
6
7
  var ob   = Onboarded.load();
  var flow = ob.getFlow();
  var step = flow.getStep();

  // Returns a jQuery object -- call any jQuery method
  // or append it to the DOM, etc...
  var $myProjectFlowStep = step.getContent();

Working With Data

Send Step Data Anywhere

To save data asynchronously to any server, bind event handlers to any of the onboarded:step:onStart, onboarded:step:afterStart, onboarded:step:onComplete, or onboarded:step:afterComplete events. Each of those callbacks receives, in addition to the event, the instance of the step object, and the data for that step.

For example, to send data after the completion of every step using the jQuery.post() method we could do the following:

1
2
3
4
5
6
7
8
9
10
jQuery(document)
  .on('onboarded:step:afterComplete', function (event, step, data) {

    // Standard jQuery.post() that returns a jQuery.Promise object:
    $.post( 'http://myapp.dev/my-data', data )
      .done( function (response) { // Handle the response } )
      .fail( function () { // Handle the failure } )
      .always( function () { // Do this, regardless of response } );

  });

To send data for only one step, conditionally check the step.label inside the callback handler:

1
2
3
4
5
6
7
8
9
10
11
12
13
jQuery(document)
  .on('onboarded:step:afterComplete', function (event, step, data) {

    // Check what step we just completed
    if (step.label === 'special_step') {

      /* 
       * Do something special with the data... for example, 
       * POST it asynchronously back to your own server.
       */

    }
  });

Altering The Data

You can also programmatically manipulate the data inside callbacks, but note that the data will get sent to the API between the on* and after* callbacks.

For example, to add an additional named data point to the step data before sending:

1
2
3
4
5
6
7
8
jQuery(document)
  .on('onboarded:step:onComplete', function (event, step, data) {

    // Add some data...
    data.woohoo = "I don't know what chunky bacon is, but we did it!";
    data.additionally = "We're in the docs!";

  });

Plugin DOM Events

Handling Events

The Plugin triggers the following events on the DOM. Bind event handlers to them in order to inject custom behavior into your flows.

For example, using jQuery you might do somthing like this:

1
2
3
$(document).on( 'onboarded:afterLoad', function (event, plugin) {
  // Do something after the plugin is loaded...
});

List of Events

Here is a complete list of the events triggered on the DOM, along with their callback signatures, and a description of when they are triggered.

Event
onboarded:afterLoad
Handler
function (Event eventObject, String plugin)
Description
This event is triggered when the plugin is first initialized. Its handler receives the Event object and the instance of the plugin.
Event
onboarded:onRender
Handler
function (Event eventObject, String content, jQueryObject renderContainer)
Description
This event is triggered before a flow step is rendered. Its handler receives the Event object, the content to be rendered, and the renderContainer.
Event
onboarded:afterRender
Handler
function (Event eventObject, String content, jQueryObject renderContainer)
Description
This event is triggered after a flow step is rendered. Its handler receives the Event object, the content to be rendered, and the renderContainer.
Event
onboarded:flow:onStart
Handler
function (Event eventObject, Flow flowObject)
Description
This event is triggered before the start of a flow. Its handler receives the Event object, and the Flow object. It is also triggered by restarting a flow, in which case it is triggered AFTER the flow is reset. (see the onReset and afterReset events below)
Event
onboarded:flow:afterStart
Handler
function (Event eventObject, Flow flowObject)
Description
This event is triggered after the start of a flow. Its handler receives the Event object, and the Flow object. It is also triggered after a flow is restarted.
Event
onboarded:flow:onComplete
Handler
function (Event eventObject, Flow flowObject)
Description
This event is triggered before a flow is marked as completed. Its handler receives the Event object, and the Flow object.
Event
onboarded:flow:afterComplete
Handler
function (Event eventObject, Flow flowObject)
Description
This event is triggered after a flow is marked as completed. Its handler receives the Event object, and the Flow object.
Event
onboarded:flow:onReset
Handler
function (Event eventObject, Flow flowObject)
Description
This event is triggered before a flow is reset. Its handler receives the Event object and the Flow object. Note that the restart() method on a flow, will call reset() and trigger this event.
Event
onboarded:flow:afterReset
Handler
function (Event eventObject, Flow flowObject)
Description
This event is triggered after a flow is reset. Its handler receives the Event object and the Flow object. Note that the restart() method on a flow, will call reset() and trigger this event.
Event
onboarded:flow:onDismissal
Handler
function (Event eventObject, Flow flowObject, Step stepObject)
Description
This event is triggered before a flow is dismissed from a flow object. Its handler receives the Event object, the Flow object, and the current Step object. Note that dismissing a flow via the plugin instance (with the dismissFlow() method) will NOT trigger this callback event.
Event
onboarded:flow:afterDismissal
Handler
function (Event eventObject, Flow flowObject, Step stepObject)
Description
This event is triggered after a flow is dismissed from a flow object. Its handler receives the Event object, the Flow object, and the current Step object. Note that dismissing a flow via the plugin instance (with the dismissFlow() method) will NOT trigger this callback event.
Event
onboarded:step:onStart
Handler
function (Event eventObject, Step stepObject, JSON data)
Description
This event is triggered before a step is started. Its handler receives the Event object, the Step object, and the JSON data object. This event is triggered before any data is sent to the API.
Event
onboarded:step:afterStart
Handler
function (Event eventObject, Step stepObject)
Description
This event is triggered after a step is started. Its handler receives the Event object, and the Step object.
Event
onboarded:step:onComplete
Handler
function (Event eventObject, Step stepObject, jQueryObj action, JSON data)
Description
This event is triggered before a step is completed. Its handler receives the Event object, the Step object, and the JSON data object. This event is triggered before any data is sent to the API.
Event
onboarded:step:afterComplete
Handler
function (Event eventObject, Step stepObject, jQueryObj action, JSON data)
Description
This event is triggered after a step is completed. Its handler receives the Event object, and the Step object.
Try scrolling menu for more