200
edits
Changes
no edit summary
[[Category:Umlaut]] =WARNING: This is Outdated Documentation!!!!= '''THIS IS OUTDATED DOCUMENTATION''' See new Umlaut documentation at http://github.com/team-umlaut/umlaut/wiki--------- 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 divspage at DOM locations you specify, and keep polling Umlaut for new results, continuing to re-update your divs page 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, on the Umlaut resolver menu page.
<b>NOTE</b>: The intended use case at the moment is a "single item" or "item detail" page. You may think "Gee, I want to embed umlaut content for every item on a 10-item results page!" Handling this case isn't fully fleshed out yet, in part becuase it might put unreasonable load on an Umlaut server. But I have it in mind, and we may be able to get there, let jrochkind know if you demand it.
== Requirements ==
You need to have the ability to add custom javascript html <script> tags referencing external js files 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. If an OpenURL link is already on your HTML somewhere, Javascript can easily pull the 'context object' out of this (see example).
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. jQuery 1.4 is highly recommended, although jQuery 1.3 will likely work too if you already depend on that in your application.
== Step by Step ==
=== Load JQuery ===
You can load JQuery from your installed Umlaut if you want. This is not neccesary if your app already includes JQuery. It's probably best to load it in "no conflict" mode:
<code>
</code>
=== Optionally, load Umlaut Javascript UI 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.
<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();
=== 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 [[#Complete Example|example ]] below.
<code>
<code>
updater.add_section_target({ umlaut_section_id: "fulltext", selector:"#my_full_text_div" });
</code>
<code>
updater.add_section_target({ umlaut_section_id: "highlighted_links", selector: ".sidebar", position: "append" });
</code>
=== Call the updater ===
=== Section Target callbacks ===
==== before_update(html, count, target_obj) ====
<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 In after_update (unlike before_update) you can call JQuery closest() on the html to look up in the DOM if you want. Whereas that's not This could be used for instance to show a previously hidden parent element only if there are umlaut items 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) {
if (count !=0 ) { $(html).closest("div.something").something...show(); }
}
});
==== complete(updater_obj) ====
updater.complete = function() { alert("all content has been fetched!"); }
== Complete Example ==
For clarity, this example has some javascript source inline in a <script> tag, the code that specifies how content is to be loaded. That javascript code could of course instead be in an external js file referenced by a <script src=>.
<pre>
<script type="text/javascript">
jQuery(document).ready(function($) {
var loader = new Umlaut.Loader();
loader.load();
/* pull openurl link out of the DOM, take umlaut base and context object
out of it */
var openurl_link = $("a.openurl_link").attr("href");
var ctx_object_kev = openurl_link.substring( openurl_link.indexOf("?") + 1);
var umlaut_base = openurl_link.substring(0, openurl_link.indexOf("/resolve")); var updater = new Umlaut.HtmlUpdater($UMLAUT_BASE umlaut_base , ctx_object_kev );
updater.add_section_target({ umlaut_section_id: "fulltext", selector:".my_full_text" , // only show ourself if we have umlaut hits, false return from // before_update stops update. 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({
position: "append",
before_update: function(container_element) {
//insert some content into the umlaut-delivered html
//before it is placed on the page
container_element.find("h3").after("<h4>We love these holdings.</h4>");
}
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({
selector:".only_if_content",
after_update: function(updated_content, count) {
//show the ancestor DOM element with certain class, only //if there are umlaut hits if ( count > != 0 ) {
updated_content.closest(".only_if_content").show();
}
<body>
<a class="openurl_link" href="http://app01.mse.jhu.edu:3000$UMLAUT_BASE/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>
