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.

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

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