Hash Browns

Hash Browns

Hash Browns is an ExpressionEngine plugin that enables you to easily create an AJAX navigable site with little to no markup changes.

Docs

Settings always display the default value.

You can edit the code within <pre>s on this page before copying and pasting.

Features

  • AJAXily navigate your site. No JavaScript/AJAX knowledge required!
  • Requires little to no markup changes
  • Compatible with custom animations
  • Navigation works fine for users with JavaScript disabled
  • Compatible with browsers’ back/forward buttons*

Browser Support**

  • Internet Explorer 6+
  • Firefox 2+
  • Chrome 5+
  • Safari 3.2+
  • Opera 9.6+
  • iPhone 3.1+
  • Android 1.6+
  • BlackBerry 4.6+

*Because of the way browsers handle hash links, users cannot navigate back to the first loaded page with the back button. However, each subsequently loaded page re-navigable to via the back button.

**For more browser support info, see jQuery Hashchange Plugin’s support info.

Installation

  1. Upload the hash_browns folder to system/expressionengine/third_party.
  2. Upload the themes/third_party/hash_browns folder to themes/third_party.

{exp:hash_browns}

Make sure you include jQuery before the Hash Browns code.

{exp:hash_browns} loads the necessary JavaScript to make your site AJAXy.

<script src="jquery.js"></script>
{exp:hash_browns}

Required Settings

page_wrap
page_wrap="#page_wrap"

The id or class of your typical page_wrap element. Hash Browns will vertically resize this when new content loads.

Set your page_wrap element to overflow: hidden to avoid jumpy animation.

main
main="#main"

The id or class of the main element. In most (all?) cases, this should contain only the content element. This helps the JavaScript load everything in its right place.

content
content="#content"

The id or class of the element that Hash Browns should discard and reload (from the linked page).

link_containers
link_containers="#nav_main"

A pipe-separated (|) list of elements that contain the links to content that Hash Browns should load via AJAX.

Optional Parameters

callback
callback=""

This allows you to set a JavaScript callback function after Hash Browns vertically resizes page_wrap.

If you load/reload any of the link_containers, you should set this to hash_browns. This allows you to use Hash Browns with a dynamic nav (like the one in the Statamic docs, which changes based on the current page).

Alternatively, if you do not reload the initial link_containers but do load new links that you want to Hash Brown-ify, for better performance, you can set this to initiateHashNav('.new_link_containers') (replacing .new_link_containers with a comma-separated list of elements that contain the new links to content that Hash Browns should load via AJAX).

{exp:hash_browns callback="hash_browns"}
class_active
class_active=""

Setting this adds the given class to the anchor tag for the current page (or the specified parent element if you use class_active_parent_el). This does not add a class until the user clicks a link, so if you use it, you should manually add the class in the template/layout for the landing page.

{exp:hash_browns class_active="active"}
class_active_parent_el
class_active_parent_el=""

If you use class_active, Hash Browns sets the class on the clicked anchor tag by default. Sometimes people prefer to set the active class on a parent element, like an li. This allows you to do so.

{exp:hash_browns
  class_active           = "active"
  class_active_parent_el = "li"
}
content_add_class_in
content_add_class_in=""

A pipe-separated (|) list of classes added to content just after Hash Browns triggers the fx_in animation. Good for CSS animations, like those found in Animate.css.

content_add_class_out
content_add_class_out=""

A pipe-separated (|) list of classes added to content just before Hash Browns triggers the fx_out animation. Good for CSS animations, like those found in Animate.css.

duration_in
duration_in="500"

The duration, in milliseconds, of the animation for fx_in.

duration_out
duration_out="500"

The duration, in milliseconds, of the animation for fx_out.

fx_in
fx_in="fadeIn"

The animation used for incoming content.

Valid Values

nofx, slideDown, or your own custom effect

Have some crazy effect from a jQuery plugin you want to use? That works, too. Just include the plugin before the Hash Browns code.

<script src="jquery.js"></script>
<script src="crazy_plugin.js"></script>
{exp:hash_browns fx_in="crazyEffect"}
fx_out
fx_out="fadeOut"

The animation used for outgoing content.

Valid Values

nofx, slideUp, or your own custom effect

Have some crazy effect from a jQuery plugin you want to use? That works, too. Just include the plugin before the Hash Browns code.

<script src="jquery.js"></script>
<script src="crazy_plugin.js"></script>
{exp:hash_browns fx_out="otherCrazyEffect"}
load_hashchange
load_hashchange="true"

If you don’t want to load the jQuery Hashchange Plugin, set this to false. However, browser support narrows without it.

relative_links
relative_links="false"

If you use relative links in link_containers, set this to true.

script_tags
script_tags="true"

Set this to false to not return opening or closing script tags. This allows you to add the Hash Browns tag to inline JavaScript.

<script>
  $('.selector').function();
  {exp:hash_browns script_tags="false"}
</script>
url_offset
url_offset=""

This allows you to manually offset the characters shown in the URL hash, which makes child page urls prettier.

For example,

http://example.com/segment_1#segment_2

instead of

http://example.com/segment_1#segment_1/segment_2
Valid Values

Integers or the piece of the URL you want removed (/segment_1/segment_2/).

{exp:hash_browns:ajax}

This tag returns true for AJAX requests or false otherwise. Use this in conditionals so that you don’t reload any code identical between pages (like headers and footers). This will boost the speed of your page load.

{if {exp:hash_browns:ajax} == "false"}
  {!-- your template code here --}
{/if}
See the demo included in the downloaded files for a more thorough example.

Basic Example

<!doctype html>
<html>
<body>
  <div id="page_wrap">
    <nav id="nav_primary">
      <ol>
        <li><a class="current" href="{homepage}"        >Home   </a></li>
        <li><a                 href="{homepage}/contact">Contact</a></li>
      </ol>
    </nav>

    <div id="main">
      <div id="content">

        {!-- your content here --}

      </div>
    </div>
  </div>

  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js"></script>
  {exp:hash_browns class_active="current"}
</body>
</html>

Pro Tips

Faster Page Loads

See {exp:hash_browns:ajax}.

CSS Animations

If you use Animate.css or something like it, you can’t use fx_out="nofx". The CSS animation needs time to run, and nofx causes the content to immediately disappear. So leave fx_out at its default and adjust duration_out accordingly.

Support

Support is available on devot:ee.

Buy Hash Browns on Devot:ee for $16