view/theme/frio/frameworks/jquery-scrollspy/README.md

   1 # NOTE: This is the latest version of ScrollSpy, which includes a ton of bug fixes and efficiency improvements. It's recommended that you use this version for now instead of the official (which hasn't been updated in a while).
   2
   3 # jQuery-ScrollSpy
   4
   5 An adaptation of the Mootools Scrollspy (http://davidwalsh.name/mootools-scrollspy) plugin for jQuery
   6
   7 (c) 2011 Samuel Alexander (https://github.com/sxalexander/jquery-scrollspy)
   8
   9 (c) 2015 SoftwareSpot
  10
  11 Released under The MIT License.
  12
  13 ## Description:
  14
  15 ScrollSpy is a simple jQuery plugin for firing events based on where the user has scrolled to in a page.
  16
  17 ## Homepage:
  18
  19 https://github.com/softwarespot/jquery-scrollspy
  20
  21 ## Source:
  22
  23 Hosted at GitHub; browse at:
  24
  25   https://github.com/softwarespot/jquery-scrollspy/tree/master
  26
  27 Or clone from:
  28
  29     git://github.com/softwarespot/jquery-scrollspy.git
  30
  31 ## Usage:
  32
  33 1. Insert the necessary elements in to your document's `<head>` section, e.g.:
  34
  35 ```html
  36     <script src="jquery.min.js"></script>
  37     <script src="jquery.scrollspy.min.js"></script>
  38 ```
  39
  40 2. Initialise ScrollSpy once the DOM has been loaded:
  41
  42 ```javascript
  43 <script>
  44     $(function() {
  45
  46             var $nav = $('#nav');
  47
  48             $('#sticky-navigation').scrollspy({
  49                 min: $nav.offset().top,
  50                 onEnter: function(element, position) {
  51                     $nav.addClass('fixed');
  52                 },
  53                 onLeave: function(element, position) {
  54                     $nav.removeClass('fixed');
  55                 }
  56             });
  57
  58         });
  59 </script>
  60 ```
  61
  62 Check out the /examples for more info !
  63
  64 ## Documentation:
  65
  66 ScrollSpy function signature:
  67 ```javascript
  68     $('container').scrollspy(options, action)
  69 ```
  70
  71 Default options for ScrollSpy:
  72 ```javascript
  73 // default options for ScrollSpy
  74 var defaults = {
  75     // the offset to be applied to the left and top positions of the container
  76     buffer: 0,
  77
  78     // the element to apply the 'scrolling' event to (default window)
  79     container: window,
  80
  81     // the maximum value of the X or Y coordinate, depending on mode the selected
  82     max: 0,
  83
  84     // the maximum value of the X or Y coordinate, depending on mode the selected
  85     min: 0,
  86
  87     // whether to listen to the X (horizontal) or Y (vertical) scrolling
  88     mode: 'vertical',
  89
  90     // namespace to append to the 'scroll' event
  91     namespace: 'scrollspy',
  92
  93     // call the following callback function every time the user enters the min / max zone
  94     onEnter: null,
  95
  96     // call the following callback function every time the user leaves the min / max zone
  97     onLeave: null,
  98
  99     // call the following callback function every time the user leaves the top zone
 100     onLeaveTop: null,
 101
 102     // call the following callback function every time the user leaves the bottom zone
 103     onLeaveBottom: null,
 104
 105     // call the following callback function on each scroll event within the min and max parameters
 106     onTick: null,
 107
 108     // call the following callback function on each scroll event when the element is inside the viewable view port
 109     onView: null
 110 };
 111 ```
 112
 113 Events are triggered by ScrollSpy are:
 114
 115     scrollTick: Fires on each scroll event within the min and max parameters:
 116         position: an object with the current X and Y position.
 117         inside: a Boolean value for whether or not the user is within the min and max parameters
 118         enters: the number of times the min / max has been entered.
 119         leaves: the number of times the min / max has been left.
 120
 121     scrollEnter: Fires every time the user enters the min / max zone:
 122             position: an object with the current X and Y position.
 123             enters: the number of times the min / max has been entered.
 124
 125     scrollLeave: Fires every time the user leaves the min / max zone:
 126             position: an object with the current X and Y position.
 127             leaves: the number of times the min / max has been left.
 128
 129     scrollLeaveTop: Fires every time the user leaves the top zone:
 130             position: an object with the current X and Y position.
 131             leaves: the number of times the min / max has been left.
 132
 133     scrollLeaveBottom: Fires every time the user leaves the bottom zone:
 134             position: an object with the current X and Y position.
 135             leaves: the number of times the min / max has been left.
 136
 137     scrollView: Fires every time the element is inside the viewable view port:
 138             position: an object with the current X and Y position.
 139             leaves: the number of times the min / max has been left.
 140
 141 ### Tidy up
 142
 143 To destroy ScrollSpy for a particular container, simple pass 'destroy' as the action parameter. The only options that will be honoured are `container` and `namespace`.
 144
 145 ## A note about forking:
 146
 147 By forking this project you hereby grant permission for any commits to your fork to be
 148 merged back into this repository and, with attribution, be released under the terms of
 149 the MIT License.
 150
 151 ## Contribute
 152
 153 To contribute to the project, you will first need to install [node](https://nodejs.org) globally on your system. Once installation has completed, change the working directory to the plugin's location and run the following command:
 154
 155 ```shell
 156     npm install
 157 ```
 158
 159 After installation of the local modules, you're ready to start contributing to the project. Before you submit your PR, please don't forget to call `gulp`, which will run against [JSHint](http://jshint.com) for any errors, but will also minify the plugin.
 160
 161 ##### Watch
 162 Call the following command to start 'watching' for any changes to the main JavaScript file(s). This will automatically invoke JSHint and Uglify.
 163 ```shell
 164     gulp watch
 165 ```
 166
 167 ##### JSHint
 168 Call the following command to invoke JSHint and check that the changes meet the requirements set in .jshintrc.
 169 ```shell
 170     gulp jshint
 171 ```
 172
 173 ##### Uglify
 174 Call the following command to invoke Uglify, which will minify the main JavaScript file(s) and output to a .min.js file respectively.
 175 ```shell
 176     gulp uglify
 177 ```
 178
 179 ##### Build
 180 Call the following command to invoke both JSHint and Uglify.
 181 ```shell
 182     gulp
 183 ```