Foundation-sites: [Smooth Scroll] Javascript documentation is confusing

Created on 29 Apr 2018  路  1Comment  路  Source: foundation/foundation-sites

This Issue is a complaint about documentation confusion. This particular issue is written for this one page, however, the underlying problem is systemic to the entire Zurb documentation site.

Basically, the Javscript help portions of the site tend to be rather confusing.

My Use Case:

  • I'm using Panini + Zurb Template

Tonight I decided to attempt to add a mouse wheel scrolling feature to my web site.

  1. I head over to Zurb's docs where I find the page on smooth-scroll and discover that this mouse wheel feature isn't part of Zurb. So, skipping that, I write my own javascript function to handle the mouse wheel and I get to the point where I need to call (I think) scrollToLoc. (because the doc page says so)

  2. The Zurb docs say to do this:
    $('#element').foundation('scrollToLoc', loc, options, callback);

This is where the confusion happens. What is #element? What is loc?

My page is setup like this:

NOTE: It would be very helpful if the javascript page showed code like this as well. It took me about 15-20 mins poking around the site to figure this out.

<body>
  <section id="panel1">hello, world</section>
  <section id="panel2">I like cake</section>
  <section id="panel3">Nintendo makes fun games</section>
</body>

Here's the mousewheel code (using jquery plugin)

$(window).on('mousewheel', function (e) {
  console.log(e.deltaY);
  // calculate which panel we are closest to above and below
  // now we have a jquery selector for the panel that we want to scroll to
  // and... now what?
});

What should the call be? None of these work:

$(document).foundation('scrollToLoc', $('#panel2'), {threshold: 50, offset: 100}, function(){console.log('scrolled');});

$(this).foundation('scrollToLoc', $('#panel2'), {threshold: 50, offset: 100}, function(){console.log('scrolled');});

$('#panel1').foundation('scrollToLoc', $('#panel2'), {threshold: 50, offset: 100}, function(){console.log('scrolled');});

I have tried other crazy combinations as well. The error always seems to be ReferenceError: We're sorry, 'scrollToLoc' is not an available method for this element.

Again, this issue is about the documentation. What is the documentation telling me? Is it assuming something that I should have known? What is supposed to be in $('#element')? What goes in loc? Why don't my ideas work?

To compound things, the docs have lines like this:

var elem = new Foundation.SmoothScroll(element, options);

They don't work in Panini + Zurb Template.

Another frustration is all the mention of this all around the docs site.

    foundation.core.js
    foundation.smoothScroll.js

If you go to Foundation for Sites 6 home page, click the "Download Foundation 6" button, then "Download Everything", the resulting zip file, does not have these javascript files in it. Not in Essentials or Custom either. This information is not helpful on the docs page. Maybe it's helpful to a developer who is wanting to contribute to Foundation. So maybe put this at the bottom of the page, next to a discrete label that says something like "For Developers - Look in GitHub for these two files. They are here"

Imagine you are brand new to Zurb. You type in a few of these code samples and nothing works. You see these js files that aren't in the package. You stumble on the Zurb Template and it's no better about this...

Total Time Spent: 4.5 hours

Expected Outcome

  • Please put html snippets on the pages with the Javscript
  • Please describe in detail what #element is and what loc is
  • Please mention what is the difference between Smooth Scroll and Magellan? The code samples seem to result in the same sort of thing.
Smooth Scroll question 馃摉 documentation
Source
picture dagostinelli

Most helpful comment

Hi @dagostinelli. Thank you for your issue. I'll try to reply to all your points and questions.

Tonight I decided to attempt to add a mouse wheel scrolling feature to my web site.

At first as a webdesigner I have to warn you: it may seem to be "smooth and beautiful" but in most case this is not a good idea to control the user scroll. This often prevents a free move across the webpage, adds delays, doesn't play well with trackpads and for all these reasons may cause disconfort or frustrations. Scroll must be free.

$('#element').foundation('scrollToLoc', loc, options, callback);
This is where the confusion happens. What is #element? What is loc?

You found that in the "Methods" section of the Smooth Scroll documentation. Methods can be called on Foundation plugins instances. This means that you first have to create a plugin instance call methods on it later.

