Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions readme.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#djax: Dynamic pjax
# djax: Dynamic pjax

##Basic usage
## Basic usage

djax is very quick to set up, with a few markup requirements to let it work smoothly.

Expand All @@ -19,7 +19,7 @@ Then instantiate on the largest page element where you will have updating conten

Congrats, you're done! Well mostly...

##Markup
## Markup

djax will track elements with the class you pass it as a first argument. In the above example I've passed the class 'updatable,' so my markup would look something like this:

Expand All @@ -44,7 +44,7 @@ djax will track elements with the class you pass it as a first argument. In the
Your markup can be laid out however you like, and your trackable sections can be anywhere in relation to one another. It's best to keep them top level (nesting is unnecessary and unsupported,) and
there are a few requirements that allow the plugin to function properly.

###IDs
### IDs

Trackable elements must all have IDs. This is how the requested page is matched up with the current page. Only trackable elements that differ between the two pages will be loaded.
Trackable elements that do not exist on the requested page will be removed, and trackable elements that do not exist on the current page will be added. In order to support this, it
Expand All @@ -53,11 +53,11 @@ is also necessary to ensure the *parent* elements of every trackable element has
These ID's are used to add elements when necessary. If an element exists in a requested page, but not the current page, it will be inserted after the prior sibling (by ID,) or prepended to
the parent element (by ID.)

##Parameters
## Parameters

The plugin accepts only two parameters, and only one is required.

###Tracking Class
### Tracking Class

The first and only required parameter is the class you will use to identify trackable elements. If my code looks like the below sample, every dynamic element in my markup should have a class
of djaxable
Expand All @@ -68,7 +68,7 @@ of djaxable
});
</script>

###Exceptions
### Exceptions

By default djax works on any internal links, but sometimes you may want to exclude certain URLs on your site. The second parameter allows you to pass an array of URL fragments to exclude from djax
loading. This is performed with a simple Javascript 'indexOf,' so the more of the URL you provide, the more specifically your exclusions will be matched. The below example will djax any internal links
Expand All @@ -80,7 +80,7 @@ that do not contain admin, resources, or ?s= in the url.
});
</script>

##DOM Replacement Callbacks (optional)
## DOM Replacement Callbacks (optional)

Pass in a reference to a function that will handle the DOM replacement logic. The default djax replacement uses the standard jQuery `replaceWith` and does an immediate replace. For transitions, fade in/outs etc, you can control when and how the new content displays on
the page. The following example fades out the old content, and fades in the new content.
Expand All @@ -102,9 +102,9 @@ the page. The following example fades out the old content, and fades in the new
</script>


##Events
## Events

###djaxLoad
### djaxLoad

By loading new content via ajax, your visitors will only encounter $('document').ready() the first time they land on your site, and any time they manually perform a hard refresh. To help address this,
djax triggers a window level event on each partial load it performs. Here's an example of enabling pageview tracking with Google Analytics on a djax enabled site:
Expand All @@ -121,7 +121,7 @@ code to work with the response as a jQuery object
//do stuff here
});

###djaxClick
### djaxClick

This event is triggered when a djax'ed link is clicked. Use something like the code below to scroll top before loading in new content with ajax:

Expand All @@ -130,7 +130,7 @@ This event is triggered when a djax'ed link is clicked. Use something like the c
bodyelem.scrollTop(0);
});

##Live Demo
## Live Demo

djax arose out of a desire to use [pjax](https://github.com/defunkt/jquery-pjax) with complicated and varied layouts. See [here](http://brianzeligson.com/djax) for a WordPress site using a modified version
of the [bones](http://themble.com/bones/) WordPress theme. djax enabling this theme took about [28 lines of code](https://github.com/beezee/bones-responsive/commit/58aadde224d74f8aaa3266a4bd76e961f2888ada)
Expand Down