Embedding the widget
Simple custom document queries from the Knowledge Services API can be embedded on any web page, with minimal technical knowledge, using our new web based API widget.
In the example below the widget is used to present metadata from a new IDS knowledge services data set about research on Covid-19 funded by the UK FCDO.
To use the widget you will first need to sign up for an API key.
To configure your API query you need to edit the ‘api_query‘ object used by the widget configuration script. This should at minimum contain a value for ‘_token_guid‘ the API token (your API key), and you can then add additional query parameters as per the API documentation.
In the example below the widget has been configured to query documents categorised by:
- Theme “Covid 19”, and
- Service “Governance, Conflict, Inclusion and Humanitarian Research, FCDO”
The first step is to identify the unique object_id for each parameter that you wish to include by searching the API. See the documentation for more on how to conduct API searches.
In this example, to find the Theme object_id for Covid 19 you might use this URL string:
https://api.ids.ac.uk/openapi/eldis/search/themes/short?_token_guid=f978cb1e-7039-4b6b-80ba-12d87a44e250&format=api&q=Covid
This returns the object_id: C102928
Because we wish to narrow our query to only return FCDO funded research documents on Covid-19 we need to conduct a simlar search to identify the Service Organisation object_id for FCDO:
This returns the object_id: A103064
We then use these values in the following api_query configuration:
const api_query = {
theme: 'C102928',
service: 'A103064',
_token_guid: 'f978cb1e-7039-4b6b-80ba-12d87a44e250'
};Other widget configuration parameters can be set in the ‘config‘ object, current supported options and their defaults are:
- ‘title‘:
- ‘items_per_page‘: 10
Putting this all together we get the following script to configure and insert the widget (insert this in your page):
<script type='text/javascript'>
const api_query = {
theme: 'C102928',
service: 'A103064',
_token_guid: 'f978cb1e-7039-4b6b-80ba-12d87a44e250'
};
const config = {
title: "My Embed showing Covid 19 theme docs"
};
const encode = (x) => Object.entries(x).map(
([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`
).join('&');
window.onload = function() {
let params = {
api_query: encode(api_query),
config: encode(config)
};
let iframe = document.createElement('iframe');
iframe.frameborder = "0";
iframe.loading = "lazy";
iframe.className = "resp-iframe";
iframe.src = "https://api.ids.ac.uk/site_media/frontend_widget/index.html?" + encode(params);
iframe.allowfullscreen;
document.querySelector('#openapi-widget').appendChild(iframe);
};
</script>
<div id="openapi-widget" class="resp-container"></div>Which should look like the following: