NCBO Widgets

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.
• Feed widget: you can put a widget on your site that will have a live feed of all the changes to your ontology of interest, such as uploads of a new version, comments from other users, new mappings for concepts in your ontology.
• 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.
• **NEW** OntologyTree 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_id_list}-{value}
  • For example, bp_form_complete-1032-uri will use NCI Thesaurus (ontology id is 1032) 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-1032,1089-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., <a rel="nofollow" title="http://bioportal.bioontology.org/visualize/39478/Common_Neoplasm" class="external free" href="http://bioportal.bioontology.org/visualize/39478/Common_Neoplasm">http://bioportal.bioontology.org/visualize/39478/Common_Neoplasm</a>);
    • 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");
  • 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">
      

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 = "1016";
  </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 = "1032,1089";
  • 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 = "1032";
    </script>
    <script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>
    

Feed widget

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

<script type="text/javascript">
	var BP_ontology_id = "1032"
</script>
<script src="http://bioportal.bioontology.org/javascripts/widgets/feed_widget.js" type="text/javascript" charset="utf-8"></script>

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:

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
	id="FlexoViz" width="100%" height="100%"
	codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
	<param name="movie" value="http://keg.cs.uvic.ca/ncbo/flexviz/FlexoViz.swf" />
	<param name="quality" value="high" />
	<param name="bgcolor" value="#ffffff" />
	<param name="allowScriptAccess" value="always" />
	<embed src="http://keg.cs.uvic.ca/ncbo/flexviz/FlexoViz.swf" bgcolor="#ffffff"
		width="100%" height="100%" name="FlexoViz" align="middle"
		play="true"
		loop="false"
		quality="high"
		allowScriptAccess="always"
		type="application/x-shockwave-flash"
		flashVars="widget=true&ontology=39478&server=http://rest.bioontology.org/bioportal/"
		pluginspage="http://www.adobe.com/go/getflashplayer">
	</embed>
</object>			

If you want the visualization to be focused on a particular term in the ontology, you can add the term id to the parameters above. For example, to have the widget focus on Melanoma in NCI Thesaurus, replace the following line in the snippet above:

		flashVars="widget=true&ontology=39478&server=http://rest.bioontology.org/bioportal/"

with

		flashVars="widget=true&ontology=39478&nodeid=Melanoma&server=http://rest.bioontology.org/bioportal/"

(note "&nodeid=Melanoma")

OntologyTree 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
http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf

Parameters

• ontology = The id of the ontology to use, by default it assumes this value is the ontology version id
• virtual [true|false] - If true then the above ontology parameter is assumed to be a virtual ontology id
• canchangeontology [true|false] = If false then users can't change the current ontology
• canchangeroot [true|false] = If true the the user can specify a root concept (using the context menu)
• rootconceptid = The id of the root concept to show in the tree, leave out to show the ontology roots
• server = The rest server to use. Defaults to "http://rest.bioontology.org/bioportal/".
• redirecturl = The url to redirect to for terms and ontologies (in BioPortal). Defaults to "http://bioportal.bioontology.org/".
• alerterrors [true|false] = If true then errors will be displayed in an annoying popup box.
• title = The title for the browser window

Embed Example
Using Javascript (preferred):

<script src="http://keg.cs.uvic.ca/ncbo/ontologytree/AC_OETags.js" language="javascript"></script>
<!--
// -----------------------------------------------------------------------------
// Globals
// Major version of Flash required
var requiredMajorVersion = 9;
// Minor version of Flash required
var requiredMinorVersion = 0;
// Minor version of Flash required
var requiredRevision = 124;
// -----------------------------------------------------------------------------
// -->

// Version check for the Flash Player that has the ability to start Player Product Install (6.0r65)
var hasProductInstall = DetectFlashVer(6, 0, 65);

// Version check based upon the values defined in globals
var hasRequestedVersion = DetectFlashVer(requiredMajorVersion, requiredMinorVersion, requiredRevision);

