Advanced jQuery Scroll Progress Tracker

Ver. 1.2.2

A very versatile jQuery plugin that creates either a horizontal or a vertical (or both) scroll progress indicator based on your content. It is highly customizable and has a built-in linking function, so it can be used as an interactive table of contents.

Using the various options, it is also possible to, for example, display one tracker on large screens and another one on small screens. Additionally it is very easy to control the position, behavior and appearance of each tracker individually.

©2016 David Whitworth (david@whitworth.de)

Released under the GNU General Public License (GPL)


Options

horColor - default: 'red'New!
Using this option the color of the horizontal tracker's default gradient can easily be adjusted. There are four options (more might be added):

  • 'red'
  • 'blue'
  • 'green'
  • 'orange'

If you want to adjust the tracker(s) beyond picking a color with this option, you can do so in the stylesheet files.


verColor - default: 'red'New!
Using this option the color of the vertical tracker's default gradient can easily be adjusted. There are four options (more might be added):

  • 'red'
  • 'blue'
  • 'green'
  • 'orange'

If you want to adjust the tracker(s) beyond picking a color with this option, you can do so in the stylesheet files.


trackViewportOnly - default: falseNew!
If set to true, the tracker(s) will track only the currently visible portion of the tacked area. This way the progress bar will act similar to a scroll bar and the bullets/titles will only be active if at least a little bit of the corresponding sections is within the visible area.


horTracker - default: true
Displays a horizontal Scroll Progress Tracker if set to true.


horInHeader - default: false
If you activate this and have a header-tag on your website, the horizontal tracker will be created within your header¹. There are three options:

  • 'top' - Creates the tracker at the top of your header (i.e. before all other content).
  • 'bottom' - Creates the tracker at the bottom of your header (i.e. after all other content).
  • false - Creates the tracker at the end of the site in a fixed container (default behavior).

¹If you use this setting, you should make sure your header is set to position: fixed.


horPosition - default: 'top'
Defines where to display the horizontal tracker. There are two options:

  • 'top' - Displays the tracker above the content.
  • 'bottom' - Displays the tracker below the content.

horCenter - default: true
Setting this to false allows you to stretch the horizontal tracker to the width of the viewport.
This is the default behavior on small screens (and will thus be ignored if horMobileOnly is set to true)


horStyle - default: 'fill'
This option enables you to change the way the horizontal tracker looks. There are two options (more will be added):

  • 'beam' - The tracker will be displayed as a thin line with the bullets overlaying it.
  • 'fill' - The tracker will be displayed as a thick bar that contains titles within and has the bullets slightly overlapping it.

horMobile - default: true
The horizontal progress tracker won't show on small screens if set to false.


horMobileOnly - default: false
Hides the horizontal tracker on large screens if set to true
This is useful if you want to use the vertical tracker for large devices and the horizontal tracker for small screen
overrides horMobile: false


horStops - default: true
Adds bullets to the horizontal progress tracker for each section of your content if set to true.


horNumbering - default: true
If set to true the bullets of the horizontal tracker will be numbered. Naturally this only works while horStops is true.


horTitles - default: false
Adds the text of each section's headline (h2) to the horizontal progress tracker if set to true. The way these titles are displayed can be further adjusted with additional settings (see below).


horTitlesOffset - default: 'bottom'
Defines if and how the titles of the horizontal progress tracker should be offset from the tracker itself. There are three options:

  • 'top' - Displays the titles above the tracker.
  • 'bottom' - Displays the titles below the tracker.
  • false - Displays the titles on top of the tracker.¹

    ¹false will automatically be overridden with 'bottom' on small screens ('top' and 'bottom' still work normally on small screens)!

horOnlyActiveTitle - default: true
If set to true, only the headline of the current setion will be shown at all times, instead of each headline. This is necessary if the sections are too short, because if the tracker's stops are too closely together, the titles will overlap. This option is automatically forced on small screens.


