Widget framework

The IMu Widget Framework is a set of components which can be added to an HTML page to provide ways to browse, search and display information from EMu.

IMu widgets can be added to any HTML page. The page which includes the widgets may be:

  • A static html file.
  • Created using a templating engine such as PHP, JSP or ASP.
  • Generated by a CMS such as Joomla!, Drupal, Umbrarco or one of many other CMSes.

IMu widgets are created using JavaScript. The components themselves are based on the jQuery library. Before using the IMu Widget Framework it is recommended that you have some knowledge of JavaScript and jQuery. Tutorials are available at the excellent w3schools.com web site for both JavaScript and jQuery.

The widgets are designed to be both portable and adaptable. This means that they operate on a wide variety of platforms and browsers and can modify their appearance and behaviour based on the type of browser being used.

Tip: For a full list of environments in which the widgets have been tested see Compatibility.

What is a widget?

A widget is an HTML element (frequently just a plain div) whose content is managed by JavaScript. The key feature of a widget is that its content is created independently of the page it is part of.

Many web sites use widgets to embed advertising in their pages.

The IMu Widget Framework provides a set JavaScript components which can take control of one or more HTML elements in a page (i.e. transform these elements into widgets) and use them to display data from EMu.

How do widgets work?

When a web page is loaded by a browser, the browser runs any JavaScript which is included in the page.

In a page using IMu widgets small pieces of JavaScript identify which elements are to be used and what kind of widgets they should be converted into.

Once the widget code takes control of an element it works out how to display information in the element. Many widgets operate by requesting information from a server using AJAX requests and then creating HTML to display the information inside the original element.

Here is a simple example which illustrates how IMu widgets are added to a page. This example does not go into all the details of how to setup an IMu widget. The details are covered elsewhere in this documentation.

In this example we will add an IMu widget to a page which displays an EMu record. The displayed record will include links which allows the user to browse to other records. The widget acts as a simple EMu record browser.

To use IMu widgets we must first include the IMu Widget library. This requires a single JavaScript file to be added to the page's <head> section:

<script type="text/javascript" src=".../imu.js"></script>

Note: The ... in the src attribute must actually be the path to the imu.js file relative to the page itself.

Note: This file includes the source-code for several third-party libraries which IMu depends on. The most important of these is the jQuery library. This means that there is no need for the page to load jQuery separately.

Each IMu widget takes control of an existing HTML element in the page. To add the record browser we need to create an empty element in the page which IMu can use to show the EMu records. The empty element is typically a <div>. So that we can refer to the element later in some JavaScript, we give the element an id:

<div id="example-widget"></div>

To control how much space the element will occupy on the page we set its height. We are not setting the element's width which means the element will grow to the width of its parent - in this case the page's <body> element. The height can be set inline on the element:

<div id="example-widget" style="height:400px"></div>

or, in a more complete example, in a css stylesheet either included inline in the page header or in a separate css file:

#example-widget
{
   height: 400px;
}

The last (and most important) step is to tell the Widget Framework to take control of the element and to use it to display EMu records. To do this we write a small piece of JavaScript. This JavaScript can be defined in the <head> section after the IMu JavaScript library has been loaded or in the <body> section. In this simple example we will put the code in the <body> straight after the element definition:

<div id="example-widget" style="height:400px"></div>
<script type="text/javascript">
IMu.ready(function()
{
   $('#example-widget').IMu('record-browser');
});
</script>

The code is relatively straightforward. The IMu.ready method waits for IMu to load any other CSS stylesheets or JavaScript files and then calls the anonymous function which is passed as an argument. This is very similar to jQuery's .ready method (in fact IMu.ready calls jQuery.ready).

The single line of code in the anonymous function uses standard jQuery to find the HTML element whose id is example-widget:

$('#example-widget')

and then calls the IMu jQuery plugin, passing the name of the widget (record-browser) we want to display in the that element:

.IMu('record-browser')

It is this code which takes control of the element and is responsible for displaying the EMu record(s).

All IMu widgets are used in a similar way to this.

Here is code for a complete HTML page which includes the record-browser widget:

<html>

   <head>

      <title>Simple IMu Record Browser</title>

      <script type="text/javascript" src="imu/imu.php"></script>

      <style>

      #example-widget

      {

         border: 1px solid black;

         height: 400px;

      }

      </style>

   </head>

   <body>

      <p>Below is a div which contains an IMu record-browser widget</p>

      <div id="example-widget"/>

      <script type="text/javascript">

         IMu.ready(function()

         {

            $('#example-widget').IMu('record-browser');

         });

      </script>

   </body>

</html>

The previous example was very simple but did not give much idea of how the widget framework actually works.

Many web technologies which deliver dynamic data to the web use templating engines (such as PHP, ASP.Net, JSP and Ruby on Rails) to generate entire HTML pages containing the required data. These systems often use small amounts of JavaScript to add some more dynamic functionality to the page generated by the templating engine. This is not the approach taken by the IMu Widget Framework.

A key goal of the framework is to allow dynamic data from EMu to be displayed in pages which come from other sources, such as Content Management Systems (CMSes). This requirement makes it impossible to use conventional templating engines to create entire pages. Instead, the IMu Widget Framework uses JavaScript to actually build the in-page components (widgets) after the page has been delivered to the browser. The widgets then use AJAX (Asynchronous JavaScript and XML) to fetch data from EMu and display it.

JavaScript

Because of the way the widgets are constructed, browsers displaying web pages which include IMu widgets must have JavaScript enabled. JavaScript cannot be treated as an optional mechanism used only to provide some additional "bells and whistles" functionality. Instead JavaScript is a fundamental cornerstone of the system. If an organization prohibits the use of JavaScript in its web pages then IMu widgets cannot be used.

Note: Fortunately, it is becoming increasingly rare for sites to mandate that their web pages be able to operate without JavaScript.

This means that, unlike in pages generated by templating engines, a large amount of what happens occurs in the browser. This is possibly less efficient than the technique used by templating engines but it provides far greater flexibility. Pages ranging from simple static HTML files to complex pages generated from a CMS can have IMu widgets added to them.

Loading IMu

Given the framework's the reliance on JavaScript it is not surprising that all pages which want to use IMu widgets must first load an IMu JavaScript file. This is done using a standard HTML <script> element in the <head> section of the HTML page:

<script type="text/javascript" src="imu/imu.js"></script>

This is often the only IMu-related entry that is required in the <head> section of the page.

Locating the imu.js File

The imu.js file is part of an imu directory which must be installed on the web server machine. The imu directory must be accessible by the web server.

Read on