Angular Joyride Directive for creating custom introductions to websites
npm install ng-joyrideng-joyride
=========
An angular directive that provides the "joyride" functionality for introducing your websites.Similar to Jquery Joyride but a lot better.
###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 :
``sh`
bower install ng-joyride --save
Add it to your module.
`sh`
angular.module('myModule', [
'ngJoyRide'
])ng-joy-ride
There is one directive called which can be used as an attribute.
`sh`
-----
####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
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:prev: Go to the previous tour stepjoyride:next
- : Go to the next tour stepjoyride:exit
- : Skip & exit the tour
#### 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:
`html`
You can call the events on it with the following way:
`javascript`
$("#serverTour").trigger("joyride:next")
--------
will have the list of joyride-element that you can pass through the config.
Example`sh
$scope.config = [
{
type: "title",
heading: "Welcome to the NG-Joyride demo",
text: 'Welcome to Ng Joyride Demo
( This demo will walk you through the features of Ng-Joyride. )
This can have custom html too !!!' },{
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 aboveelements that you pass through the selector.Any jqyery selector will work.$location.path incase the joyride needs to be across different pages of your website. ####Elaborate details of each of the Joyride Elements are at the end
--------
#### 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.
------
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
----------
### Type : Title
``sh`
$scope.config = [
{
type: "title",
heading: "Welcome to the NG-Joyride demo",
text: ''Welcome to Ng Joyride Demo
( This demo will walk you through the features of Ng-Joyride. )
This can have custom html too !!!
curtainClass : 'myCustomClass' //this is optional.
}
];
The title element generates a box that looks like below.
!ng-joyride
####Properties
* 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.titleTemplate
##### Custom . The custom title template should have the following placeholder.
Heading Placeholder* : {{heading}} will be replaced by the heading you pass.
Content Placeholder* :
should be present in your template so that it can be populated by the template.
Skip Joyride Placeholder* : should be present as the class selector skipBtn is ysed to detect whether the user skipped the joyride.
Previous Button Placeholder* : should be present as the class selector prevBtn is used to detect whether the user pressed on previous step.
Next Button Placeholder* : should be present as the class selector nextBtn is used to detect whether the user pressed on next step. The default template for 'title' is .
`sh
"{{heading}}
"
`
---------### Type : Element
`sh
$scope.config = [
{
type: "element",
selector: "#home",
heading: "Title can have HTML",
text: "You are in the home page.",
placement: "bottom",
scroll: true,
curtainClass : 'myCustomClass' //this is optional.
}
];
`The
element joyride-element generates a box that looks like below.!ng-joyride
####Properties
*
type : Should be a string element
* selector : Any jquery selector can be passed here.
* heading : This is the heading.Can have html also.
* text : Text or HTML can be passed
* placement ( 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 of element and event. 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 this
* 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.
* shouldNotStopEvent ( Optional ) : This should be set to true if you don't want event generated on the selected element should be allowed to propagate. This should be rarely needed as you normally would not want user to click on a button a trigger actions out of joyride.If you are looking to move the joyride forward when user does an action other than next, use advanceOn
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:`sh
function _generateTextForNext(isEnd){
if (isEnd) {
return 'Finish';
} else {
return 'Next';
}
} function elementTourTemplate(content, isEnd){
return '
' + content + '
';
}
$scope.config = [
{
type: "element",
selector: "#home",
heading: "Title can have HTML",
text: "You are in the home page.",
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.
##### 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`sh
` 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* : .An element with class popover-title should be present for bootstrap to identify the popover template.
popover-content* : .An element with class popover-content should be present for bootstrap to identify the popover content template.
The default template for 'element' is .
`sh
" "
`
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.
`sh
$scope.config = [
{
type: "location_change",
path: "/demo"
}
];
`Immediately after changing the location, the next
joyride-element is called.
####Properties*
type : Should be a string location_change
* path : The path to navigate to should be passed here.The path needs to be a part of the same app.
---------
### Type : function
This is required where your need to run some function for your dom element to get generated.
`sh
$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
*
type : Should be a string function
* fn` : 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 .
License
----
MIT
Free Software, Hell Yeah!