verTracker - default: false
Displays a vertical Scroll Progress Tracker if set to true.


verPosition - default: 'left'
Defines where to display the vertical tracker. There are two options:

  • 'left' - Displays the tracker on the far left of the viewport.
  • 'right' - Displays the tracker on the far right of the viewport.

verStyle - default: 'beam'
This option enables you to change the way the vertical tracker looks. There are two options (more will be added):

  • 'beam' - The tracker will be displayed as a thin line with the bullets overlaying it.
  • 'fill' - The tracker will be displayed as a thick bar that contains the bullets within.

verMobile - default: false
The vertical progress tracker won't show on small screens if set to false.


verMobileOnly - default: false
The counterpart to horMobileOnly and only here for completeness. Usually it is not recommendable to actually set this to true.


verStops - default: true
Adds bullets to the vertical progress tracker for each section of your content if set to true.


verNumbering - default: false
If set to true the bullets of the vertical tracker will be numbered. Naturally this only works while verStops is true.


verTitles - default: true
Adds the text of each section's headline (h2) to the vertical progress tracker if set to true. They will be displayed to the right of the progress bar and the bullets (if verStops is true) per default. This can be changed via the stylesheet.


mobileThreshold - default: 1300
Treats the device as small screen if the viewport width is below or equal to this value, i.e. on default settings, if the viewport is at least 1301px wide, the device is treated as large screen, otherwise as small screen.
This setting affects horMobile, horMobileOnly, verMobile, verMobileOnly and others.


trackAllHeadlines - default: false
If set to true, any headline tag (h1, h2, h3,...) inside '.spt-trackThis'¹ will be used as a section title on the tracker(s) instead of h3 only. Be careful to use one headline only, if you use this option.

¹or with the class "spt-trackThis" - see the last point under "Setup" for further information.


addFinalStop - default: false
If set to true this option adds an additional bullet to the very end of the tracker(s). By default this final bullet is a little bigger than the others but this can be changed via the stylesheet.
This option is compatible with horNumbering and verNumbering.


finalStopTitle - default: ''
Allows you to add a custom title to the additioanl bullet of addFinalStop. Usually this only works if addFinalStop and either horTitles, verTitles or both are true; however this also works without addFinalStop if either horOnlyActiveTitle is true or on small screens if horTtiles is true.


hovering - default: true
Adds a hover effect to both the bullets and the titles if set to true. Naturally for this to take effect, at least one of horStops, verStops, horTitles and verTitles needs to be true. However if horStops, verStops and verTitles are set to false and only horTitles is set to true and horOnlyActiveTitle is also set to true, this still won't take effect.


linking - default: true
If set to true, clicking/tapping on either a bullet or a title will scroll to the top of the corresponding section. The behavior of this can be further customized with additional settings (see below).


skipHeadlines - default: false
The default behavior for linking is to scroll to the very top of a section. If this option is set to true, the headline of that section will be skipped when a bullet/title is clicked/tapped. This is useful if horOnlyActiveTitle is active, so that the title doesn't show twice.
On small screens this option is automatically applied if horTitles is active.


scrollSpeed - default: 800
This option controls the duration in milliseconds of the animation when a link is clicked. The higher this value, the slower the scroll animation.
Set this to 0 to jump to each section without an animation.


trackViewport - default: true
If set to true, the scroll position of the whole viewport will be displayed on the tracker(s) instead of the top of the viewport. In other words, if this is active the bottom of your screen is decisive, otherwise the top is.


Setup

1. Include the advanced-progress-tracker.min.css in the head

<link href="css/advanced-progress-tracker.min.css" rel="stylesheet" />

2. Include jQuery followed by advanced-progress-tracker.min.js in the head

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
<script src="js/advanced-progress-tracker.min.js"></script>

3. Initialize the plugin below the included scripts

<script>
    $('body').progressTracker();
</script>

Or with custom options (the options below are used in this ReadMe):

