search

abhikmitra / ng-joyride

Angular Joyride Directive for creating custom introductions to websites
126 stars 68 forks source link

readme

ng-joyride

An angular directive that provides the "joyride" functionality for introducing your websites.Similar to Jquery Joyride but a lot better.

ng-joyride

Demo

See the demo page for a demo and the overview of the features.

Installation

Bower

You can install this package through Bower by using the following command :

bower install ng-joyride --save

Add dependencies to your project.

<link href="https://github.com/abhikmitra/ng-joyride/blob/master/bower_components/bootstrap/dist/css/bootstrap.css" rel="stylesheet">
<link href="https://github.com/abhikmitra/ng-joyride/blob/master/bower_components/ng-joyride/ng-joyride.css" rel="stylesheet">

<script src="https://github.com/abhikmitra/ng-joyride/raw/master/bower_components/jquery/jquery.js"></script>
<script src="https://github.com/abhikmitra/ng-joyride/raw/master/bower_components/angular/angular.js"></script>
<script src="https://github.com/abhikmitra/ng-joyride/raw/master/bower_components/bootstrap/dist/js/bootstrap.js"></script>
<script src="https://github.com/abhikmitra/ng-joyride/raw/master/bower_components/ng-joyride/ng-joyride.js"></script>

Add it to your module.

angular.module('myModule', [
    'ngJoyRide'
])

There is one directive called ng-joy-ride which can be used as an attribute.

<div ng-joy-ride="startJoyRide" config="config" on-finish="onFinish()"  on-skip="onFinish()"></div>

Starting the Joyride

ng-joy-ride

You can invoke the joyride from anywhere by setting (in this case) startJoyRide to true.The scope variable that you bind to ng-joy-ride is the one that will control the start of the joyride. Once the joyride is complete , the scope variable gets set to false.So on completeion of the joyride startJoyRide will be set to false

Stopping the Joyride

The joyride stops when, the user presses "skip", "finish" or when you programamtically set startJoyRide to false.Setting startJoyRide to false when the joyride is on , will have the same effect as skip.

Joyride Events

You can bind to certain events in order to control the behaviour of the tour, this can be useful when you want a more specific level of interaction, where the tour continues by a user action instead of hitting Next. The following events are currently available:

Example

You'll have to use something like jQuery to trigger the events on the element, for example, if you've defined the following tour:

<div id="serverTour" ng-joy-ride="startServerTour" config="serverTourConfig"></div>

You can call the events on it with the following way:

$("#serverTour").trigger("joyride:next")

Configuring the joyride

config

This is the attribute for setting the required steps.In the above example scope.config will have the list of joyride-element that you can pass through the config.
Example

$scope.config = [
        {
                type: "title",
                heading: "Welcome to the NG-Joyride demo",
                text: '<div class="row"><div id="title-text" class="col-md-12"><span class="main-text">Welcome to <strong>Ng Joyride Demo</strong></span><br><span>( This demo will walk you through the features of Ng-Joyride. )</span><br/><br/><span class="small"><em>This can have custom html too !!!</em></span></div></div>'

            },{
                type: "element",
                selector: "#finish",
                heading: "Custom Title",
                text: "The demo finishes.Head over to github to learn more",
                placement: "top",
                scroll: true
            }

        ];

Each element of the array should be a proper joyride element.There are 4 types of joyride-element.

Elaborate details of each of the Joyride Elements are at the end

Hooks in the joyride

on-finish,on-skip

You can pass functions using the on-finish and on-skip attributes.The function passed to on-finish will be called on finish of the joyride and the on-skip function will be called if the user skips from the joyride.

Demo and example usage.

You see this repo sample repo for the usage. You can download it and run it through a web browser.You can check main.js to see how I have passed the config using $scope.config

Joyride-Element Descriptions

      Type : Title

$scope.config = [
        {
                type: "title",
                heading: "Welcome to the NG-Joyride demo",
                finishBtnText: 'Finish',
                prevBtnText: 'Previous',
                skipBtnText: 'Skip',
                nextBtnText: 'Next',
                text: '<div class="row"><div id="title-text" class="col-md-12"><span class="main-text">Welcome to <strong>Ng Joyride Demo</strong></span><br><span>( This demo will walk you through the features of Ng-Joyride. )</span><br/><br/><span class="small"><em>This can have custom html too !!!</em></span></div></div>'
                 curtainClass : 'myCustomClass' //this is optional.
            }
        ];

The title element generates a box that looks like below.

ng-joyride

