Latest revision as of 17:17, 1 February 2016

NCBO widgets are the HTML or Javascript code that you can put on your Web site or Web form to use BioPortal functionality there. Using NCBO Widgets is just one of the ways in which you can use the NCBO technology directly on your Web site or in your application.

Types of NCBO Widgets and use cases

Term-selection field on a form: You can add a text field to your Web form that will let users enter a term from a controlled vocabulary (e.g., terms from a single ontology)
- Example use case: Suppose you are running a tissue microarray database and users upload sample descriptions to your database using a web form. There is usually a field for the user to enter the diagnosis for the tissue sample that she is entering. Usually, this field is a text-box or a drop down menu populated with a list of controlled terms. The free text-box is prone to errors, the drop-down gets too unwieldy with large terminologies. Using the NCBO term-selection widget to have users easily select a term from an ontology or controlled vocabulary (such as the NCI Thesaurus) to fill in the field. For example, when the user starts typing "cutaneous me", the term "cutaneous melanoma" pops up.
- What does the term-selection field get you:
  - Look-ahead so that you don't need to type the whole term
  - Controlled vocabulary provides consistency of the way different users use the term (If you want to put "Malignant melanoma", it will always be the same term from NCIT, regardless of how a user started typing it
  - When a new version of your controlled vocabulary becomes available in BioPortal, the widget will automatically use that new version.
Ontology search widget: You can add to your Web site a search box that searches a specific BioPortal ontology. When the user selects the term of interest (with the help of the look-ahead feature), he can jump to the BioPortal page for the corresponding concept in BioPortal.
Ontology visualization widget: You can put a widget on your Web site that visualizes your entire ontology of interest, or some part of it, as on the "Visualize" tab in BioPortal.
NCBO Ontology Tree Widget: You can put a widget on your Web site that displays the ontology tree, or some part of it, as on the "Visualize" tab in BioPortal.

How to use NCBO Widgets

The easiest way to add any NCBO widget to your HTML page or Web form is by following these steps:

Find your ontology of interest in the list of BioPortal ontologies (e.g., NCI Thesaurus)
Click on the ontology name to get to the page with Details for that ontology (e.g., the Details for NCI Thesaurus)
On the Ontology Details page, go to Ontology Widgets tab
Select the widget you want
Click the button below the widgets to get instructions for the specific widget

Term-selection field on a form

To add a field to your form that lets the user fetch a term from your ontology of interest, do the following:

Download the form_complete.js file and put it on your server
In the header for the page where you want the form field, include the form_complete.js file
On your form, for the fields where you want to use the term-selection widget, specify the field's class in the following format: bp_form_complete-{ontology_acronym_list}-{value}
- For example, bp_form_complete-NCIT-uri will use NCI Thesaurus (ontology acronym is NCIT) and will put the term URI in the field after the user selects the term from the pull-down list.
  - Note: In addition to single ontology ids, you can use a list:
    bp_form_complete-NCIT,BIRNLEX-uri
  - OR use 'all' to search across all BioPortal ontologies:
    bp_form_complete-all-uri
- You can use the following parameters to select which value will be placed into the user-visible input field:
  - uri : put the complete URI of the term (e.g., "http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Neoplasm");
  - shortid : put the short id of the term, as used in BioPortal (e.g., "Common_Neoplasm");
  - name : put the preferred name of the term (e.g., "Common Neoplasm");
Hidden form elements auto-generated

In addition to the input element you defined, there are four hidden form elements that are created and then set when a user selects 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_bioportal_preferred_name">
<input type="hidden" id="a_bioportal_concept_id">
<input type="hidden" id="a_bioportal_ontology_id">
<input type="hidden" id="a_bioportal_full_id">
```
Optional attributes
- Include term definitions. Use data-bp_include_definitions="true". This will display definitions with the list of terms that are returned. For example, use this code to display search results for 'heart' terms, with definitions, in the NCI Thesaurus.
  <input type="text" name="m" data-bp_include_definitions="true" class="bp_form_complete-NCIT-name"/>
- Limit lookup to terms below a root term. Use data-bp_search_branch="{class_id}" (replace {class_id} with the class id for the term to use as the branch root). For example, use this code to limit the search for 'heart' to terms within the 'Anatomic_Structure_System_or_Substance' branch of the NCI Thesaurus.
  <input type="text" name="n" data-bp_search_branch="Anatomic_Structure_System_or_Substance" class="bp_form_complete-NCIT-name"/>
- Object types
  - Search 'class' and 'property' objects. Use data-bp_objecttypes="class,property". For example, use this code to search for 'function' among both 'class' and 'property' objects from the "Adverse Event Reporting Ontology".
    <input type="text" name="o" data-bp_objecttypes="class,property" class="bp_form_complete-AERO-uri"/>
  - Search only 'property' objects. Use data-bp_objecttypes="property". For example, use this code to search for 'function' among only 'property' objects from the "Adverse Event Reporting Ontology".
    <input type="text" name="p" data-bp_objecttypes="property" class="bp_form_complete-AERO-uri"/>
  - Search 'class' and 'individual' objects. Use data-bp_objecttypes="class,individual". For example, use this code to search for 'seizure' among 'class' and 'individual' objects from the "Adverse Event Reporting Ontology".
    <input type="text" name="q" data-bp_objecttypes="class,individual" class="bp_form_complete-AERO-uri"/>
  - Only search 'individual' objects. Use data-bp_objecttypes="individual". For example, use this code to this search for 'seizure' only among 'individual' objects from the "Adverse Event Reporting Ontology".
    <input type="text" name="r" data-bp_objecttypes="individual" class="bp_form_complete-AERO-uri"/>

Ontology search widget

To add a search widget to your HTML page that searches a specific ontology, do the following:

Download the quick_jump.js file and 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 = "FB-DV";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8">
</script>

Note: If you would like to use Quick Jump across multiple ontologies:
- You can enter a comma-separated list of ontology ids:
  var BP_ontology_id = "NCIT,BIRNLEX";
- You cans set the variable to 'all' to search all ontologies in BioPortal:
  var BP_ontology_id = "all";
In the code that you just pasted, make sure to change the path to the quick_jump.js file to point to the location where you put the file (relative to your HTML file)
- For example, if you put the quick_jump.js file in the same directory as your HTML file, this is the code you would use:
```
<script type="text/javascript">
    var BP_ontology_id = "NCIT";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>
```
To limit the term lookup to a particular branch of an ontology, include the following Javascript in your page (replace conceptid with the id for the term which you would like 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;
```

Ontology visualization widget

To add a widget visualizing your ontology to your HTML page, simple copy the code from the Ontology Widget page for your ontology of interest. Here is a sample:

<iframe src="http://bioportal.bioontology.org/widgets/visualization?
  ontology=NCIT
  &class=http%3A%2F%2Fncicb.nci.nih.gov%2Fxml%2Fowl%2FEVS%2FThesaurus.owl%23C38999
  &apikey=YOUR_API_KEY"
  frameborder="0">
</iframe>

NCBO Ontology Tree Widget

Description

The OntologyTree widget is an embeddable Flex application that allows a user to interact with a tree browser for ontologies. The widget can be configured to display a list of all the ontologies in BioPortal, allowing the user to select which one to view, or can be setup to view a particular ontology. Additionally, there are several Javascript helper functions for the widget, allowing it to be utilized as a fully functional component in other applications.

Location

Add the following files to use the widget:

Or the minified versions:

Setup

You will need to use jQuery to utilize the Tree Widget. If you aren't using jQuery already, you can add it as follows:
```
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
```
Create a div element to store the tree:
```
<div id="tree"></div>
```

Initialize the tree:

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

The div you created should now contain a tree showing the roots of the NCIT ontology
Additional setup options:
- autoclose: Close other branches of the tree when expanding a new one
- treeClass: Class to identify the tree with
- autocompleteClass: Class to identify the autocomplete (search) input with
- width: Set the width of the tree and autocomplete input
- startingClass: Start with this class selected (and expanded to) in the tree
- startingRoot: 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: Use a different NCBO REST instance (not normally used)
- ncboUIURL: Use a different NCBO UI instance (not normally used)

Callbacks and Event Triggers

You can interact programmatically with the tree using JavaScript and jQuery. Callbacks can be passed when setting up the tree:

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

The following are the available callbacks with their arguments:

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

You can also listen to these as jQuery events:

tree.on("afterSelect", function(event, classId, prefLabel, selectedNode) {
  console.log(classId);
}

Here are the events with their arguments:

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 you can call on the object 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 and 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 ontology.

Difference between revisions of "NCBO Widgets"