For SmoothScroll it is a bit different: its only method scrollToLoc is static, it can be called on the SmoothScroll plugin class directly and does not need an instance.

So you can do:

<section id="section">Section</section>

```js
Foundation.SmoothScroll.scrollToLoc('#section');


But if you want to call it on a jQuery element `$(<element>).foundation(<method>)`, the element must be a SmoothScroll instance.

For example:
```html
<a id="link-to-section" href="#section" data-smooth-scroll>Link to section</a>
<section id="section">Section</section>

```js
// Move to section
instance.scrollToLoc('#section');


Of if you want to manually instantiate the plugin:
```html
<a id="link-to-section" href="#section">Link to section</a>
<section id="section">Section</section>

```js
// Manually create a SmoothScroll instance
const instance = new Foundation.SmoothScroll('#link-to-section');
// Move to section
instance.scrollToLoc('#section');


You may have guessed it now: `element` is the DOM element you want to create a SmoothScroll instance on. For SmoothScroll you can create an instance on a link, that will make the page smoothly scroll to the link target instead of jumping to it when you click on the link. `loc` is the target you want to scroll to.

But there isn't any advantages with using the last two example in your case because all you want is to call "scrollToLoc" manually. As this is a static method, there is no need to create an instance and call it via jQuery.

The exampel `$('#element').foundation('scrollToLoc', loc, options, callback);` is automatically generated and as explained above it misleading because `scrollToLoc` is a static method. We may have to fix our documentation generator to use others examples for static methods.

---

> It would be very helpful if the javascript page showed code like this as well. It took me about 15-20 mins poking around the site to figure this out.

I don't understand what you expected the documentation to show you. If you're talking about the list of section with their dedicated ids, well it's not the expected usecase for SmoothScroll. We may have to improve the `scrollToLoc` documentation but you are free to organize your HTML as you want. All `scrollToLoc` is expecting is an target.

---

> What should the call be? None of these work:

This should work:
```js 
Foundation.SmoothScroll.scrollToLoc('#panel2', {
  threshold: 50,
  offset: 100
}, function(){
  console.log('scrolled');
});

The error always seems to be ReferenceError: We're sorry, 'scrollToLoc' is not an available method for this element.

As explained above: $(<element>).foundation(<method>) should be called on elements with a Foundation plugin instance associated to it. Using <div id="element" data-<plugin> > in the HTML or manually creating a plugin instance with new Foundation.<plugin>('#element'); will create an instance on #element and allow you to call $('#element').foundation(<method>);

To compound things, the docs have lines like this:

var elem = new Foundation.SmoothScroll(element, options);

They don't work in Panini + Zurb Template.

Please explain. What's not working ?

Another frustration is all the mention of this all around the docs site.

  foundation.core.js
  foundation.smoothScroll.js

This means that if you import Foundation plugin per plugin, you have to make sure that these plugins are imported. See https://foundation.zurb.com/sites/docs/javascript.html#file-structure

When you use foundation.js you can ignore this, all plugins are included in it.

Please mention what is the difference between Smooth Scroll and Magellan? The code samples seem to result in the same sort of thing.

I would advise you to take a closer look at the documentation, each plugin role is correctly explained. Smooth Scroll allow you to make a link smoothly scroll to its target. Magellan track where you are in the page and update its list of links according to it. Magellan uses SmoothScroll when you click on one of its links and provide its own options to customize the scroll animation.

So you are right on some points and the documentation can be improved about how to use static methods and how to create plugin instances with and without jQuery. For your others points I think I replied to them. Let me know if something is still unclear.

I'm letting this open as there is some work to do in foundation-docs.

picture ncoden on 29 Apr 2018
👍3

>All comments

Hi @dagostinelli. Thank you for your issue. I'll try to reply to all your points and questions.

Tonight I decided to attempt to add a mouse wheel scrolling feature to my web site.

At first as a webdesigner I have to warn you: it may seem to be "smooth and beautiful" but in most case this is not a good idea to control the user scroll. This often prevents a free move across the webpage, adds delays, doesn't play well with trackpads and for all these reasons may cause disconfort or frustrations. Scroll must be free.

$('#element').foundation('scrollToLoc', loc, options, callback);
This is where the confusion happens. What is #element? What is loc?