if (hasProductInstall && !hasRequestedVersion) {
    // DO NOT MODIFY THE FOLLOWING FOUR LINES
    // Location visited after installation is complete if installation is required
    var MMPlayerType = (isIE == true) ? "ActiveX": "PlugIn";
    var MMredirectURL = window.location;
    document.title = document.title.slice(0, 47) + " - Flash Player Installation";
    var MMdoctitle = document.title;

    AC_FL_RunContent(
    "src", "playerProductInstall",
    "FlashVars", "MMredirectURL=" + MMredirectURL + '&MMplayerType=' + MMPlayerType + '&MMdoctitle=' + MMdoctitle + "",
    "width", "300",
    "height", "100%",
    "align", "middle",
    "id", "OntologyTree",
    "quality", "high",
    "bgcolor", "#ffffff",
    "name", "OntologyTree",
    "allowScriptAccess", "always",
    "type", "application/x-shockwave-flash",
    "pluginspage", "http://www.adobe.com/go/getflashplayer"
    );
} else if (hasRequestedVersion) {
    // if we've detected an acceptable version
    // embed the Flash Content SWF when all tests are passed
    AC_FL_RunContent(
    "src", "http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf",
    "width", "300",
    "height", "100%",
    "align", "middle",
    "id", "OntologyTree",
    "quality", "high",
    "bgcolor", "#ffffff",
    "name", "OntologyTree",
    "allowScriptAccess", "always",
    "flashVars", "ontology=&virtual=false&alerterrors=false&canchangeontology=true&rootconceptid=",
    "type", "application/x-shockwave-flash",
    "pluginspage", "http://www.adobe.com/go/getflashplayer"
    );
} else {
    // flash is too old or we can't detect the plugin
    var alternateContent = 'Alternate HTML content should be placed here. '
    + 'This content requires the Adobe Flash Player. '
    + '<a href=http://www.adobe.com/go/getflash/>Get Flash</a>';
    document.write(alternateContent);
    // insert non-flash content
}

Using HTML:

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
	id="OntologyTree" width="300" height="100%"
	codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
	<param name="movie" value="http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf" />
	<param name="quality" value="high" />
	<param name="bgcolor" value="#ffffff" />
	<param name="allowScriptAccess" value="always" />
	<param name="flashVars" value="ontology=&alerterrors=false&canchangeontology=true" />
	<embed src="http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf" quality="high" bgcolor="#ffffff"
		width="300" height="100%" name="OntologyTree" align="middle"
		play="true"
		loop="false"
		allowScriptAccess="always"
		type="application/x-shockwave-flash"
		flashVars="ontology=&alerterrors=false&canchangeontology=true"
		pluginspage="http://www.adobe.com/go/getflashplayer">
	</embed>
</object>

Javascript Examples
You will need to copy/paste this code to a Javascript file or embed directly in the HTML for usage in your page.

/* 
 * The following JavaScript functions allow you to interact with the Flash BioPortal Ontology Tree.  
 * You can load an ontology by id, and get the current ontology id or name.
 * Once an ontology is loaded then you can get the currently selected concept by id or name,
 * and you can also select a concept by id or name.  
 * You can also listen for one of these events by implementing the following functions (see the stubs below):
 * appComplete, treeSelectionChanged, treeNodeDoubleClicked, or errorLoadingOntology
 *
 * These are the parameters that you can pass into the application using the "flashVars" parameter:
 * (see the examples below):
 * - ontology: the id of the ontology (version or virtual)
 * - virtual: if false (default) then the ontology id above is the version id
 * 			  if true then the above ontology id is assumed to be the virtual id 
 * - alerterrors: (true/false) determines whether the application will display errors (default is false)
 * - server: defines the URL of the rest server (null by default)
 * - title: changes the default title for the page 
 * - canchangeontology: if true then the ontology can be changed
 * - rootconceptid: sets the optional root node of the tree
 * - canchangeroot: if false then the root of the tree cannot be changed by the user (using context menu items)
 */