<script>
    $('body').progressTracker({
        horStops: false,
        horTitles: true,
        horMobileOnly: true,
        verTracker: true,
        verPosition: 'right',
        trackAllHeadlines: true,
        addFinalStop: true,
        finalStopTitle: 'Credits, Questions & Feedback',
        scrollSpeed: 1200
    });
</script>

If you want the Scroll Progress Tracker to track a certain area only (instead of the whole page), you have to define a container with the id "TrackScrollProgress".

<div id="TrackScrollProgress">
    <!-- insert content here -->
</div>

In order for horStops/verStops to work, you need to define sections with the class "spt-trackThis".

<div class="spt-trackThis">
    <!-- insert content here -->
</div>

In order for horTitles/verTitles to work, you also need to have h3-headlines within your sections.

<div class="spt-trackThis">
    <h3>section headline</h3>
    <!-- insert content here -->
</div>

In some cases you might want to display a different text than the h3-text on the progress tracker. This can be achieved by adding the data-name attribute to the headline. This will not affect the titles of the horizontal tracker if horOnlyActiveTitle is active or on small screens.
(the example below is from this ReadMe).

<h3 data-name="Introduction">Advanced jQuery scroll progress tracker</h3>

In some cases, for example if a content management system (cms) is used, it can be difficult to create custom containers. To compensate this, you can alternatively just attach the class "spt-trackThis" to the headline. The structure above will then automatically be created, i.e. a <div class="spt-trackThis"> will automatically be created around the h3 and the content and the class "spt-trackThis" will be removed from the h3 (thanks to R. Mansveld).

<h3 class="spt-trackThis">section headline</h3>
<!-- insert content here -->
...will automatically be converted to...
<div class="spt-trackThis">
    <h3>section headline</h3>
    <!-- insert content here -->
</div>

Tips & Tricks

After the first versions of this plugin had been released, the feedback I received showed me that I hadn't given a lot of thought to some things that are important but not self-explanatory. In this section I'd like to give you the means to use the plugin to the fullest extend of it's possibilities

Note: Please understand that I can't guide you through the basics of cascaded stylesheets in this ReadMe. Basic css-knowledge is the minimum requirement to enable you to change the style of this plugin (beyond it's given possibilities):


① Making changes to the style of the tracker(s):

The Advanced jQuery Scroll Progress Tracker plugin comes with a somewhat huge stylesheet that's probably pretty overwhelming to some users, which can potentially scare them away from changing any of them. However if you do it right, it's not all that hard to adjust the styles.

Before you decide to go through the hassle of changing any of the plugin's styles, you should read the "Options" carefully to make sure, you actually have to. There's a multitude of different settings that already allow for a huge number of visual changes to be made. To name just a fraction of them, you can for example have both a horizontal and a vertical tracker active at the same time, or one on small and one on large screens, or just one of them all the time; you can set the vertical tracker to be either on the left or the right of your content; you can also change the colors (of each tracker individually) and so on. So chances are, the visual changes you want to make are already in the options.

If you still want to change the plugin's styles, you should do so in an additional stylesheet. That way, if an update is released and you download it, your changes will not get lost. This means the first step in adjusting the styles should be to create a new stylesheet and include it in the <head> of your site.

In order for your changes to take effect, they need to overwrite the plugin's "factory styles". This can be achieved by including your stylesheet after the plugin's.

<link href="css/advanced-progress-tracker.min.css" rel="stylesheet" />
<link href="css/your-custom-stylesheet.css" rel="stylesheet" />

And with that you're set to adjust the plugin however you see fit. Since no future updates of the plugin will contain your own custom stylesheet, your changes will never be overwritten by accident, and by loading your stylesheet after the plugin's main stylesheet you can just style any element of the plugin like you would anything else.


② Creating your own gradients for the tracker:

