Frameless Docs + New Menu

[eksperimental]

In #150 @alco mentioned that the core team is ok with removing the frames. The questions is raised, how are we going to get rid of those frames.

• just the module list itself now in HTML weights: 180KB
• modifying this html to pack it as much as possible i could only make it weight 50KB
• the data itself (just the module names, and the functions (with no module name and with a separator), all weights: 10KB

including the menu on every html page doesn't seem like a feasible option (in addition to modules, we need to add, protocol and exception lists).
Maybe we should look loading the module_list as json, and load it throught javascript on every page.
the module list will still be available as html in the overview page, in case javascript is disabled, or for search engine detection.

I was thinking of a menu that pops up upon a special key is hit, and covers the screen, and then you can navigate thought it and get rid of it as soon as you choose which page you want to read. or hit ESC.

I think http://jqapi.com/ has achieve this in a nice way, the way the navigational menu works.
Also the search is more advanced, i think the search funcitonality we have now is very basic as it doesn't return results sorted by relevance.

what you guys think?

[josevalim]

You are right, still loading the menu separately, maybe even with a simple ajax request would be the best. I think the issue with ajax though is that it wouldn't work when running locally due to cross origin requests?

I was thinking of a menu that pops up upon a special key is hit, and covers the screen, and then you can navigate thought it and get rid of it as soon as you choose which page you want to read. or hit ESC.

Actually, I am 👎 on this. Because most people will access the documentation for their first time and not know how to use it. I think it is important for the module list to always be visible. :)

[eksperimental]

1. Exactly, that is the problem very same proble with http://jqapi.com/, you cannot run it locally in Chrome (but it does work in Firefox).
   Can we avoid ajax, and just save all the modules, exceptions and protocols in one json file, and loading this from the <script ..> tag as explained here.
   This way we can get rid of frames and have the menu in every page.

2. Additionally, if having a pop-up menu is not a very intuitive idea for first-time users, how about having a similar side-bar menu, but a collapsible one, with a menu-icon like most websites when dealing with mobile clients. The Menu can stay in the left-top corner all the time so it can take as little space as possible, and be accessible at all times.

3. The navigation features of jqapi.com can be implemented to either menu, and I think they are useful and do no hurt but help.

Anyway, item no. 2 & 3 are optional, and we can build it on top of item no.1, once that one is working.
What you think about this?

[josevalim]

Perfect! I am ok with making the menu collapsible as long as it is opt-in. Although I particularly won't use features 2 and 3, it is ok if it is not adding a bunch of complexity. :) Thank you for looking into this!

[eksperimental]

I will starting with porting everything to json/javascript, and from there we'll see
do you recommend any json library?
I was thiking of using jazz the whole repo is 38kb, but i haven't looked much into this one really, or any other options.

[josevalim]

Hrm... I would go with poison. But maybe it would be easy enough to generate the JSON by hand? Up to you! :D

[milmazz]

@josevalim @eksperimental I think that we can replace {modules,exceptions,protocols}_list.html for something like sidebar-items.js:

fillSidebarWithNodes({
    "protocols" : [
        {
            "id": "Ecto.Queryable",
            "docs": ["to_query/1"]
        }
    ],
    "exceptions" : [
        {
            "id": "Ecto.CastError",
            "docs": ["exception/1", "message/1"]
        },
        {
            "id": "Ecto.ChangeError",
            "docs": ["exception/1", "message/1"]
        }
   ]
});

Then we can recreate the current layout for the sidebar with jQuery:

// Somewhere in the app.js
function fillSidebarWithNodes(nodes) {
    var full_list = $("#full_list");

    function scope(items) {
        var filtered = nodes[items];
        if(!filtered) {
            return;
        }

        for(var i = 0, l = filtered.length; i < l; i++) {
            var id = filtered[i].id;
            var docs = filtered[i].docs;

            /* li.node */

            var li = $('<li>', {'class': 'node ' + items});
            if (docs.length !== 0) {
                li.append($('<a/>').attr('class', 'toggle'));
            }

            li.append($('<a/>', {'href': id + '.html',
                                 'title': id,
                                 'html': id,
                                 'class': 'object_link'}));
            li.append($('<span/>', {'class': 'node_name', 'html': id}));


          full_list.append(li);

          if (docs.length !== 0){

          /* li.docs */
          var docs_container = $('<li>', {'class': 'docs'});
          docs_container.append($('<ul>'));

          for(j = 0, l = docs.length; j < l; j++) {
            var detail = $('<li>');
            detail.append($('<a/>', {'href': id + '.html' + '#' + docs[i], 'title': id + '.' + docs[i], 'class': 'object_link', 'html': docs[i]}));
            detail.append($('<span/>', {'class': 'node_name', 'html': id}));
            docs_container.append(detail);
          }
            full_list.append(docs_container);

        }
          }
    }

    scope("exceptions");
}

As a side note, the previous code sample is just a proposal, for me its better to control all that mess with a template system like Liquid or Handlebars, but I'm assuming that you don't want to include another dependency.

So, with this approach I think we can get ride of the frames (of course, we need to do more changes).

In each page that we want the sidebar we can include a line like this:

<script src="sidebar-items.js" defer></script>

If you want I can work on this issue. Example

[josevalim]

This sounds quite good to me. Let's see if @eksperimental or @alco have some thoughts to share, otherwise we can go ahead.