View source for JQuery HTML Updater

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:

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

=== Load the Umlaut.HtmlUpdater object ===

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

=== 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. 

<code>
  <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>
</code>

=== 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. 

<code>
  //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  );
</code>

=== 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":

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

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 [http://umlaut.rubyforge.org/svn/trunk/config/initializers/umlaut/resolve_views.rb 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. 

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



== Call the updater ==

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

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. 

<pre>
  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);
   }
  });
</pre>

=== after_update(html, count, target_obj) ===

Similar to before_update, but called after the html has been placed in the DOM on the page. Not sure what this is useful for, but in after_update you can call JQuery closest() on the html to look up in the DOM if you want. Whereas that's not available in before_update since the html has not yet been placed on the page. 

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

=== 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. 

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

== 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 ==
For the purpose of this example, to avoid confusion, we use JHU Umlaut installation URLs. You would want to replace with URLs to your own Umlaut of course. 

<pre>
<html>

<head>
  
  <script type="text/javascript" src="http://findit.library.jhu.edu/javascripts/jquery/jquery-1.4.2.min.js"></script>
  <script type="text/javascript">
     jQuery.noConflict();
  </script>
  
  <script type="text/javascript" src="http://findit.library.jhu.edu/javascripts/jquery/umlaut/update_html.js"></script>
  
  <script type="text/javascript" src="http://findit.library.jhu.edu/js_helper/loader"></script>

<script type="text/javascript">
  
jQuery(document).ready(function($) {
  var loader = new Umlaut.Loader();
  loader.load();
  
  var openurl_link = $("a.openurl_link").attr("href");
  var ctx_object_kev = openurl_link.substring( openurl_link.indexOf("?") + 1);
  var updater = new Umlaut.HtmlUpdater("http://findit.library.jhu.edu"  ,  ctx_object_kev );
  
  updater.add_section_target({ umlaut_section_id: "fulltext", selector:".my_full_text" , before_update: function(html, count) { return (count == 0); }});   
  
  
  updater.add_section_target({ umlaut_section_id: "search_inside", selector:".stuff", position: "append"  });  
  
  updater.add_section_target({ umlaut_section_id: "excerpts", selector:".stuff", position: "append"  });   
  
  updater.add_section_target({ 
    umlaut_section_id: "holding", 
    selector:".stuff", 
    position: "append",
    before_update: function(container_element) {
      container_element.find("h3").after("<h4>We love these holdings.</h4>");
    }
  });   
  
  updater.add_section_target({
      umlaut_section_id: "abstract", 
      selector:".stuff", 
      position: "append",  
      before_update: function(html, count) {
        //only show if there are hits
        return ( count == 0);
      }
   });     
  
  updater.add_section_target({ umlaut_section_id: "related_items", selector:".stuff", position: "append"  });   
  
  updater.add_section_target({ 
    umlaut_section_id: "highlighted_link", 
    selector:".only_if_content",
    after_update: function(updated_content, count) {
      if ( count > 0 ) {
        updated_content.closest(".only_if_content").show();
      }
    }
    });   
  
    updater.add_section_target({
      umlaut_section_id: "export_citation",
      selector:".stuff",
      position:"append",
      before_update: function(content, count) {
        $(content).find(".section_heading h3").text("My own crazy export options");
      }
    });
    
    updater.complete = function() { alert("Umlaut fully loaded") };
  
    updater.update();   

  });
</script>

</head>

<body>

<a class="openurl_link" href="http://app01.mse.jhu.edu:3000/resolve?sid=google&auinit=N&aulast=Chomsky&title=Aspects+of+the+Theory+of+Syntax&genre=book&isbn=0262530074&date=1965">Find It @ JH</a>

<h2>Full Text</h2>
<div class="my_full_text">
Replace me.
</div>

<h2>More Stuff</h2>
<div class="stuff">
</div>

<div class="only_if_content" style="display:none">
This will be shown only if it actually contains content. 
</div>


</body>


</html>
</pre>