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.

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.

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 filed to your form that lets the user fetch a term from your ontology of interest, do the following:

• Download the ["http://bioportal.bioontology.org/javascripts/widgets/form_complete.js 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 class in the following format: bp_form_complete-{ontology_id}-{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.
  • You can use the following values:
    • uri: put the complete URI of the concept (e.g., http://bioportal.bioontology.org/visualize/39478/Common_Neoplasm);
    • shortid: put the short id of the concept, as used in BioPortal (e.g., "Common_Neoplasm");
    • name: put the preferred name of the concept (e.g., "Common Neoplasm");

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")

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 out 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).