An angular directive that provides the "joyride" functionality for introducing your websites.Similar to Jquery Joyride but a lot better.
See the demo page for a demo and the overview of the features.
You can install this package through Bower by using the following command :
bower install ng-joyride --saveAdd dependencies to your project.
<link href="/bower_components/bootstrap/dist/css/bootstrap.css" rel="stylesheet">
<link href="/bower_components/ng-joyride/ng-joyride.css" rel="stylesheet">
<script src="/bower_components/jquery/jquery.js"></script>
<script src="/bower_components/angular/angular.js"></script>
<script src="/bower_components/bootstrap/dist/js/bootstrap.js"></script>
<script src="/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>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
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.
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:
joyride:prev: Go to the previous tour stepjoyride:next: Go to the next tour stepjoyride:exit: Skip & exit the tour
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")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.
- title - The `title joyride-element' opens a generic styled box shows showing information.You can have custom HTML passed to it as you see above
- element - Boostrap popvers over
elementsthat you pass through the selector.Any jqyery selector will work. - function - A function call . The function call will be done.Through this you can render more DOM or open a modal etc
- location_change - This will change the location using
$location.pathincase the joyride needs to be across different pages of your website.
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.
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
$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.
heading: Custom heading that you want the title box to have.text: Text or HTML can be passedtitleTemplate( Optional ) : You can pass a templateURL that can be used in case you don't want the default template.This will be a url that can be loaded either from the $templateCache or through AJAX if its not present in the cache.curtainClass( Optional ) : You can use this to pass your custom class to the joyride background.This is useful where you want the background to change in each step.
- Heading Placeholder :
{{heading}}will be replaced by the heading you pass. - Content Placeholder :
<div ng-bind-html="content"></div>should be present in your template so that it can be populated by the template. - Skip Joyride Placeholder :
<a class="skipBtn"></a>should be present as the class selectorskipBtnis used to detect whether the user skipped the joyride. - Previous Button Placeholder :
<a class="prevBtn"></a>should be present as the class selectorprevBtnis used to detect whether the user pressed on previous step. - Next Button Placeholder :
<a class="nextBtn"></a>should be present as the class selectornextBtnis used to detect whether the user pressed on next step.
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> 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> Previous</button> <button id=\"nextTitleBtn\" class=\"nextBtn btn btn-primary\" type=\"button\">Next <i class=\"glyphicon glyphicon-chevron-right\"></i></button></div></div></div></div></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,
curtainClass : 'myCustomClass' //this is optional.
}
];The element joyride-element generates a box that looks like below.
type: Should be a stringelementselector: Any jquery selector can be passed here.heading: This is the heading.Can have html also.text: Text or HTML can be passedplacement( Optional ) : Where the popover will be placed.Similar to bootstrap popover placements. The possible values are "top|bottom|right|left".scroll: Whether you want, the page to be scrolled to the particular element.advanceOn(Optional): An action on the page which will move the Joyride to the next step. It must consist ofelementandevent. Example:{element: '#foo', event: 'click'}curtainClass( Optional ) : You can use this to pass your custom class to the joyride background.This is useful where you want the background to change in each step.attachToBody( Optional ) : You can use this to attach the popover to the body instead of the element.In some cases you might run into problems with css stacking context.Normally you wouldn't need to use thisshouldNotStopEvent( Optional ) : This should be set to true if you want event generated on the selected element to propagate. This should be rarely needed as you normally would not want user to click on a button and trigger actions out of joyride.If you are looking to move the joyride forward when user does an action other than click 'next', use advanceOn.elementTemplate( Optional ) : This is a function which receives two arguments (content,isEnd) . content -> The content to display, isEnd -> Is true if its the last step. Return value of the function is used a template.This function controls the look and feel of the popover, that part which is inside the popover-content.
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.
- Previous Button : a button of id "prevBtn" should be present for previous the user to go back.
- Next Button : a button of id "nextBtn" should be present for previous the user to go back.
- Skip Button : a button of id "skipBtn" should be present for previous the user to go back.
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.
- Heading Placeholder :
{{heading}}will be replaced by the heading you pass. - popover-title :
<h3 class="popover-title"></h3>.An element with class popover-title should be present for bootstrap to identify the popover template. - popover-content :
<div class="popover-content"></div>.An element with class popover-content should be present for bootstrap to identify the popover content template.
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
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.
type: Should be a stringlocation_changepath: The path to navigate to should be passed here.The path needs to be a part of the same app.
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 .
type: Should be a stringfunctionfn: pass the actual function reference.Or you can pass a function name as string. If you pass a string then it will be resolved on the scope .
MIT
Free Software, Hell Yeah!
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent