Widget HowTo

This technical guide will help you getting started with the implementation of the Metagrid widget in your pages.

In a nutshell, the Metagrid widget is actually a small piece of javascript, built on top of jQuery, which runs within the page (i.e. every entity detail page) and issues an asynchronous (AJAX) request to the Metagrid server in order to know which concordances exist for the entity represented on the current page. It will then parse the response (usually in JSON) and create a new element (the “widget”) within the existing page DOM.

Please note that the AJAX-based approach proposed here is not the only way of consuming data from Metagrid. In some circumstances, other approaches could be more suitable to your situation, pending the acceptation of the Code of conduct. Please contact the Metagrid team if you need help.

The proposed widget implementation is based on the jQuery javascript library. The first step is therefore to make sure that the jQuery code is included in your pages.

The actual javascript code for the widget can reside in a separate javascript file (recommended method) or be embedded within the page’s html in a <script> tag.

Because the widget should appear as soon as possible when your page is loaded, the widget code should be written inside a callback.

$(document).ready(function() { 

There are basically three steps in the life cycle of the widget:

  1. know which entity it has to ask Metagrid for
  2. issue a request to Metagrid
  3. process the response, build and display the widget

It is not mandatory to have one Widget per page. In some situations, for instance when you want to display Metagrid information for a collection of entities at the same time (vs. on a detail page of a single entity), you could use a different approach (pending the respect of the Code of conduct).


1. Collecting information about the entity

The first step is to collect some minimal information about the entity. In most cases, this boils down to knowing your “slug” as a provider (always the same for a given widget) the entity type (i.e. “person”) and the unique identifier (please refer to the Best practices page for more information). Optional information includes the desired language, the format (defaults to json) and a name for the jsonp callback (automatically set by jQuery).

For a complete description of the Metagrid API, please refer to https://api.metagrid.ch/doc.

How the entity information is collected depends on how your page is structured. As this can vary a lot from one site to another, there isn’t a universal strategy that will work in every case. In the following sections, we suggest possible solutions for common scenarios.

Extracting information from the URL

If your site follows the RESTful principles, chances are that most of the information needed by the widget is already available in the URL. In this case, you could

We advise to use JSONP technique in order to prevent any security-related issues with cross-domain requests. jQuery provides a very convenient means of issuing JSONP requests, via the getJSON method.

In this example, we try to extract the numeric unique identifier from the URL:

var personId = window.location.href.match(/\/pub\/person\/([0-9]+)$/i);
 if(personId) { 
// personId can now be used for building the Metagrid request 

Extracting information from the DOM

More often than not, the information is available somewhere in the page, in a structured or unstructured way. Of course it’s better, and easier, if the information is structured. One possible approach is to store this data in html5 “data-” attributes. For instance, you could add a data-unique-identifier attribute to any html element of the page, and set its value to the actual id:

<div data-element-kind="P" data-element-id="150" id="metagrid-widget"></div>

Retrieveng this data is then rather straighforward:

if($('#metagrid-widget').length) {                  
         var entityKind = $('#metagrid-widget').attr("data-element-kind");
         var entityId = $('#metagrid-widget').attr("data-element-id");  

In other cases, especially when your margin for modifying the page html  is tight, it might be necessary to extract the information in a more brutal (and inefficient) way, i.e. using regular expressions or by traversing the page’s DOM using jQuery’s methods.

2. Issue a request to Metagrid

Once all information has been collected, it’s time to use it and build the actual request. Be sure to build your request as per the API specification.

The Metagrid widget API endpoint (just like the whole API, for that matter) is available both over plain http, or over a secure HTTPS protocol. We strongly encourage you to always use the latter method. If your page is already served over HTTPS, then you are required to use Metagrid over HTTPS, or your browser will simply refuse to run the widget.

Please note that, in order to manage the same origin policy, we always include in the response a header ‘Access-Control-Allow-Origin’ with a value of ‘*’.

3. process the response, build and display the widget

The Metagrid API conforms to the RESTful architecture principles. As a consequence of this, exceptions are expressed using standard HTTP status codes. The code 404 Not found is particularly meaningful. For some projects, a lot of requests to Metagrid will end up with a 404 response, because no concordance was found for the given entity. The jQuery getJSON method will detect the response status code for us, and the callback will only be invoked if a valid response code (200) is returned.

The response contains a key-value array of ressources, where the key is the name of the provider of the ressource, and the value is the actual (complete and ready to use) URL of the ressource.

The last thing to do is to inject the actual HTML code of the widget into the page. Once again, several approaches exist, depending on each project’s peculiarities. The easiest way is to define an empty <div> or <span> element with a given id (for instance “metagrid-widget”) on your page template, then inject the widget code into it when the widget code is executed. If you can’t define an empty element, you can still use jQuery to traverse the DOM to an existing element near the location where you would like the widget to be displayed, and inject the widget html using jQuery methods such as insertAfter().

Also, because every site is different, with its own layout and identity, partners of Metagrid are not set on a mandatory layout for the widget. On the other hand, the coding effort for creating a widget is not enormous (to say the least), therefore there is no need for imposing a standard one.

Metagrid only asks his partners to fully conform to the Code of conduct, which dictates very few rules that you have to follow when you implement your widget.

The metagrid application enables every project to define which links are to be shown in its widget, and in which order they should be displayed. Although it is technically possible to modify the Metagrid response on the client side, we ask you to conform to what the Code of conduct dictates in this respect.

The code below shows a possible implementation of the widget (here for the Dodis website):

            $.appendString = "";
            $.getJSON("https://api.metagrid.ch/widget/dds/" + urlFragment + "/"+
                  entityId +'.json?lang=de&jsoncallback=?', function(data){
                      $.each(data[0], function(index, value) {
                          $.appendString += '<span style="margin-left: 1em;"><a target="_blank" href="' + value + '">' + index + '</a></span>';
                      if ($.appendString != "") {
                          $('#metagrid-widget').html('<div class="row"><div class="span8"><div class="blue-box"><b>Links from <a style="" href="http://www.metagrid.ch" target="_blank">Metagrid</a>:</b>'+$.appendString+'</div></div></div>');