Filtering javascript from Sepembre

filter.js

// Most websites use a javascript library known as jQuery.
// This library is used for finding certain elements on a page by certain attributes and/or by tag name
// and then setting events, finding their neighbors, inserting html, reading values, and pretty much a
// of other things.
//
// The main function is called jQuery(), but $ = jQuery(), so $() is used as a shortcut.
$(function() {

  // Here a variable named $container is being set from finding an element with an id attribute of container.
  // So for example:
  // <div id="container">
  //  <p>Hi!</p>
  // </div>
  //
  // $('#container') would return an a javascript object that represents the element above.
  // 
  var $container = $('#container');


  // isotope seems to be some custom plugin that is being used with jquery. jquery has tons of plugins that ppl make.
  $container.isotope({
    itemSelector : '.story'
  });

  // here $optionSets will be a collection of elements that can be found by finding an element with id "sort" 
  // that has any descendants (sub elements, like the <p> in the example HTML above) that have a class attribute that contains "option-set"
  var $optionSets = $('#sort .option-set'),
  // Then from that collection of elements, find any elements that are <a> (link) elements.
  $optionLinks = $optionSets.find('a');

  // For each of those <a> (link) elements, whenever they are clicked, we want this function to run.
  $optionLinks.click(function(){

    // When you pass a function to jQuery's click function, jQuery will set "this" to be the javascript object of the <a> element. 
    // But since dealing with the plain javascript object that reps the <a> is a bit more verbose to deal with, you can pass it to $()
    // and get back a jquery object that allows you to use all the convenience functions for doing things with it.
    var $this = $(this);


    // Here it's checking to see if the <a> element has a classname "selected" in its class attribute.
    // If it does, we exit this function by returning false, which tells the browser to not follow the link.
    if ( $this.hasClass('selected') ) {
      return false;
    }
    // Here we're looking for any of this <a> element's ancestor elements that have a class name of "option-set" in their class atribute. 
    var $optionSet = $this.parents('.option-set');
    // For any that we end finding, find any direct descendants that have the "selected" class and remove that class name from the class attribute.
    // This effectively removes any selected filter links you may have had selected before.
    $optionSet.find('.selected').removeClass('selected');

    // We set this <a> to be selected now by adding the "selected" classname to its class attribute
    $this.addClass('selected');

    // make option object dynamically, i.e. { filter: '.my-filter-class' }
    // Here we create a plain javascript object or otherwise known as a Hash/Dictionary
    var options = {},
    // Here we get the value of the "data-option-key" attribute for the element represented by $optionSet
    key = $optionSet.attr('data-option-key'),
    // And here we get the value of the "data-option-filter" attribute for this <a> element
    value = $this.attr('data-option-filter');
    // parse 'false' as false boolean
    // Here we set the value variable by checking if value is equal to the string 'false' and value is in fact a string object.
    // If those things are true, then we set value to false. Otherwise we set it to whatever value was from data-option-filter attr we read above
    value = value === 'false' ? false : value;
    // Here is an example of the box analogy I mentioned to you when we first started talking.
    // options is a hash/dictionary and we're labeling the box with the key variable and putting value in the box.
    // The syntax is dictionary[key] = value. You can reference the value by using the key when you do: var myVar = dictionary[key]; 
    // myVar would then equal whatever was value.
    options[ key ] = value;

    // Here they are checking whether key is 'layoutMode' or if changeLayoutMode is a function. 
    // Based on those conditions, it either calls this changeLayoutMode function and passes the <a> object along with some options or it does
    // someting else

    if ( key === 'layoutMode' && typeof changeLayoutMode === 'function' ) {
      // changes in layout modes need extra logic
      changeLayoutMode( $this, options )
    } else {
      // otherwise, apply new options
      $container.isotope( options );
    }

    // in the end you return false, so that the browser doesn't try to redirect you to somewhere by following any sort of url in the href attribute of <a>
    return false;
  });