-
Notifications
You must be signed in to change notification settings - Fork 24
HTML Snippet API Response
While Umlaut has a full XML/JSON Data API Response, for the common use case of embedding Umlaut content on an external page, it's just too much work to use the full data api.
This HTML Snippet API Response is meant for when you want Umlaut to generate the HTML, but you want to embed that HTML on an external page. The API will deliver sections of generated HTML, that you can include elsewhere.
If you plan to include it via javascript, you will likely find it even more convenient and less work to use the Umlaut JQuery Content Utility, saving you even more work. The Content Utility javascript helper uses the API behind the scenes.
Supplied via the resolve/partial_html_sections actions. Instead of accessing the ordinary resolver base URL, you replace resolve? in your query with resolve/partial_html_sections, eg http://umlaut.university.edu/resolve/partial_html_sections? . You send the OpenURL context object the same as you would for an ordinary resolve action, in URL or POST XML, etc.
By default, the API returns XML. To return json instead, include:
¨aut.response_format=json
To return jsonp, wrapped in a javascript procedure call:
¨aut.response_format=jsonp¨aut.jsonp=desiredJavascriptFunctionName
When accessing Umlaut over an API, it's important to realize that the initial response from Umlaut may not include all Umlaut information.
Umlaut continues to run services in the background that can generate responses and enhance metadata. <complete> will contain 'true' or 'false' depending on whether background services are still executing. Further elements in the response provide information on what is still executing, and how to retrieve further information.
An <in_progress> block will be present if and only if <complete> is false. It provides information on completion status, and how to refresh the response for more information prepared in the background. For more information, see the documentation in Data API Response, the block is the same here.
Among other things, it includes a URL you should use to call back for a more complete response as Umlaut's resolution progresses.
What you really want is contained in 0 or more html_section blocks. Each one contains some generated HTML, along with some metadata about it. The id attribute of <html_section> is a unique id for that section.
What sections exist is configured in Umlaut in the resolve_sections configuration of sections. The div_id key for each section will be the id of the html_section in the snippet response. A resolve_section configured with partial_html_api=false will not be included in the snippet response.
Inside an html_section in the response there is a bit of metadata for you:
-
<included_services>What ServiceTypeValues are included in this html section. This specifies what type of data is in this block. For a list of possible ServiceTypeValues in a default Umlaut configuration, see service_type_values.yml in umlaut source.
-
<service_load_complete>trueorfalse. False if this html_section might change as more background services run, true if this html_section is completely finished. -
<response_count>How many Umlaut response objects were used to generate this block? Can be useful if you want to do something different with 0 (no content) vs. non-0 (content).
-
<html_content>The actual html content. It is standardly XML-escaped in XML, or json-escaped in json. Whatever software you are using to read the API response will need to un-escape it when reading from XML or JSON to get an HTML literal suitable for embedding in a page.