jquery-fragments documentation

You can access to the source code and downloads in
jquery-fragments in Google Code

How it works?

jquery-fragments overrides the jQuery load function,
the new function is almost the same but when the data is received the jquery-fragments plugins check if the plugin is enabled (by http headers of by settings).
If enabled the plugin make his magic if not the default jQuery load functionality is used.

What is the magic?

When the plugin is enabled instead of put the data into the target it analyzes the data a take all the first level tags.

For each first level tag it looks for a target tag or tags in the original document.
To look for the target tags the plugin uses several matching methods.

After that it applies the defined action on the tag (usually replacing the content of the tag).

And that it’s!.

Settings introduction

jquery-fragments allows a lot of configuration settings, but in the most cases you don’t need to change anything. Just add the plugin and it works!.

To change the default settings of the plugin you only need to provide the settings changes with the fragmentsSetup function.

For example to disable jquery-fragments write:


You also can change the settings in the load call:


Note the null as first parameter. This is because the orginal load function use two
parameteres params and callback so to not mix the parameters you always must provide at least one parameter.

Valid examples ares:

        alert("This is my callback function!");
        alert("This is my callback function!");


This are the default jquery-fragments settings:

Property Values/Default value Description
enabled true | false | “httpHeaders”

Enables/disables the plugin or activate the conditional activation
defaultAction “replace” | “append” | “prepend” | “delete” |

Set the default action when apply a block change. See the section Actions.
appendClass String with class name

Overrides the default action for this block to ‘append’. See the section Actions
prependClass String with class name

Overrides the default action for this block to ‘prepend’. See the section Actions
replaceClass String with class name

Overrides the default action for this block to ‘replace’. See the section Actions
deleteClass String with class name

Overrides the default action for this block to ‘delete’. See the section Actions
specialTagClass Dictionary with class/tag pairs

Allow to convert any tag to another. See the Special Tags section.
scriptTagClass String with class name

Defines the special class name to add scripts to the document. See the Adding scripts to your document section.
matchingMethods Defines or modify the matching methods used by the plugin. See the Matching Methods section.
useFullDocument true | false

Enables/disables the useFullDocument functionality,

it forces to use always all the document to place the changes not only the selector used to call $.load()

Special Tags

Some tags can’t be loaded by the jQuery $.load() method. jquery-fragments
allow you to define a tag (like a <div>) that will be converted
to another tag (like <head>).

To do this you only need to use any of the
specialTagClass setting class,
when a tag use any of this tags the matching methods
will use the tags asigned to the class instead de real tag in the load() response.

By default jquery-fragments define the class fragments-tag-head to set the target tag to the <head> tag. For example:

<div class="fragments-tag-head fragments-append">
    <link href="test.css" type="text/css" rel="stylesheet"/>

This will append the new stylesheet to the document’s head.

Feel free to define new special tag classes.

To add scripts to the documento you must use a special wat. See the Adding scripts to your document section.

Adding scripts to your document

To add <script> to the document you must use a special way:

<div class="fragments-tag-script">test.js</div>

This will add the script with src “test.js” using the $.getScript() jQuery method.

Activating the plugin with “httpHeaders”

By default the plugin is enabled with “httpHeaders” conditional activation.

This means that the plugin will only work when a special http header is
sended by the server. This header is X-jQuery-Fragments-Enabled and the value must be true or 1.

If any other value is sended or no X-jQuery-Fragments-Enabled is found the plugin don’t do anything.

This allow to the server to decide when the plugin must do their magic or not.

To activate the plugin in php for example you only need to send the header like this:

header("X-jQuery-Fragments-Enabled: true");

You can disable this functionality changing the jquery-fragments setting enabled to true. In this case the plugin will always work.


This functionality is most usefull when the useFullDocument functionality is enabled.


For each tag found by the plugin in the load() request response it executes an action over the target tag.

The available actions are:

  • replace: Replaces the content of the target tag with the new content.
  • delete: Deletes the target tag.
  • append: Append the new content to the target tag.
  • prepend: Prepend the new content to the target tag.

By default the plugin executes the default action defined in the defaultAction settings property.
But you can define custom actions in each block.

To change the default action of a block simply add any of the action classess to the block. For example:

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

This will replace the content of the #main div with New content (if the default action is “replace”).

<div id="main" class="fragments-append">New content</div>

This will add the text New content to the current content of the #main div.

<div id="main" class="fragments-delete"></div>

This will delete the #main div.

Matching Methods

The matchingMethods setting defines the methods used to look for the target tag of a block in the request response (see the How it works? section).

This setting defines a dictionary of methods. Each method must have, at least, the following properties:

  • weight: Integer, default 50. Integer with the weight of the method. The methods with less weight will be executed first.
  • enabled: true/false default true. Enables/disables the method.
  • useTag: true/false default true. Enables/disables if the method must use the tag to find the target (#id vs. div#id or .className vs div.className).
  • stopSearch: true/false default true. If true and the method found matching tags the search will stop. If false the search continues and new matching methods could add new elements to the target pool.
  • action:function(container,content,settings) default empty function. Defines the function that will look for the targets.

Matching function

The action propertie of the matching method must be a function that returns null or a jQuery object.

The function gets three params:

  • container: jQuery object for the tag used to make the $.load() call.
  • content: DOM node for what we are looking matching tags.
  • settings: Dictionary with the jquery-fragments settings.

The function must return null or a jQuery object.

Default matching methods

jquery-fragments come with some matching methods. They should be enought to the most cases and you don’t need to do anything.

Some matching methods are disabled by default. The default matching methods are:

  • byId:
    • weight:10
    • enabled:true
    • useTag:true
    • stopSearch:true
    • Description: Looks for tags with the same ID.
  • byAllClasses:
    • weight:20
    • enabled:true
    • useTag:true
    • stopSearch:true
    • Description: Looks for tags with the same classes (ignores action classes)
  • byClass:
    • weight:30
    • enabled:true
    • useTag:true
    • stopSearch:true
    • Description: Looks for tags with any of the block classes (ignores action classes)
  • byTag:
    • weight:100
    • enabled:false
    • useTag:true
    • stopSearch:true
    • Description: Looks for tags with the same tag name and without ID or classes.
  • byAllTags:
    • weight:100
    • enabled:false
    • useTag:true
    • stopSearch:true
    • Description: Looks for tags with the same tag name.
  • bySingleTag:
    • weight:100
    • enabled:true
    • useTag:true
    • stopSearch:true
    • Description: Looks for tags with the same tag name and only make a match if the tag count is one.

How to change matching methods?

Enable/disable or modify any of the properties of the matching method are pretty easy. For example to change the weight and stopSearch of the
byId method:


To add a new method simply add a new object to the matchingMethods setting, be carefull with the names to not use a existing one.

useFullDocument functionality

jquery-fragments by default only load fragments in the elements covered by the jQuery selector used. So if you have the html:

<div id="div_a">
    <div id="div_a1" class="my_class">
<div id="div_b">
    <div id="div_b1" class="my_class">

If you execute:


And the request response is:

<div class="my_class">New content</div>

Only the #div_a1 div will be updated. If you use the expression:


The #div_b1 div will be updated. And finally if you use the expression:


Both #div_a1 and #div_b1 will be updated.
The useFullDocument disables this feature. Not matters with what selector you make the load() call always affects to all
the document. So if useFullDocument setting is true the three examples before will output the same result (both divs will be updated).

So, why should we want it?

The useFullDocument functionality in combination with the ‘httpHeaders’ conditional activation allow you
to use the load() method with and without the jquery-fragments controled by the server and with no changes in the javascript code.

For example imagine the following HTML:

<div id="content">
<div id="sidebar">

And we have a jQuery listener that makes that all the link clic load the content in the #content div:

            $('a').live('click', function() {
                var href=$(this).attr("href");

Well, now we add the jquery-fragments plugin so we need to change the javascript to:

            $('a').live('click', function() {
                var href=$(this).attr("href");

And change all the responses from the server, etc. But we only need the jquery-fragments functionality in some pages or in some cases.

The solution is the combination of useFullDocument and http headers. With it we don’t need to change the javascript, it remains like:

            $('a').live('click', function() {
                var href=$(this).attr("href");

So if we don’t send the http headers the web will remain the same using the standard jQuery load().

Now in one section we want to change the sidebar, so only in this secction we send the data for the content and the sidebar and the http headers.
How we had set the useFullDocument setting to true is the same use
$.load(href); or $(“#content”).load(href); the plugins always will use all the document to look for targets.

With this combination we can use the standar jQuery load() and only when we need to update other content the jquery-fragments will be activated. Great!