Foundation-sites: Magellan docs don't explain how to use it

[hocine]

The docs for Magellan don't contain any javascript, only html. Please update the docs so they explain exactly how to implement Magellan?

[tedpennings]

+1

[shovanuk]

+1

[briancwald]

The documentation for it on the site doesn't make sense, here is what I did to use it (basically extrapolated from what was on the site source):

<dl id="magellanTopNav" class="sub-nav" data-magellan-expedition="fixed">
  <dd data-magellan-arrival="fiji"><a href="#fiji">Fiji</a></dd>
  <dd data-magellan-arrival="bahamas"><a href="#bahamas">Bahamas</a></dd>
  <dd data-magellan-arrival="hawaii"><a href="#hawaii">Hawaii</a></dd>
</dl>

(only use fixed if you want it to follow you, which, is of course kinda the point)

Destinations here:

<a name="fiji" data-magellan-destination="fiji"></a>
<a name="bahamas" data-magellan-destination="bahamas"></a>
<a name="hawaii" data-magellan-destination="hawaii"></a>

On the site it says to use div, although id recommend using an anchor instead.

and of course, style #magellanTopNav how you want it.

[hatefulcrawdad]

Docs explain clearly how to use it.

[rjakobsson]

I'm sorry, but the documentation is still a mess, examples showing stuff that doesn't relate (the first example).
The second example is better but it would be better if "Destination" could come after "Arrival".
It must be better explained.

"data-magellan-arrival" is the menu item and the point that triggers the switch is "data-magellan-destination".
Once the "data-magellan-destination"-element is reached, the "data-magellan-arrival"-element will get a ".active" class.

[saidimu]

@zurbchris How do you know the docs clearly explain how to use Magellan? They docs may make sense to you but that doesn't necessarily make them clear to others.

[binaryphile]

+1, the examples are not clear enough to implement and contain mistakes. First, the destinations in the sample code are supposed to correspond to the ones used in the working example on the page, yet the example html refers to the second target as "Arrival 2", not "Using JavaScript" as would be consistent. Second, it is less than clear that in showing you examples of both ul and dl implementation that you are only supposed to choose one. Third, it does not break down the role played by each attribute in the markup and how it ties from destination to arrival. Nor are the terms destination and arrival defined. Finally, in order to explain how to include the css and javascript, the text refers you to other pages which describe the general process of adding things but do not contain the code to add the magellan css and javascript specifically.

That's just a list I came up with after looking at the page for a few seconds, which is to say there are surely more issues to be found. While these things may seem self-explanatory to someone quite familiar with implementing foundation, for a novice they seem quite opaque. A google search will uncover other people confused by this topic as well. It's not a bad idea to give this page an actual once-over rather than simply overlooking it.

Also, I tried using the ul form for the list after successfully using the dl form, and the ul form doesn't receive the correct css.

[kevando]

Zurb docs continue to lack complete examples. At least one of the comments here explains why they're like that:

...commented: "Docs explain clearly how to use it."
... closed the issue

[coreyward]

+1 — Magellan is poorly documented, and this is exacerbated by poor choice in language (e.g. arrival is actually an indicator of current position).

[ghost]

I agree. Wouldn't be hard to change docs! Anyone up for editing the docs. I myself have not yet done a pull request so its beyond my skills. In fact, when users like me come across issues, it would be usefully to also have a place in the docs that explains how to contribute to foundations on github. So as a community, we can fix things as appose to just point out the problems and hope someone will address it.

[JonKernPA]

Love the Zurb stuff. Love that they freely open-source these cool tools and provide documentation to the community. So, it is hard to complain about "free." But, in the spirit of community, I think our frustration is often due to being excited about trying out a new, cool, thing, and getting bummed out when running into small roadblocks. (Especially for me, a hacker, who is not really qualified to jump in and discover some crazy cascading javascript or CSS explanation for the odd behavior.)

The disjointed and terse example on the Magellan docs page does leave one asking for more details.

_Disjointed_ example:

• Arrivals (build, js)

<div data-magellan-expedition="fixed"> 
  <dl class="sub-nav"> 
    <dd data-magellan-arrival="build"><a href="#build">Build with HTML</a></dd> 
    <dd data-magellan-arrival="js"><a href="#js">Arrival 2</a></dd>
  </dl>