Should you decide to change the way the tracker look as described in the first tip, you might want to create your own gradients for it as well. The most elegant way to do so is by generating it within the stylesheet (as opposed to creating a gradient image-file). However gradients can be assholes, since most browsers need them to be defined and set up differently.

The best way to create any gradient you can imagine and make it as compatible as possible, is to head over to the Ultimate CSS Gradient Generator. This tool allows you to create gradients in a Photoshop-like fashion and automatically generates the style for all relevant browsers.

However, if you're familiar with {less}, you probably created a *.less stylesheet in the first tip. If so, you can alternatively import the "_spt-settings.less" from the css/LESS directory of the plugin at the beginning of your stylesheet, and then use either the .spt-gradient2Stops or .spt-gradient3Stops mixin.

@import '_spt-settings.less';

.spt-horizontalScrollProgress {
    .spt-scrollProgressContainer {
        .spt-scrollProgressBar {
            .spt-gradient2Stops (left, to right, 1, 0%, 100%, @color-yellow, @color-green);
        }
    }
}

Update history

Version 1.2.2

Fixes:

Once more fixed the calculations...
Since, the area that holds the horizontal tracker got changed in the last update' »Removed superfluous elements«, the calculations for where to scroll to when a bullet on the tracker was clicked, needed to be changed again. While doing so, I also noticed and fixed a potentially fatal mistake: If a tracked area didn't have a tracked headline, the scrolling did not occur. Now it doesn't matter if there is a headline or not. This has been tested with and without trackAllHeadlines, skipHeadlines and horMobile / horMobileOnly and should thus (hopefully) work in all scenarios.

Version 1.2.1

Changes:

Added the "Tips & Tricks" and "Miscellaneous" sections to this ReadMe.


Removed superfluous elements.
There used to be an empty container for the horizontal tracker when the tracker itself was hidden via horMobile: false or horMobileOnly: true, which has now been removed.


Automatically adjust the max-width of .spt-centerAll if necessary.
Before, changing the mobileThreshold option could have some unwanted results in some cases.
Whenever it was too small in comparison to the max-width of .spt-centerAll, the vertical tracker would overlap the content on some resolutions. Now, it is enough to just change the mobileThreshold option. If it's value is smaller than the max-width of .spt-centerAll, the latter will automatically adjusted.


Moved the different color-presets out of the main stylesheet.
The additional lines in the stylesheet for the options horColor and verColor drastically increased the file size of the minified stylesheet. To minimize the core files of the plugin, they have been moved to their own stylesheets that only get included (automatically) in the site's <head> if at least one of those options is changed. That way you can now reduce traffic by only uploading the color-stylesheets you need. They can be found in the css/themes subdirectory (or, if you prefer working with {less}, in the css/LESS directory).

Note: In order for the colors to work properly, they have to be located in the css/themes directory of your site


Fixes:

Fixed a mistake that occured when the height/padding-top where changed by the user.
The script ignored the padding-top of the horizontal tracker when it was not in a <header> but positioned at the top, before.


Made the positioning values for the horTitlesOffset option dynamic.
Before, the offset-positioning of the horizontal tracker's titles was achieved using fixed margin-top values (i.e. margin-top: 38px; if horTitlesOffset was set to 'bottom'). This caused problems if the user changed the height, margin-top and / or padding-top of the horizontal tracker. Now, the offset gets calculated dynamically based on the tracker's height, margin and padding.

Version 1.2

Changes:

