angular-joyride

A simple joyride directive for angular. This is inspired by ng-joyride and works very similarly but with less dependencies. The only dependency is ngAnimate, no jquery or any other libraries required.

Demo

Installing

Install with npm:

npm install angular-joyride

Install with bower:

bower install angular-joyride

Inject angular-joyride and ngAnimate into your angular module:

angular.module('MyApp', ['ngAnimate', 'angular-joyride']);

Add the joyride directive as an element:

<joyride></joyride>

Usage

This directive relies on a service for handling the joyride content and configuration, so include the joyrideService in your controller:

app.controller('MainCtrl', function($scope, joyrideService) {
  var joyride = joyrideService;

  joyride.start = true;
  
  joyride.config = {
    overlay: false,
    onStepChange: function(){ // Code Here },
    onStart: function(){ // Code Here },
    onFinish: function(){ // Code Here },
    steps : [
      {
        title: "Title 2",
        content: '<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptatibus, quidem, quia mollitia harum tempora laudantium deserunt deleniti. Expedita, soluta, atque maxime minus commodi quaerat ipsum reiciendis veritatis eum laboriosam incidunt.</p><p>another example</p>'
      },
      {
        type: 'element',
        selector: "#title",
        title: "Title 1",
        content: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptatibus, quidem, quia mollitia harum tempora laudantium deserunt deleniti. Expedita, soluta, atque maxime minus commodi quaerat ipsum reiciendis veritatis eum laboriosam incidunt.',
        placement: 'top'
      }
    ]
  },

});

Starting the joyride

The start property can be used to trigger the joyride, setting it to true starts the joyride and false will end it.

Configuration

steps - The steps to be used in the joyride, expects an array of objects.
overlay - Display overlay, default is true.
template - This can be used to add a custom template for the joyride, a path to an html file should be given.
onStepChange - Callback for step change.
onStart - Callback for joyride start.
onFinish - Callback for joyride end.

Joyride Steps

The steps property accepts an array containing the steps of the joyride, each step should be an object with the following properties:

Property	Type	Description
type	String	Type of step, default is "Regular"
title	String	Title of step
content	String	Step content, can incude html tags
selector	String	If type is set to "element" this is the selector used to find the element
placement	String	If type is set to "element" determines the placement of the container, default is "bottom"
appendToBody	boolean	If type is set to "element" setting to true appends the joyride to the body instead of the element the joyride is pointing to, default is false
scroll	boolean	If type is set to "element" can disable/enable scrolling to element, default is true
beforeStep	function	Function called before step transitions in, can pause joyride until some code executes

Step Types

There are 2 available types:

Regular: The default type, appears as a regular pop-up.
Element: Highlights a certain element in the DOM. Requires the selector property to work and can be positioned with the placement property with top, right, bottom or left.

Before step callback

These should be used if you want to pause between steps to execute some code first, for example opening a modal or going to a different page before going to the next step. Both these functions need to take a resume function as the first paramater (you can rename it if you want) to be called when you want the joyride to resume.

In the example below the modal should be open in the second step but it should be closed in the first and third step:

joyride.config.steps = [
    {
      title : 'Step 1',
      content: "<p>This step is on the main page with the modal closed.</p>",
      beforeStep: closeModal
    },
    {
      type: 'element',
      selector: '.modal .button',
      title: "Step 2",
      content: "This step should wait for the modal to open first!",
      beforeStep: openModal,
      scroll: false
    },
    {
      title : 'Step 3',
      content: "<p>Last step is on the main page with the modal closed.</p>",
      beforeStep: closeModal
    }
  ];
  
  // Make sure to call resume to let the joyride know it should continue
  function openModal(resume){
    modal.open.then(function(){
        resume();
    });
  }
  
  function closeModal(resume){
    modal.close.then(function(){
        resume();
    });
  }

Methods

Method	Description
next	Goes to the next step
prev	Goes to the previous step
goTo	Goes to a specific step, requires a number representing the index of the step
Usage:

$scope.customNext = function(){
    joyride.next();
}

$scope.go = function(index){
    joyride.goTo(index)
}

Animations

This directive relies on ngAnimate and the $animate service for handling animation classes. By default the joyride has simple fade in/out animations, but you can customize them by using the .jr_start class for start/end animations and the .jr_transition for step transition animations:

.jr_container{
    transition: opacity 0.3s, transform 0.3s
}

//////// START/END ANIMATIONS
.jr_container.jr_start-add {
  opacity: 0;
}
.jr_container.jr_start-add-active {
  opacity: 1;
}

.jr_container.jr_start-remove {
  opacity: 1;
}
.jr_container.jr_start-remove-active {
  opacity: 0;
}
//////////// STEP TRANSITION ANIMATIONS
.jr_container.jr_transition{
  opacity: 0;
}
.jr_container.jr_transition-add {
  opacity: 1;
  transform: translateY(0px);
}
.jr_container.jr_transition-add-active {
    opacity: 0;
    transform: translateY(-100px);
}

.jr_container.jr_transition-remove {
    opacity: 0;
    transform: translateY(-100px);
}

.jr_container.jr_transition-remove-active {
  opacity: 1;
    transform: translateY(0px);
}

Custom Templates

If you want to use your own template for the joyride then add the template in an html file then enter the path to that file in your controller similar to the following:

joyride.config.template = 'partials/myCustomTemplate.html'

Your template must contain a div with the class jr_container, i would recommend copying the html of the default template and editing it, you can find the html below:

<div class="jr_container" id="jr_step_{{joyride.current}}">
  <div class="jr_step">
    <h4 ng-if="joyride.config.steps[joyride.current].title" class="jr_title">{{joyride.config.steps[joyride.current].title}}</h4>
    <div ng-if="joyride.config.steps[joyride.current].content" class="jr_content" ng-bind-html="joyride.config.steps[joyride.current].content | jr_trust"></div>
  </div>
  <div class="jr_buttons">
    <div class="jr_left_buttons">
      <a class="jr_button jr_skip" ng-click="joyride.start = false">Skip</a>
    </div>

    <div class="jr_right_buttons">
      <a class="jr_button jr_prev" ng-click="joyride.prev()" ng-class="{'disabled' : joyride.current === 0}">Prev</a>
      <a class="jr_button jr_next" ng-click="joyride.next()" ng-bind="(joyride.current == joyride.config.steps.length-1) ? 'Finish' : 'Next'"></a>
    </div>
  </div>
</div>

mt0803/angular-joyride