Widgets

EarthPortal widgets: how to use them

EarthPortal widgets are snippets of HTML or JavaScript code that users can embed in their website/web form to use the EarthPortal functionalities. Using EarthPortal widgets is just one of the ways in which users can use EarthPortal technologies on your website/application. Developers can add any EarthPortal widget to their HTML page or web form by following these steps:

find the semantic artefact that users are interested in by browsing the list of EarthPortal semantic artefacts;
click on the semantic artefact name to get to the page with Details for that semantic artefact;
in the semantic artefact details page, go to the “Widgets” tab;
select the widget that want to use;
click the button below the widget to get usage instructions.

Developers can add a search box to their website that will allow users to search a specific EarthPortal semantic artefact. When the user selects the term of interest (with the help of the auto-complete feature), she/he can move directly to the EarthPortal summary page of the corresponding concept. To add a search widget to a HTML page that allows users to search for a specific semantic artefact: download the quick_jump.js file, put it on your server, copy the code below and paste it to your HTML page:

 <div id="bp_quick_jump"></div>
 <script type="text/javascript">
   var BP_ontology_id = "ACRONYM";
 </div>
 <script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>

Note: To use Quick Jump across multiple semantic artefacts:

enter a comma-separated list of semantic artefact ids: var BP_ontology_id = “ACRONYM, ACRONYM2”, or
you can set the variable to ‘all’ to search all semantic artefacts in EarthPortal: var BP_ontology_id = “all”.

Update the copied code by changing the path to the quick_jump.js file that has to point to the server location where you put the HTML file. For example, if you put the quick_jump.js file in the same directory as your HTML file, this is the code that you have to use:

<script type="text/javascript">
 var BP_ontology_id = "ACRONYM";
 </div>
<script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>

to limit the term search to a particular branch of a semantic artefact, include the following JavaScript in your page (remember to replace the conceptid with the ID for the term that you want to use as the root of your branch): var BP_search_branch = “{class_id}”; to display definitions with the list of terms that are returned, include the following JavaScript in your page: var BP_include_definitions = true;

Term-selection field on a form Developers can add a text field to their web form that will allow users to enter a term from a controlled vocabulary (e.g., terms from a single )

What does the term-selection field do? Auto-complete the text field so that user don’t need to type the whole term The controlled vocabulary provides consistency in the manner in which different users use a specific term When a new version of your controlled vocabulary becomes available in EarthPortal, the widget will automatically use that new version. To add a field to a web form that allows users to retrieve a term from the semantic artefact of interest, do the following:

download the form_complete.js file and put it on your server;
in the header of the page where want the field, include the form_complete.js file;
in the form, specify the field class in the following format: bp_form_complete-{semantic_resource_acronym_list}-{value}
- Note: In addition to single ontology IDs, you can use a list: bp_form_complete-FISHTRAITS, ENVTHES-uri OR you can use ‘all’ to search across all EarthPortal semantic artefact: bp_form_complete-all-uri
Developers can use the following parameters to select which value will be placed into the user-visible input field:
- uri: the complete URI of the term;
- shortid: the short ID of the term, as used in EarthPortal;
- name: the preferred name of the term;

Auto-generated hidden form elements In addition to the input element you defined, there are four hidden form elements that are automatically created and set when users select a term from the list. For example, if you create a field with this code:

<input type="text" name="a" class="bp_form_complete-all-uri" size="100"/> 
The 'name' attribute is used to create the four following fields (note how the 'a' from the name attribute is appended to the id attribute:
 <input type="hidden" id="a_EarthPortal_preferred_name">
 <input type="hidden" id="a_EarthPortal_concept_id">
 <input type="hidden" id="a_EarthPortal_ontology_id">
 <input type="hidden" id="a_EarthPortal_full_id">

Optional attributes

Include term definitions Use data-bp_include_definitions="true" to display definitions with the list of terms that are returned.
Limit search to terms below a root term. Use data-bp_search_branch=”{class_id}”, replacing {class_id} with the class ID for the term to use as the branch root.

Object types:

Search ‘class’ and ‘property’ objects. Use data-bp_objecttypes=”class,property”.
Search only ‘property’ objects. Use data-bp_objecttypes=”property”.
Search ‘class’ and ‘individual’ objects. Use data-bp_objecttypes=”class,individual”.
Search only ‘individual’ objects. Use data-bp_objecttypes=”individual”.

Developers can put a widget on their website that displays the semantic artefact tree, or a part of it, with the same result obtained in the “Visualize” tab in EarthPortal.

Description The semantic artefact tree widget is an embeddable Flex application that allows users to interact with a tree to browse semantic artefacts. The widget can be configured to display a list of all the EcoPortal semantic artefacts, allowing users to select which one to view, or can be set to view a particular semantic artefact. Moreover, there are several JavaScript helper functions for the widget, allowing it to be used as a fully functional component in other applications.

Location To use the tree widget, you have to add the following files:

http:///widgets/jquery.ncbo.tree.css
http:///widgets/jquery.ncbo.tree-2.0.2.js

or the minified versions:

http:///widgets/minified/jquery.ncbo.tree.min.css
http:///widgets/minified/jquery.ncbo.tree-2.0.2.min.js

Setup jQuery is required in order to use the tree widget. If jQuery is not still in your project, you have to include it as follows:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>

Then, you have to create a div element to store the tree:

<div id="tree"></div>

initialise the tree with the following JavaScript code:

var tree = $("#tree").NCBOTree({apikey: "YOUR_API_KEY",ontology: "ACRONYM"});

The div you created will contain a tree showing the roots of the ACRONYM semantic artefact. Additional setup options include:

autoclose: to close other branches of the tree when expanding a new one;
treeClass: the class to identify the tree;
autocompleteClass: the class to identify the autocomplete (search) input;
width: the width of the tree;
startingClass: to start with this class selected (and expanded to) in the tree;
startingRoot: to start with this class as the only root displayed in the tree. This allows you to display a sub-tree or branch of your choosing;
ncboAPIURL: to use a different NCBO REST instance (not normally used);
ncboUIURL: to use a different NCBO UI instance (not normally used).

Callbacks and event triggers Developers can interact programmatically with the tree by using JavaScript and jQuery. Callbacks can be passed when setting up the tree:

var tree = $("#tree").NCBOTree({apikey: "YOUR_API_KEY",ontology: "ACRONYM", afterSelect: function(event, classId, prefLabel, selectedNode){console.log(classId);}});

The available callbacks with their arguments are:

beforeExpand, arg: expandedNode
afterExpand, arg: expandedNode
afterExpandError, arg: expandedNode
afterSelect, arg: classId, prefLabel, selectedNode
afterJumpToClass, arg: classId

It’s possible to listen to these callbacks as jQuery events: tree.on(“afterSelect”, function(event, classId, prefLabel, selectedNode){console.log(classId);}

The events with their arguments are:

beforeExpand, arg: event,expandedNode
afterExpand, arg: event,expandedNode
afterExpandError, arg: event,expandedNode
afterSelect, arg: event,classId, prefLabel, selectedNode
afterJumpToClass, arg: event,classId

Public methods There are a variety of methods to call on the object that is returned when calling NCBOTree(). They can be used to get information about the state of the tree or to programmatically interact with it.

var tree = $("#tree").data("NCBOTree");
OR
var tree = $("#tree")[0].NCBOTree;
OR
var tree = document.getElementById("tree").NCBOTree;

Once you have the tree instance, you can call the following methods:

tree.selectedClass(): returns an object that represents the currently-selected class. The object includes attributes for ID, prefLabel, and URL. URL is the REST location of the class, and performing an HTTP GET on that URL will provide a JSON representation of the class;
tree.selectClass(classId): activates the class in the tree with the matching URI (classId). This will only work if the class is already visible;
tree.jumpToClass(classId): replaces the current tree with a version that is expanded with a path from the root to the given class. This method is triggered when selecting a class from the search field. The provided class will be selected in the tree when the tree returns;
tree.changeOntology(ontologyAcronym): replaces the current tree with the roots from the given semantic artefact.

semantic artefact visualisation widget Developers can put a widget on their website that shows semantic artefact of interest, or a part of it, and obtain the same result as in the “Visualize” tab in EarthPortal. To add a widget visualising your semantic artefact in your HTML page, copy the code from the Widget page of your semantic artefact of interest. Here is an example:

<iframe src="http:///widgets/visualization/?ontology=ACRONYM&class=SELECT_CLASS&apikey=YOUR_API_KEY"frameborder="0"></iframe>

EarthPortal widgets: how to use them

semantic artefact search widget

EarthPortal Ontology Tree Widget