Difference between revisions of "JQuery HTML Updater"

Revision as of 16:03, 6 May 2010

If you want to include Umlaut-generated HTML directly on a third party page via javascript, there is a Javascript helper object to make that very easy. This helper uses the Umlaut partial html API, but does everything for you. The helper will update your divs, and keep polling Umlaut for new results, continuing to re-update your divs until Umlaut is finished.

The Javascript helper object relies on JQuery.

This Javascript helper is actually also used internally by Umlaut to load background results as they come in.

Requirements

You need to have the ability to add custom javascript to the page you'd like to Embed Umlaut content in. You also need to be able to somehow make an OpenURL Context Object representing the thing you'd like to load Umlaut content for, and pass this to the Javascript.

You need to be willing to load the JQuery library on your page, although it can be loaded in "no conflict" mode if you also need Prototype or another JS library.

Step by Step

In the following examples, $UMLAUT_BASE stands for the base URL you have installed Umlaut at, for instance http://findit.library.jhu.edu for JHU.

Load JQuery

You can load JQuery from your installed Umlaut if you want. It's probably best to load it in "no conflict" mode:

 <script type="text/javascript" src="$UMLAUT_BASE/javascripts/jquery/jquery-1.4.2.min.js"></script>
 <script type="text/javascript">
     jQuery.noConflict();
 </script>

Load the Umlaut.HtmlUpdater object

 <script type="text/javascript" src="$UMLAUT_BASEjavascripts/jquery/umlaut/update_html.js"></script>

Optionally, load Umlaut Javascript Behaviors

HTML loaded in by the HtmlUpdater may include javascript behaviors when displayed in Umlaut, such as expand/contract toggles. You can choose to load JS files providing those behaviors into your local app. If you don't, certain links will degrade to linking out to Umlaut, but everything should still work fine.

Currently, expand/contract toggles are actually the only js behavior supported on external pages; dialog boxes will neccesarily degrade to links out to your Umlaut app.

 <script type="text/javascript" src="http://app01.mse.jhu.edu:3000/js_helper/loader"></script>
 <script type="text/javascript">
   jQuery(document).ready(function($) {
     var loader = new Umlaut.Loader();
     loader.load();
   });
 </script>

Instantiate an HtmlUpdater

You need to instantiate an Umlaut.HtmlUpdater, and tell it your Umlaut base url, and a context object key-encoded-value query parameter string. If you already have an OpenURL link on the page, it may be convenient to pull the context object out of that, see example below.

 //inside a jQuery ready()
 var ctx = "sid=google&auinit=N&aulast=Chomsky&title=Aspects+of+the+Theory+of+Syntax&genre=book&isbn=0262530074&date=1965"
 var updater = new Umlaut.HtmlUpdater($UMLAUT_BASE,  ctx  );

Configure HtmlUpdater

You use the add_section_target() method on your updater to tell it which blocks of Umlaut content you'd like to put where on your page. The argument to add_section_target() is a JS object containing options.

In the simplest case, you can simply supply an umlaut section in the "umlaut_section_id" option, and the ID of a div you'd like to place the content in on your page in "selector":

 updater.add_section_target({ umlaut_section_id: "fulltext", selector:"#my_full_text_div"  });

The exact umlaut sections available may depend on your Umlaut configuration. To see the sections in a default Umlaut installation, see: AppConfig::Base.bg_update_map in resolve_views in svn

The selector argument can actually be any JQuery selector. By default, the first item on the page that matches this selector will have it's content entirely replaced by the specified umlaut section. However, you can also supply a "position" argument of "before", "after", "append", or "prepend", and the umlaut section will instead be inserted before or after the element matching your selector, or prepended or appended to the element's children.

 updater.add_section_target({ umlaut_section_id: "highlighted_links", selector: ".sidebar", position: "append"});

Call the updater

 //in a JQuery ready block
 updater.update();

The updater will now make a call to Umlaut, grab the content from Umlaut, and do what you've told it to do with it. Additionally, it will keep polling Umlaut until all content is available. How often it polls is configured by application config 'poll_wait_seconds', which defaults to 4 seconds.

Callbacks

When configuring the HtmlUpdate object, there are several callbacks you can supply functions to, for your own code to be called.

Section Target callbacks

Additonally, you can specify some javascript callback functions to add_section_target, if desired. These can be useful for modifying the HTML returned by Umlaut before it's placed on your page, or modifying other parts of your page upon receiving content.

before_update(html, count, target_obj)

Called before the Umlaut html is actually on the page, you can use it to modify the HTML before it gets added to the page. "count" is a JS integer count of how many items are included in the section; sometimes you may wish to hide the whole section from the page if there are 0 items; returning "false" from before_update will cause the HtmlUpdater to *not* place the block on the page.

The "target_obj" is an HtmlUpdate internal object that's probably not too useful unless you want to look at the source, but can be used for some complex things.

 updater.add_section_target({ umlaut_section_id: "highlighted_links", selector: ".sidebar", position: "append", before_update: function(html, count) {
    $(html).find(".section_heading h3").hide();

    return (count > 0);
  }
 });

  updater.add_section_target({umlaut_section_id: "fulltext", selector:"#my_fulltext", 
           after_update: function(html, count) {
              $(html).closest("div.something").something...
           }
  });

complete(target_obj)

Complete on a given section is called after there are no more updates for that section. Currently, the HtmlUpdate isn't smart enough to know that until the entire Umlaut update is done however, so it'll be called at the same time as complete() on the updater as a whole. This may change in the future.

  updater.add_section_target({umlaut_section_id: "fulltext", selector:"#my_fulltext", 
                              complete: function() { alert("fulltext done!") }});

HtmlUpdate callbacks

Currently just one, for when the Umlaut update is complete (all content has been fetched).

complete(updater_obj)

updater.complete = function() {

 alert("all content has been fetched!");

}

Complete Example