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 class in the following format:
- For example,
bp_form_complete-1032-uriwill 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");
- For example,
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 from the Ontology Widgets page in Bioportal and paste it to your HTML page
- 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, you will have:
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:
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:
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).