You found that in the "Methods" section of the Smooth Scroll documentation. Methods can be called on Foundation plugins instances. This means that you first have to create a plugin instance call methods on it later.

For SmoothScroll it is a bit different: its only method scrollToLoc is static, it can be called on the SmoothScroll plugin class directly and does not need an instance.

So you can do:

<section id="section">Section</section>

```js
Foundation.SmoothScroll.scrollToLoc('#section');


But if you want to call it on a jQuery element `$(<element>).foundation(<method>)`, the element must be a SmoothScroll instance.

For example:
```html
<a id="link-to-section" href="#section" data-smooth-scroll>Link to section</a>
<section id="section">Section</section>

```js
// Move to section
instance.scrollToLoc('#section');


Of if you want to manually instantiate the plugin:
```html
<a id="link-to-section" href="#section">Link to section</a>
<section id="section">Section</section>

```js
// Manually create a SmoothScroll instance
const instance = new Foundation.SmoothScroll('#link-to-section');
// Move to section
instance.scrollToLoc('#section');


You may have guessed it now: `element` is the DOM element you want to create a SmoothScroll instance on. For SmoothScroll you can create an instance on a link, that will make the page smoothly scroll to the link target instead of jumping to it when you click on the link. `loc` is the target you want to scroll to.

But there isn't any advantages with using the last two example in your case because all you want is to call "scrollToLoc" manually. As this is a static method, there is no need to create an instance and call it via jQuery.

The exampel `$('#element').foundation('scrollToLoc', loc, options, callback);` is automatically generated and as explained above it misleading because `scrollToLoc` is a static method. We may have to fix our documentation generator to use others examples for static methods.

---

> It would be very helpful if the javascript page showed code like this as well. It took me about 15-20 mins poking around the site to figure this out.

I don't understand what you expected the documentation to show you. If you're talking about the list of section with their dedicated ids, well it's not the expected usecase for SmoothScroll. We may have to improve the `scrollToLoc` documentation but you are free to organize your HTML as you want. All `scrollToLoc` is expecting is an target.

---

> What should the call be? None of these work:

This should work:
```js 
Foundation.SmoothScroll.scrollToLoc('#panel2', {
  threshold: 50,
  offset: 100
}, function(){
  console.log('scrolled');
});

The error always seems to be ReferenceError: We're sorry, 'scrollToLoc' is not an available method for this element.

As explained above: $(<element>).foundation(<method>) should be called on elements with a Foundation plugin instance associated to it. Using <div id="element" data-<plugin> > in the HTML or manually creating a plugin instance with new Foundation.<plugin>('#element'); will create an instance on #element and allow you to call $('#element').foundation(<method>);

To compound things, the docs have lines like this:

var elem = new Foundation.SmoothScroll(element, options);

They don't work in Panini + Zurb Template.

Please explain. What's not working ?

Another frustration is all the mention of this all around the docs site.

  foundation.core.js
  foundation.smoothScroll.js

This means that if you import Foundation plugin per plugin, you have to make sure that these plugins are imported. See https://foundation.zurb.com/sites/docs/javascript.html#file-structure

When you use foundation.js you can ignore this, all plugins are included in it.

Please mention what is the difference between Smooth Scroll and Magellan? The code samples seem to result in the same sort of thing.

I would advise you to take a closer look at the documentation, each plugin role is correctly explained. Smooth Scroll allow you to make a link smoothly scroll to its target. Magellan track where you are in the page and update its list of links according to it. Magellan uses SmoothScroll when you click on one of its links and provide its own options to customize the scroll animation.

So you are right on some points and the documentation can be improved about how to use static methods and how to create plugin instances with and without jQuery. For your others points I think I replied to them. Let me know if something is still unclear.

I'm letting this open as there is some work to do in foundation-docs.

ncoden picture ncoden on 29 Apr 2018
👍3
Was this page helpful?
0 / 5 - 0 ratings

Related issues

johnbacon picture johnbacon  路  3Comments
BicanMarianValeriu picture BicanMarianValeriu  路  3Comments
johnbacon picture johnbacon  路  4Comments
coachie picture coachie  路  4Comments
anware picture anware  路  3Comments