Skip to content

Commit

Permalink
Make functions in docs filterable
Browse files Browse the repository at this point in the history
With a utility library like Underscore, it is very common to open the docs with
the aim of locating the documentation for a specific function.

Currently I use my browser's search functionality, but since many functions
reference other functions, I frequently have to cycle through multiple matches
before I arrive at the actual function's description.

This patch aims to improve this common use case by offering a "filter" input
above the list of functions. As a user types, the list of functions (and
section titles) is reduced, leaving only the matching functions. If the user
presses enter, they are jumped to the documentation for the first matching
function.

This functionality (and implementation) is greatly inspired by the
implementation that is included in the [Ramda docs](http://ramdajs.com/0.21.0/docs/).

You can read their source code [here](https://github.com/ramda/ramda.github.io/blob/master/main.js)
  • Loading branch information
captbaritone committed Apr 25, 2016
1 parent 0f8895e commit 66da49f
Show file tree
Hide file tree
Showing 3 changed files with 243 additions and 156 deletions.
5 changes: 5 additions & 0 deletions docs/.eslintrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"globals": {
"_": true
}
}
58 changes: 58 additions & 0 deletions docs/main.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
(function() {
var functions = document.querySelectorAll('[data-name]');
var sections = document.querySelectorAll('.searchable_section');
var searchInput = document.getElementById('function_filter');

function strIn(a, b) {
a = a.toLowerCase();
b = b.toLowerCase();
return b.indexOf(a) >= 0;
}

function doesMatch(element) {
var name = element.getAttribute('data-name');
var aliases = element.getAttribute('data-aliases') || '';
return strIn(searchInput.value, name) || strIn(searchInput.value, aliases);
}

function filterElement(element) {
element.style.display = doesMatch(element) ? '' : 'none';
}

function filterToc() {
_.each(functions, filterElement);

var emptySearch = searchInput.value === '';

// Hide the titles of empty sections
_.each(sections, function(section) {
var sectionFunctions = section.querySelectorAll('[data-name]');
var showSection = emptySearch || _.some(sectionFunctions, doesMatch);
section.style.display = showSection ? '' : 'none';
});
}

function gotoFirst() {
var firstFunction = _.find(functions, doesMatch);
if(firstFunction) {
window.location.hash = firstFunction.getAttribute('data-name');
searchInput.focus();
}
}

searchInput.addEventListener('input', filterToc, false);

// Press "Enter" to jump to the first matching function
searchInput.addEventListener('keypress', function(e) {
if (e.which === 13) {
gotoFirst();
}
});

// Press "/" to search
document.body.addEventListener('keyup', function(event) {
if (191 === event.which) {
searchInput.focus();
}
});
}());
Loading

0 comments on commit 66da49f

Please sign in to comment.