VIVO Users Guide
Using VIVO
VIVO is very easy to use in your web pages and/or applications. Vivo comes packaged with prototype and scripaculous libraries this framework is built upon. VIVO needs to be installed and available somewhere on your website. This guide assumes they are installed in '/js/vivo'.
To start using vivo in your pages, you need to include a few <script> tags in <head>:
<script type="text/javascript" src="/js/vivo/prototype.js"></script> <script type="text/javascript" src="/js/vivo/scriptaculous.js"></script> <script type="text/javascript" src="/js/vivo/vivo-utils.js"></script> <script type="text/javascript" src="/js/vivo/vivo-tools.js"></script> <script type="text/javascript" src="/globals/js/vivo/vivo.js"></script>
The vivo.js script adds an onload handler to initialize vivo when the document has loaded. All VIVO tools found in the DOM will be initialized.
See the VIVO Tools page for detailed information and examples on how to use VIVO tools.
Speeding up initialization
The default VIVO initialization manually iterates through the entire DOM, inspecting each element registered vivo tools. For large documents (e.g. containing a table with 1000 rows) this can be horribly inefficient. This appears to be more of an issue with IE than with Mozilla/Gecko-based browsers. In my tests, IE 6.0 could take up to 30 seconds to render a specific large document, all the while being completely unresponsive. While still noticeable in Mozilla (linux), this DOM parsing was a bit faster.
Initialization time can be drastically reduced (for large documents) if an XPath query is used instead of DOM iteration. To do this, the content type of the document needs to change from text/html to application/xhtml+xml, application/xml or text/xml. I haven't tested the xml types, and application/xhtml+xml is only supported in gecko-based browsers. XPath queries with namespaces only work in xml documents. So to get this working:
- Set the content-type HTTP header to application/xhtml+xml
- Set the <meta http-equiv="content-type" content="application/xhtml+xml;charset=?" />
Both of these need to be properly set. The HTTP Header forces xml parsing in Mozilla. The vivo initialization checks the meta tag for the content type, as there is no way to inspect the HTTP headers of the current document in javascript.
A good way to determine whether to send application/xhtml+xml is to use content negotiation. Inspect the 'Accept' HTTP header, looking specifically for application/xhtml+xml.
Defining the vivo namespace
Since the pages are now served as validated xml documents, the vivo namespace needs to be included in the <html> tag. So, the following should be added so it looks like this:
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:vivo="http://www.bethel.edu/namespaces/vivo">
This defines the default names (xhtml) and the vivo namespace. XPath will not work without this, because it will be unable to resolve the namespaces.
Basic, Useful API
If your code causes new VIVO tools to be added to the DOM, you'll need to re-parse that section of the DOM. A few tools do this automatically. If you find that this doesn't happen, in your code you can call this function:
VIVO.apply(dom)
If the dom parameter is null, the entire document is re-parsed.