</div>

• Destinations (arrival, destination)

<a name="arrival"></a> 
<h3 data-magellan-destination="arrival">Arrival</h3> 
<a name="destination"></a> 
<h3 data-magellan-destination="destination">Destination</h3>

(Using "arrival" as an example for destination is very unfortunate. Maybe the docs should have used something more obvious: First Section, Second Section, Third Section)

I had a great deal of trouble to get the nesting correct on my page that also included the topbar element. There seemed to be conflicts with having the topbar being contain-to-grid and fixed.

From what I have gleaned by looking at the page source and doing a lot of trial and error (:boom:), I got something to work "good enough" (as I got tired of the trial and error):

• In one div, define the arrivals
• Later in the page, define the matching destinations
• And fiddle around with divs, nesting, classes, until it works the way you like

An example in haml (sorry for not doing it in HTML, but this is ripped from an app I am writing -- modified slightly for this post):

- structure_elements = %w(Access Interior Roof Shutoff)
- structure = @structure

%div{"data-magellan-expedition" => "fixed"}
  %dl.sub-nav
    - structure_elements.each do |element|
      %dd{"data-magellan-arrival" => element}
        = link_to element, "##{element}"
%article#structure
  %h4
    = link_to structure.name, edit_structure_path(structure)
    = link_to fa_icon('pencil'), edit_structure_path(structure)

- structure_elements.each do |element|
  %a{name: element}
  %h3{"data-magellan-destination" => element}
    = element
  %div.panel
    ="#{Faker::Lorem.paragraphs(3).join(' ')}"

I hope this helps :heart_eyes_cat:

[joneshf]

This issue should probably to be reopened. As the last 7 people will surely agree, this issue is not fixed.

The docs still are very unclear. I'd surely like to help out and improve the docs, but I cannot figure out how to get this to work.

Things I don't understand

• What is the minimum that is needed in order to have the navigation stick?
• Am I forced to use dl tags and their children, or can I use ul's and ol's?
• Can I use any other tags, div, span, anything else?
• Is there any kind of structure?
• Can this be nested?
• What are the limitations?
• What classes are applicable/needed?
• What data attributes are applicable/needed?

There's probably more things, but these are just some questions I ran into while trying to use this.

If anyone knows how to answer these, please update the docs:

https://github.com/zurb/foundation/blob/master/doc/pages/components/magellan.html
https://github.com/zurb/foundation/tree/master/doc/includes/magellan

If you need help on that part I can help, just post back here how things are supposed to work. But, I've no clue how to answer those questions myself.

[lozandier]

Hi, @JonKernPA & @joneshf: We'll definitely look into this more, especially the supposed discrepancy between the class names and attributes necessary to implement a magellan component.

[JonKernPA]

Oh, I did figure it out… I should write up a blog post or something… Here is a quick cut-n-paste from my code, with some minor edits to remove stuff that isn’t germane. Hope it helps

show.html.haml

    .row
      .nav-column
        =render 'shared/preplan_nav', preplans: [@structure.preplan]
      .content-column
        - structure_elements = %w(Access Interior Roof Shutoff Drain FloorPlan SiteDetails Documents)
        %div{"data-magellan-expedition" => "fixed"}
          %dl.sub-nav
            - structure_elements.each do |element|
              %dd{"data-magellan-arrival" => element}
                = link_to element, "##{element}"

        .container
          %article#structure
            %h4
              Blah Blah Blah
          %hr
        = render partial: 'photos/photos', locals: {owner: @structure}
        = render 'roofs/index'
        = render 'accesses/index'
        = render 'shutoffs/index'

Each partial then provided the destinations:
roofs/_index.html.haml

%hr
%a{name: "Roof"}
%h3{"data-magellan-destination" => "Roof"}
  .add_roof
    Roof
    =link_to new_preplan_structure_roof_path(@structure.preplan, @structure), title: 'Click to add' do
      %i.fa.fa-plus-circle
- if @structure.roofs.count > 0
  blah blah blah

[sebastianwestberg]

Are there any events provided? I'd like to trigger a function when my element switches between sticky and default positioning. Can't find anything regarding this in the docs.