Changed the way headlines are tracked.
When trackAllHeadlines is set to true, the plugin now checks all headlines within the tracked area (i.e. #TrackScrollProgress or <body>) instead of any headline on the site.
Also, the tracker now only checks the first headline within each .spt-trackThis, instead of all.


Dynamically changes the space used by the vertical tracker on large screens.
Whenever the viewport is wide enough to be considered a large screen, the space used by the vertical tracker will be dynamically adjusted to maximize usability.


New Features:

Added option trackViewportOnly.
The behavior of the trackers can now be changed to act similar to a scroll bar, meaning the progress bar's length will represent the length of the tracked area and the bullets and/or titles will turn inactive once you leave the corresponding section.


Added options horColor and verColor to choose between different preset gradients.

Version 1.1.4

Changes:

Changed the names of all classes and ids.
To prevent any possible conflicts with other plugins, the names of all classes and ids have been changed to a more unique format.


Reduced the package size.
In order to keep the package as small and tidy as possible:

  • All the styles that are irrelevant for the plugin (i.e. the styles for this ReadMe) have been removed from the stylesheet.
  • The images used in the Options section are now stored online.

Version 1.1.3

Fixes:

Revised the whole calculation.
Sadly, even after all my previous "fixes", the calculations for most of the values were still awfully off (and seemed to be working with the right set of options, which is why I didn't notice it sooner). After investing quite some time and thought, they should now finally all work correctly.

Version 1.1.2

Fixes:

Increased the default value for mobileThreshold.
Up until now the horizontal tracker would overlap the content if the viewport was too narrow to contain both, but too wide to be considered a 'small screen'. The default value for mobileThreshold along with the max-width of .spt-centerAll has been adjusted to prevent that.
Additionally, the vertical tracker now moves 50px closer to the content as soon as the viewport is wide enough to fit the content + the tracker + 50px.

Version 1.1.1

Fixes:

Fixed a positioning bug for the vertical tracker.

Version 1.1

Fixes:

Fixed the combination of horOnlyActiveTitles and horStops: false
There was a bug where the title of the horizontal tracker did not show up for horOnlyActiveTitle when horStops was set to false.
It is now bound to horTitles instead, as it should be.


Fixed the behavior of horOnlyActiveTitles, linking and skipHeadlines
There was a minor mistake in the calculations for when to update the title of the horizontal tracker when on small screens and/or when horOnlyActiveTitles is set to true and for where to scroll when skipHeadlines is set to true. These values are now calculated correctly and the titles show up where you'd expect them to.


New features:

Added title-attribute to the bullets of the horizontal tracker
Before, when horOnlyActiveTitles was set to true, you basically had to guess what each stop represented. Now there will be a tooltip when you hover over them with a mouse cursor.


Added option horInHeader
It is now possible to put the horizontal tracker inside an existing <header>.
It is also possible to define where in the header it should be positioned by using either 'top' or 'bottom' as the option's value.


Added option horCenter
It is now possible to make the horizontal tracker span the full width of the viewport (aka the window/screen) by setting horCenter to false.
On small screens this is the default behavior!


Added options and styles for horStyle and verStyle
By changing the value of horStyle/verStyle, the style of the tracker(s) can now easily be changed.


Added option trackAllHeadlines
In addition to searching for each <h3> in the tracked area, it is now also possible to search for any headline instead. That way, for example, the very first section could have a <h1> (as seen in this ReadMe) but still give it's title to the tracker. However if you'd for example like to use <h4>-headlines within your tracked areas, you should handle this option with care (Though it would be possible to achieve both by putting the <h4> inside a not-tracked area (i.e. one without the class "spt-trackThis").


Credits

I'd like to thank René Mansveld (R.Mansveld@Spider-IT.de) for providing me with the "headline only markup"-solution
(see last point under "Setup").


I'd also like to address my sincere thanks to JSClasses user Herb Walsh for asking lots and lots and lots of questions and thus pointing out some flaws in the plugin and inspiring me to write the "Tips & Tricks" section.


Miscellaneous

If you're interested in my other plugins, like the "read more" plugin used in this ReadMe's "Tips & Tricks" section, feel free to download them from GitHub or JSClasses.org.


Questions & Feedback

If you have any questions, notice any bugs, have issues getting the plugin to work, have an idea for a cool feature to be added, or would like to leave any other kind of feedback, feel free to contact me under David@Whitworth.de

Also, please, feel free to send me links to websites where you used this!