Properties

   Custom titleTemplate. The custom title template should have the following placeholder.

The default template for 'title' is .

"<div id=\"ng-joyride-title-tplv1\"><div class=\"ng-joyride sharp-borders intro-banner\" style=\"\"><div class=\"popover-inner\"><h3 class=\"popover-title sharp-borders\">{{heading}}</h3><div class=\"popover-content container-fluid\"><div ng-bind-html=\"content\"></div><hr><div class=\"row\"><div class=\"col-md-4 skip-class\"><a class=\"skipBtn pull-left\" type=\"button\"><i class=\"glyphicon glyphicon-ban-circle\"></i>&nbsp; Skip</a></div><div class=\"col-md-8\"><div class=\"pull-right\"><button disabled=\"disabled\" class=\"prevBtn btn\" type=\"button\"><i class=\"glyphicon glyphicon-chevron-left\"></i>&nbsp;Previous</button> <button id=\"nextTitleBtn\" class=\"nextBtn btn btn-primary\" type=\"button\">Next&nbsp;<i class=\"glyphicon glyphicon-chevron-right\"></i></button></div></div></div></div></div></div></div>"

      Type : Element

$scope.config = [
        {
                type: "element",
                selector: "#home",
                heading: "Title can have <em>HTML</em>",
                text: "You are in the <em>home page.</em>",
                placement: "bottom",
                scroll: true,
                curtainClass : 'myCustomClass' //this is optional.
            }
        ];

The element joyride-element generates a box that looks like below.

ng-joyride

Properties

Can also be used as a delegate which accepts content to be displayed and if it is reached the end of the tour. This will enable you to customize the look and feel of element type just as you can with title type. An example of this is shown below:

function _generateTextForNext(isEnd){
      if (isEnd) {
        return 'Finish';
      } else {
        return 'Next';
      }
    }

    function elementTourTemplate(content, isEnd){
      return '<div class=\"row\"><div id=\"pop-over-text\" class=\"col-md-12\">' + content + '</div></div><hr><div class=\"row\"><div class=\"col-md-4 center\"><a class=\"skipBtn pull-left\" type=\"button\">Skip</a></div><div class=\"col-md-8\"><div class=\"pull-right\"><button id=\"prevBtn\" class=\"prevBtn btn btn-xs\" type=\"button\">Previous</button> <button id=\"nextBtn\" class=\"nextBtn btn btn-xs btn-primary\" type=\"button\">' + _generateTextForNext(isEnd) + '</button></div></div></div>';
    }

$scope.config = [
        {
                type: "element",
                selector: "#home",
                heading: "Title can have <em>HTML</em>",
                text: "You are in the <em>home page.</em>",
                placement: "bottom",
                scroll: true,
                elementTemplate: elementTourTemplate
            }
        ];

The string returned by "elementTemplate" should have the following placeholders.

   Each joyride-element can have its own elementTemplate function .The below parameter controls

the look and feel of the popover as a whole while the above part controls the look and feel of the "popover-content" section

<div ng-joy-ride="startJoyRide" config="config" template-uri="template.html"></div>

The custom template-uri (This is different from the elementTemplate config )can be passed as an attribute value to template-uri as shown above.template.html will be loaded asynchronously in the above case.

The custom element template (supplied through template-uri) should have the following placeholders.

The default template for 'element' is .

"<div class=\"popover ng-joyride sharp-borders\"> <div class=\"arrow\"></div>   <h3 class=\"popover-title sharp-borders\"></h3> <div class=\"popover-content container-fluid\"></div></div>"

The template supplied by template-uri will be same for all the popovers which will be structurally similar.Fine grained control and distinction can be achieved by the "elementTemplate" which can be different for each step

      Type : location_change

This is required where your intro content spans over multiple pages and you want joyride to be across multiple pages.

$scope.config = [
        {
                type: "location_change",
                path: "/demo"
            }
        ];

Immediately after changing the location, the next joyride-element is called.

Properties

      Type : function

This is required where your need to run some function for your dom element to get generated.

$scope.config = [
        {
                type: "function",
                fn: openModalForDemo //(can also be a string, which will be evaluated on the scope)
            }
        ];

Immediately after calling the function, the next joyride-element is called.

The function that you will be passing should expect a boolean argument.

For eg : true being passed to the function, will signify creation of dom nodes.Like opening of modal. false being passed the function, will signify removal of these nodes, like closing the modal.

This is important, for the 'previous' button to work .

Properties

License

MIT

Free Software, Hell Yeah!