// get a handle for the flash application
function getApp() {
	if (navigator.appName.indexOf ("Microsoft") != -1) {
		app = window["OntologyTree"];
	} else {
		app = document["OntologyTree"];
	}
	if (app == null) {
		app = document.getElementById("OntologyTree");
	}
	if (app == null) {
		alert("Could not get Flash object, JavaScript/Flex communication failed.");
	}
	return app;
}

// these are the available functions that you can call ONCE the 
// flash SWF has finished loading

/** Loads a new ontology by id. */
function loadOntology(ontologyID) {
	var app = getApp();
	if (app && app.loadOntology) {
		app.loadOntology(ontologyID);
	}
}

/** Gets the id of the current ontology, will be null if no ontology is loaded. */
function getOntologyID() {
	var ontologyID = null;
	var app = getApp();
	if (app && app.getOntologyID) {
		ontologyID = app.getOntologyID();
	}
	return ontologyID;
}

/** Gets the name of the current ontology, will be null if no ontology is loaded. */
function getOntologyName() {
	var ontologyName = null;
	var app = getApp();
	if (app && app.getOntologyName) {
		ontologyName = app.getOntologyName();
	}
	return ontologyName;
}

/** Gets the id of the currently selected concept, will be null if nothing is selected. */
function getSelectedConceptID() {
	var conceptID = null;
	var app = getApp();
	if (app && app.getSelectedConceptID) {
		conceptID = app.getSelectedConceptID();
	}
	return conceptID;
}

/** 
 * Gets the full id (not all ontologies support this) of the currently selected concept. 
 * Will be null if nothing is selected, will be the same as the conceptID if no fullID exists. 
 */
function getSelectedConceptFullID() {
	var conceptID = null;
	var app = getApp();
	if (app && app.getSelectedConceptFullID) {
		conceptID = app.getSelectedConceptFullID();
	}
	return conceptID;
}

/** Gets the name of the currently selected concept, will be null if nothing is selected. */
function getSelectedConceptName() {
	var conceptName = null;
	var app = getApp();
	if (app && app.getSelectedConceptName) {
		conceptName = app.getSelectedConceptName();
	}
	return conceptName;
}

/** Loads and selects a concept (by id) in the current ontology. */
function loadConceptByID(conceptID) {
	var app = getApp();
	if (app && app.loadConceptByID) {
		app.loadConceptByID(conceptID);
	}
}

/** Attempts to load and select a concept (by name) in the current ontology. */
function loadConceptByName(conceptName) {
	var app = getApp();
	if (app && app.loadConceptByName) {
		app.loadConceptByName(conceptName);
	}
}

/** This function gets call by flash when the swf has finished loading. */
function appComplete(swfID) {
//	alert("flash app finished loading: " + swfID);
}

/** Implement this function to listen for tree selection changes */
function treeSelectionChanged(nodeID, nodeName, swfID) {
//	alert("tree selection: " + nodeID + " - " + nodeName + " - " + swfID);
}

/** Implement this function to listen for tree double click events */
function treeNodeDoubleClicked(nodeID, nodeName, swfID) {
	alert("tree node double clicked: " + nodeID + " - " + nodeName + " - " + swfID);
}

/** Implement this function to listen for error messages when loading an ontology */
function errorLoadingOntology(errorMsg, swfID) {
//	alert("Error: " + errorMsg);
}

GWT

• See http://code.google.com/p/gwt2swf/ for information on how to embed SWF in GWT.

Referencing your ontology of interest in the widgets

Most of the time you would want your widget to use the latest version of your ontology of interest that is available in BioPortal. Thus, you would want to use the ontology id and not the version is in your widget. To find the ontology id, go to the "Ontology Details" page for your ontology of interest in BioPortal (e.g., the page for NCI Thesaurus). You will find the ontology id on the Metadata tab there (e.g., the ontology id for NCI Thesaurus is 1032).