Difference between revisions of "XBio:D Javascript Library Reference"

From xBio:D Wiki
Jump to navigation Jump to search
(→‎Options)
(→‎Loading the xBio:D JavaScript Library)
 
(135 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
'''Introduction'''
 
'''Introduction'''
  
−
The xBio:D Javascript library offers the functionality to create rich, dynamic, and interactive features for use with the [[OJ_Break API Reference|OJ_Break API]]. The OJ_Break API provides procedures to retrieve data within the xBio:D database, and the xBio:D JS library is how that data gets presented. Users planning on working with the xBio:D JS library should be familiar with Javascript programming and object-oriented programming.  
+
The xBio:D JavaScript library offers the functionality to create rich, dynamic, and interactive features for use with the [[OJ_Break API Reference|OJ_Break API]]. The OJ_Break API provides procedures to retrieve data within the xBio:D database, and the xBio:D JS library is how that data gets presented. Users planning on working with the xBio:D JS library should be familiar with JavaScript programming and object-oriented programming.  
  
 
== API Access ==
 
== API Access ==
Line 9: Line 9:
 
== Example ==
 
== Example ==
  
−
An easy way to become familiar with the xBio:D JS library is to see a simple example of a web application which uses two xBio:D methods. The first is a Google Maps widget which takes data from the OJ_Break method [[OJ_Break API Reference#getLocalities|getLocalities]] for a specified [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]] and displays the data onto an interactive map. Read more about the [https://developers.google.com/maps/documentation/javascript/tutorial Google Maps Javascript API]. The second method used in the example is a listing of included taxa for a specified tnuid by using the OJ_Break method [[OJ_Break API Reference#getIncludedTaxa|getIncludedTaxa]]. When you click on any of the linked taxa, that taxa's localities will be shown on the map, however this feature will not be explained in this bare bones example as only the basics will be covered.
+
An easy way to become familiar with the xBio:D JS library is to see a simple example of a web application which uses two xBio:D methods. The first is a Google Maps widget which takes data from the OJ_Break method [[OJ_Break API Reference#getLocalities|getLocalities]] for a specified [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]] and displays the data onto an interactive map. Read more about the [https://developers.google.com/maps/documentation/javascript/tutorial Google Maps JavaScript API]. The second method used in the example is a listing of included taxa for a specified tnuid by using the OJ_Break method [[OJ_Break API Reference#getIncludedTaxa|getIncludedTaxa]].
  
−
<!--[[File:Xbiodjslib.png|alt=source code for a simple xBio:D web application.|Simple example of web application.]]-->
+
[[File:wiki-test.png|alt=source code for a simple xBio:D web application.|Simple example of web application.]]
−
  <nowiki></nowiki><span style="color: purple"><!DOCTYPE HTML></span><nowiki>
 
−
  </nowiki><span style="color: blue"><html></span><nowiki>
 
−
  </nowiki><span style="color: blue"><head></span><nowiki>
 
−
</nowiki><span style="color: blue"><meta </span><span style="color: purple">charset</span>=<span style="color: green">"UTF-8"</span><nowiki></nowiki><span style="color: blue">/></span><nowiki>
 
−
</nowiki><span style="color: blue"><title></span><nowiki>xBio:D API test</nowiki><span style="color: blue"></title></span><nowiki>
 
−
</nowiki><span style="color: blue"><link </span><span style="color: purple">rel</span>=<span style="color: green">"stylesheet"</span><span style="color: purple"> type</span>=<span style="color: green">"text/css"</span><span style="color: purple"> href</span>=<span style="color: green"><nowiki>"xbiod.css"</nowiki></span><nowiki></nowiki><span style="color: blue">></span><nowiki>
 
−
</nowiki><span style="color: blue"><script </span><span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span><span style="color: blue">></span><nowiki>
 
−
</nowiki><span style="color: purple">src</span>=<span style="color: green"><nowiki>"http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js"</nowiki></span><nowiki>
 
−
</nowiki><span style="color: blue"></script></span><nowiki>
 
−
</nowiki><span style="color: blue"><script </span><span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span><span style="color: blue">></span><nowiki>
 
−
</nowiki><span style="color: purple">src</span>=<span style="color: green"><nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki></span><nowiki>
 
−
</nowiki><span style="color: blue"></script></span><nowiki>
 
−
</nowiki><span style="color: blue"><script </span> <span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span> <span style="color: purple">src</span>=<span style="color: green"><nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki></span><span style="color: blue">></span><span style="color: blue"></script></span><nowiki>
 
−
</nowiki><span style="color: blue"><script></span><nowiki>
 
−
// Call the loader for the current page
 
−
$(document).ready(loader);
 
  
−
</nowiki><span style="color: blue">function</span><nowiki> loader() {
+
<!--  1 <span style="color:purple"><!DOCTYPE HTML></span>
−
 
+
  2 <span style="color: blue"><html></span>
−
// Initialize xBio:D library
+
  3 <span style="color: blue"><head></span>
−
xbiod.init([</nowiki><span style="color: green">'visual'</span><nowiki>,</nowiki><span style="color: green">'taxon'</span><nowiki>], </nowiki><span style="color: green; font-style: italic">'{API_KEY}'</span><nowiki>, function() {
+
  4    <span style="color: blue"><meta </span><span style="color: purple">charset</span>=<span style="color: green">"UTF-8"</span><span style="color: blue">/></span>
−
</nowiki><span style="color: blue">var</span><nowiki> tnuid = </nowiki><span style="color: pink">605</span><nowiki>;
+
  5    <span style="color: blue"><title></span>xBio:D API Test<span style="color: blue"></title></span>
−
 
+
  6    <span style="color: blue"><link </span><span style="color: purple">rel</span>=<span style="color: green">"stylesheet"</span><span style="color: purple"> type</span>=<span style="color: green">"text/css"</span><span style="color: purple"> href</span>=<span style="color: green">"xbiod.css"</span><span style="color: blue">></span>
−
// Load xBio:D components
+
  7    <span style="color: blue"><script </span><span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span><span style="color: purple"> src</span>=<span style="color: green">"<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"</span><span style="color: blue">></script></span>
−
</nowiki><span style="color: blue">var</span><nowiki> visual = </nowiki><span style="color: red">new</span><nowiki> xbiod.visual();
+
  8    <span style="color: blue"><script </span><span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span><span style="color: purple"> src</span>=<span style="color: green">"<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"</span><span style="color: blue">></script></span>
−
</nowiki><span style="color: blue">var</span><nowiki> taxon = </nowiki><span style="color: red">new</span><nowiki> xbiod.taxon();
+
  9    <span style="color: blue"><script </span><span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span><span style="color: purple"> src</span>=<span style="color: green">"<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"</span><span style="color: blue">></script></span>
−
+
10    <span style="color: blue"><script</span> <span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span><span style="color: purple"> src</span>=<span style="color: green">"<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"</span><span style="color: blue">></span><span style="color: blue"></script></span>
−
// Load map
+
11    <span style="color: blue"><script></span>
−
visual.showGoogleMap(</nowiki><span style="color: green">'map_id'</span><nowiki>, tnuid);
+
12        <span style="color:green">// Call the loader for the current page</span>
−
+
13        $(document).ready(loader);
−
// Load included taxa
+
14
−
taxon.showIncludedTaxa(</nowiki><span style="color: green">'included_id'</span><nowiki>, tnuid, {show_num_spms: </nowiki><span style="color: green">'Y'</span><nowiki>,
+
15            <span style="color: blue">function</span> loader() {
−
    taxonFormat: </nowiki><span style="color: green">'<a href="test.html?tnuid=%tnuid%">%taxon%</a> %author% - %num_spms%'</span><nowiki>
+
16
−
});
+
17                <span style="color: green">// Initialize xBio:D library</span>
−
});
+
18                xbiod.init([<span style="color: green">'visual'</span>,<span style="color: green">'taxon'</span>], <span style="color: green; font-style: italic">/*API_KEY*/</span>, function() {
−
}
+
19                    <span style="color: blue">var</span> tnuid = <span style="color: DarkMagenta">605</span>;
−
</nowiki><span style="color: blue"></script></span><nowiki>
+
20
−
        </nowiki><span style="color: blue"><style </span> <span style="color: purple">type</span>=<span style="color: green">"text/css"</span><span style="color: blue">></span><nowiki>
+
21                    <span style="color:green">// Load xBio:D components</span>
−
html { height: </nowiki><span style="color: pink">100</span><nowiki>% }
+
22                    <span style="color: blue">var</span> visual = <span style="color: red">new</span> xbiod.visual();
−
body { height: </nowiki><span style="color: pink">100</span><nowiki>%; margin: </nowiki><span style="color: pink">0</span><nowiki>; padding: </nowiki><span style="color: pink">0</span><nowiki> }
+
23                    <span style="color: blue">var</span> taxon = <span style="color: red">new</span> xbiod.taxon();
−
#map_id { height: </nowiki><span style="color: pink">50</span><nowiki>% }
+
24
−
#included_id { height: </nowiki><span style="color: pink">50</span><nowiki>% }
+
25                    <span style="color:green">// Load map</span>
−
        </nowiki><span style="color: blue"></style></span><nowiki>
+
26                    visual.showGoogleMap(<span style="color: green">'map_id'</span>, tnuid);
−
    </nowiki><span style="color: blue"></head></span><nowiki>
+
27
−
    </nowiki><span style="color: blue"><body></span><nowiki>
+
28                    <span style="color: green">// Load included taxa</span>
−
</nowiki><span style="color: blue"><div </span><span style="color: purple">id</span>=<span style="color: green">"map_id"</span><nowiki></nowiki><span style="color: blue">/></span><nowiki>
+
29                    taxon.showIncludedTaxa(<span style="color: green">'included_id'</span>, tnuid, {show_num_spms: <span style="color: green">'Y'</span>});
−
</nowiki><span style="color: blue"><div </span><span style="color: purple">id</span>=<span style="color: green">"included_id"</span><nowiki></nowiki><span style="color: blue">/></span><nowiki>
+
31
−
    </nowiki><span style="color: blue"></body></span><nowiki>
+
32                });
−
    </nowiki><span style="color: blue"></html></span><nowiki></nowiki>
+
33            }
−
 
+
34    <span style="color: blue"></script></span>
−
[http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/test.html View simple example here (test.html)]
+
35    <span style="color: blue"><style </span><span style="color: purple">type</span>=<span style="color: green">"text/css"</span><span style="color: blue">></span>
 +
36        html { height: <span style="color: DarkMagenta">100%</span> }
 +
37        body { height: <span style="color: DarkMagenta">100%</span>; margin: <span style="color: DarkMagenta">0</span>; padding: <span style="color: DarkMagenta">0</span> }
 +
38        #map_id { height: <span style="color: DarkMagenta">50%</span> }
 +
39        #included_id { height: <span style="color: DarkMagenta">100%</span> }
 +
40    <span style="color: blue"></style></span>
 +
41 <span style="color: blue"></head></span>
 +
42 <span style="color: blue"><body></span>
 +
43    <span style="color: blue"><div </span><span style="color: purple">id</span>=<span style="color: green">"map_id"</span><span style="color: blue">/></span>
 +
44    <span style="color: blue"><div </span><span style="color: purple">id</span>=<span style="color: green">"included_id"</span><span style="color: blue">/></span>
 +
45 <span style="color: blue"></body></span>
 +
46 <span style="color: blue"></html></span>-->
  
  
 
There are a few things to note about this example:
 
There are a few things to note about this example:
 
* The '''<!DOCTYPE html>''' tag is necessary for HTML 5 applications (line 1)
 
* The '''<!DOCTYPE html>''' tag is necessary for HTML 5 applications (line 1)
−
* Jquery 1.8 library is included with a '''<script>''' tag (line 7 - 9)  
+
* Jquery 1.8 library is included with a '''<script>''' tag (line 7)
−
* The Map API Javascript is included with a '''<script>''' tag (line 10 - 12)
+
* Jquery UI 1.10.4 library is included with a '''<script>''' tag (line 8)  
−
* The xBio:D JS library is included with a '''<script>''' tag (line 13)
+
* The Google Map API JavaScript library is included with a '''<script>''' tag (line 9)
−
* A function called ''loader'' intializes the xBio:D resources when the web page has finished loading (line 16)
+
* The xBio:D JS library is included with a '''<script>''' tag (line 10)
−
* Two objects where created to access the xBio:D components called ''visual'' and ''taxon'' (line 25 - 26)
+
* A function called ''loader'' intializes the xBio:D resources when the web page has finished loading (line 15)
−
* The applications are created by calling there respective methods via the xBio:D library components (line 29 & 32 - 33)
+
* Two objects where created to access the xBio:D components called ''visual'' and ''taxon'' (line 22 - 23)
−
* In the '''<body>''' there are two '''<nowiki><div></nowiki>''' elements which create areas to hold the widgets. The first is called ''map_id'' and the second is ''included_id''. (line 40 - 41)
+
* The applications are created by calling there respective methods via the xBio:D library components (line 26 & 29 - 30)
 +
* In the '''<body>''' there are two '''<nowiki><div></nowiki>''' elements which create areas to hold the widgets. The first is called ''map_id'' and the second is ''included_id''. (line 43 - 44)
  
  
Line 87: Line 83:
 
  <span style="color: blue"><script </span><span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span> <span style="color: purple">src</span>=<span style="color: green"><nowiki>"http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js"</nowiki></span><span style="color: blue">></script></span>
 
  <span style="color: blue"><script </span><span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span> <span style="color: purple">src</span>=<span style="color: green"><nowiki>"http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js"</nowiki></span><span style="color: blue">></script></span>
  
−
The URL in the '''<script>''' tag above is the location of the Javascript file which allows [http://en.wikipedia.org/wiki/JQuery JQuery] 1.8 to run on the web application. JQuery is used in the xBio:D JS library to get methods from the OJ_Break API and other scripts. It is a necessary component of any web app that intends to use xBio:D functionality.
+
The URL in the '''<script>''' tag above is the location of the JavaScript file which allows [http://en.wikipedia.org/wiki/JQuery JQuery] 1.8 to run on the web application. JQuery is used in the xBio:D JS library to get methods from the OJ_Break API and other scripts. It is a necessary component of any web app that intends to use xBio:D functionality.
  
 
=== Loading the Google Maps API ===
 
=== Loading the Google Maps API ===
 
  <span style="color: blue"><script </span><span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span> <span style="color: purple">src</span>=<span style="color: green"><nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki></span><span style="color: blue">></script></span>
 
  <span style="color: blue"><script </span><span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span> <span style="color: purple">src</span>=<span style="color: green"><nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki></span><span style="color: blue">></script></span>
  
−
The URL in the '''<script>''' tag above is the location of the Javascript file which will load all the necessary defintions to allow access to the Maps API. Normally, an access key would need to be provided in order to use the Maps library. See [https://developers.google.com/maps/documentation/javascript/tutorial#Loading_the_Maps_API Loading the Maps API] for more info. This script file is necessary for web apps that use Google Maps as part of the application. It is a necessary file to have in this simple example, but is not required for all xBio:D applications.
+
The URL in the '''<script>''' tag above is the location of the JavaScript file which will load all the necessary defintions to allow access to the Maps API. Normally, an access key would need to be provided in order to use the Maps library. See [https://developers.google.com/maps/documentation/javascript/tutorial#Loading_the_Maps_API Loading the Maps API] for more info. This script file is necessary for web apps that use Google Maps as part of the application. It is a necessary file to have in this simple example, but is not required for all xBio:D applications.
  
−
=== Loading the xBio:D Javascript Library ===
+
=== Loading the xBio:D JavaScript Library ===
−
  <span style="color: blue"><script </span><span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span> <span style="color: purple">src</span>=<span style="color: green"><nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki></span><span style="color: blue">></script></span>
+
  <span style="color: blue"><script </span><span style="color: purple">type</span>=<span style="color: green">"text/javascript"</span> <span style="color: purple">src</span>=<span style="color: green"><nowiki>"http://xbiod.osu.edu/xbiod_lib/xbiod.js"</nowiki></span><span style="color: blue">></script></span>
  
−
The URL in the '''<script>''' tage above is the location of the xBio:D Javascript Library which is a required file for this simple example and any web application that will be using xBio:D applications.
+
The URL in the '''<script>''' tage above is the location of the xBio:D JavaScript Library which is a required file for this simple example and any web application that will be using xBio:D applications.
  
 
=== Initializing the xBio:D JS Library ===
 
=== Initializing the xBio:D JS Library ===
−
  <nowiki></nowiki><span style="color: blue"><script></span><nowiki>
+
  <span style="color: blue"><script></span>
−
// Call the loader for the current page
+
    <span style="color: green">// Call the loader for the current page</span>
−
$(document).ready(loader);
+
    $(document).ready(loader);<br>
−
 
+
        <span style="color: blue">function</span> loader() {<br>
−
</nowiki><span style="color: blue">function</span><nowiki> loader() {
+
            <span style="color: green">// Initialize xBio:D library</span>
−
 
+
            xbiod.init([<span style="color: green">'visual'</span>,<span style="color: green">'taxon'</span>], <span style="color: green; font-style: italic">/*API_KEY*/</span>, function(){
−
// Initialize xBio:D library
 
−
xbiod.init([</nowiki><span style="color: green">'visual'</span>,<span style="color: green">'taxon'</span>], <span style="color: green; font-style: italic">'{API_KEY}'</span>,<nowiki> function() {</nowiki>
 
  
−
To begin using the xBio:D library, first the components need to be loaded. This is done through the xBio:D ''init'' function which takes three parameters: an array of the components to be loaded, an API access key, and a callback function. In this example, the '''visual''' and '''taxon''' resources are passed to the ''init'' function for loading. This example also shows where a user would provide an OJ_Break API access key. See [[OJ_Break API Access]] for more information on access keys. Lastly, a callback method needs to be provided which will create the component objects.
+
To begin using the xBio:D library, first the components need to be loaded. This is done through the xBio:D ''init'' function which takes three parameters: an array of the components to be loaded, an API access key, and a callback function. In this example, the '''visual''' and '''taxon''' resources are passed to the ''init'' function for loading (all resources and their methods can be found in the [[XBio:D Javascript Library Reference#Reference|Reference]] section below). This example also shows where a user would provide an OJ_Break API access key. See [[OJ_Break API Access]] for more information on access keys. Lastly, a callback method needs to be provided which will create the component objects.
  
 
==== Component Objects ====
 
==== Component Objects ====
−
  // Load xBio:D components
+
  <span style="color: green">// Load xBio:D components</span>
 
  <span style="color: blue">var</span> visual = <span style="color: red">new</span> xbiod.visual();
 
  <span style="color: blue">var</span> visual = <span style="color: red">new</span> xbiod.visual();
 
  <span style="color: blue">var</span> taxon = <span style="color: red">new</span> xbiod.taxon();
 
  <span style="color: blue">var</span> taxon = <span style="color: red">new</span> xbiod.taxon();
  
−
An object derived from a class is instatiated using the '''new''' keyword and a class's constructor. The Javascript class that represents the xBio:D visual applications is the '''visual''' class/component and similarly the class that represents the xBio:D taxon applications is the '''taxon''' class/component. To access functionality from either of these components requires an object with a reference to that component. These objects allow methods from each component to be called to the web page.
+
An object derived from a class is instatiated using the '''new''' keyword and a namespace's constructor. The JavaScript namespace that represents the xBio:D visual applications is the '''visual''' namespace/component and similarly the namespace that represents the xBio:D taxon applications is the '''taxon''' namespace/component. Access to functionality from either of these components requires an object with a reference to that component. These objects allow methods from each component to be called to the web page.
  
 
==== Calling Application Methods ====
 
==== Calling Application Methods ====
−
  // Load map
+
  <span style="color: green">// Load map</span>
 
  visual.showGoogleMap(<span style="color: green">'map_id'</span>, tnuid);
 
  visual.showGoogleMap(<span style="color: green">'map_id'</span>, tnuid);
 
 
 
 
−
  // Load included taxa
+
  <span style="color: green">// Load included taxa</span>
 
  taxon.showIncludedTaxa(<span style="color: green">'included_id'</span>, tnuid, {show_num_spms: <span style="color: green">'Y'</span>, taxonFormat: <span style="color: green">'<a href="test.html?tnuid=%tnuid%">%taxon%</a> %author% - %num_spms%'</span>});
 
  taxon.showIncludedTaxa(<span style="color: green">'included_id'</span>, tnuid, {show_num_spms: <span style="color: green">'Y'</span>, taxonFormat: <span style="color: green">'<a href="test.html?tnuid=%tnuid%">%taxon%</a> %author% - %num_spms%'</span>});
  
 
Each application has a method associated with it which takes several parameters which will dictate what data it loads, where it will be contained, and options for how it should be presented. These methods and requirements can be found in the [[XBio:D Javascript Library Reference#Reference|Reference]] section.
 
Each application has a method associated with it which takes several parameters which will dictate what data it loads, where it will be contained, and options for how it should be presented. These methods and requirements can be found in the [[XBio:D Javascript Library Reference#Reference|Reference]] section.
  
−
In the above example, the '''visual''' method ''showGoogleMap'' gets passed a '''<nowiki><div></nowiki>''' element id, which decides where it will be contained, and a tnuid which will dictate which taxon data the map will locate.
+
In the above example, the '''visual''' method ''showGoogleMap'' gets passed a '''<nowiki><div></nowiki>''' element ID string which decides where it will be contained and a tnuid which will dictate which taxon data the map will locate.
  
−
The '''taxon''' method ''showIncludedTaxa'' gets passed similar parameters (a specified '''<nowiki><div></nowiki>''' element id and a tnuid) however it also gets additional options in the form of a Javascript object literal. In this example, the option ''[[OJ_Break API Data Type Glossary#show_num_spms|show_num_spms]]'' is given the [[OJ Break API Data Type Glossary#Boolean_Flag| Boolean_flag]] 'Y' signifying that the application should display the number of specimens for that particular taxon and ''taxonFormat'' is assigned to present the data as links using the '''<a>''' tag.
+
The '''taxon''' method ''showIncludedTaxa'' gets passed similar parameters (a specified '''<nowiki><div></nowiki>''' element ID string and a tnuid) however it also gets additional options in the form of a [http://www.w3schools.com/js/js_objects.asp JavaScript object literal]. In this example, the option ''[[OJ_Break API Data Type Glossary#show_num_spms|show_num_spms]]'' is given the [[OJ Break API Data Type Glossary#Boolean_Flag| Boolean_flag]] 'Y' signifying that the application should display the number of specimens for that particular taxon and ''taxonFormat'' is assigned to present the data as links using the '''<a>''' tag.
  
 
==== Element Containers ====
 
==== Element Containers ====
−
Each method requires one unique '''<nowiki><div></nowiki>''' tag with an id (seen in the example '''<body>''' below). This will be used to specify where the resource will be contained in the web page.
+
Each method requires one or more unique '''<nowiki><div></nowiki>''' tag IDs as string parameters (seen in the example '''<body>''' below). This will be used to specify where the resource will be contained in the web page.
  
 
  <span style="color: blue"><body></span>
 
  <span style="color: blue"><body></span>
Line 140: Line 134:
  
 
== Reference ==
 
== Reference ==
−
=== Visual ===
+
=== Agent ===
−
==== showGoogleMap ====
+
==== showAgentInfo ====
 
===== Description =====
 
===== Description =====
 +
Displays information about an agent, including name, contact information, and a short biography.
 +
===== Parameters =====
 +
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
 +
* [[OJ_Break v2 Agent Reference#agent_id|agent_id]]
 +
* options
 +
===== Options =====
 +
* widget_options - Object
  
 +
==== showAgentOccurrences ====
 +
===== Description =====
 +
Displays collected occurrences for a specified agent on a Google Map. Creates two windows.
 
===== Parameters =====
 
===== Parameters =====
−
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
+
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
 
* options
 
* options
 +
 
===== Options =====
 
===== Options =====
−
* [[OJ_Break API Data Type Glossary#pnid_2|pnids]] - array of number
+
* info_element_id - ID String (defaults to element_id parameter)
−
* [[OJ_Break API Data Type Glossary#inst_id_2|inst_id]] - number
+
* generalFormat - HTML String
−
* [[OJ_Break API Data Type Glossary#precDecimals|precDecimals]] - number
+
* markers - String ('spiderfy' or undefined). Requires additional dependencies (see below).
−
* [[OJ_Break API Data Type Glossary#showChildren|showChildren]] - Boolean_flag
+
* offset - Number
 +
* limit - Number
 +
* icons - Object
 +
* widget_options
  
 
===== Additional Requirements =====
 
===== Additional Requirements =====
 
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
 
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
 +
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]
  
−
==== showTaxonHierarchy ====
+
==== showAgentOccurrenceLocalityInfo ====
 +
===== Description =====
 +
Displays locality information for a certain agent's collecting occurrence.
 +
===== Parameters =====
 +
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
 +
* loc_id ([[OJ_Break API Data Type Glossary#loc_id_2|?]])
 +
* options
 +
===== Options =====
 +
None
 +
 
 +
==== showDescribedTaxa ====
 
===== Description =====
 
===== Description =====
−
An interactive, tree-based animation which allows a user to navigate through a selected taxon's hierarchy and all taxa available through the OJ_Break API.
+
Displays all taxa described by the specified agent.
 +
===== Parameters =====
 +
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
 +
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
 +
* options
 +
===== Options =====
 +
* taxonFormat - String
 +
* useTaxonItalics - Boolean
 +
* limit - Number
 +
* offset - Number
 +
* widget_options - Object
  
 +
==== showPublications ====
 +
===== Description =====
 +
Displays all publications for a specified agent.
 
===== Parameters =====
 
===== Parameters =====
−
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
+
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
−
* requestedNode
 
 
* options
 
* options
 +
===== Options =====
 +
* limit - Number
 +
* offset - Number
 +
* widget_options - Object
 +
 +
=== Occurrence ===
 +
==== showBiologicalInfo ====
 +
===== Description =====
 +
Displays both the habitat and associations for a selected occurrence identifier.
  
 +
===== Parameters =====
 +
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
 +
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
 +
* options
 
===== Options =====
 
===== Options =====
−
* [[OJ_Break API Data Type Glossary#show_num_spms|show_num_spms]] - Boolean_flag
+
* widget_options - Object
−
* [[OJ_Break API Data Type Glossary#inst_id_2|inst_id]] - number
 
−
* [[OJ_Break API Data Type Glossary#showSyns|showSyns]] - Boolean_flag
 
−
* [[OJ_Break API Data Type Glossary#showFossils|showFossils]] - Boolean_flag
 
−
* [[OJ_Break API Data Type Glossary#typesOnly|typesOnly]] - Boolean_flag
 
−
* node_color - string or hexadecimal number
 
−
* background_color - string or hexadecimal number
 
  
−
===== Additional Requirements =====
+
==== showOccurrenceInfo ====
−
* [http://en.wikipedia.org/wiki/Processing.js Processing.js] 1.4.1+
+
===== Description =====
−
* Pass requestedNode parameter a value of '''null''' when calling function. See below:
+
Displays collecting trip info for a specified occurrence.
−
<span style="color:blue;">// Load taxon hierarchy</span>
+
===== Parameters =====
−
visual.showTaxonHierarchy(<span style="color:green">'canvas_id'</span>, tnuid, <span style="color: red;">null</span>, {backgroundColor: <span style="color: green">'black'</span>});
+
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
 +
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
 +
* options
 +
===== Options =====
 +
* widget_options - Object
  
−
=== Taxon ===
+
==== showDeterminations ====
−
==== showIncludedTaxa ====
 
 
===== Description =====
 
===== Description =====
−
Displays taxa directly included within a taxon but not synonymous with it.
+
Displays determinations for a specified occurence.
 +
===== Parameters =====
 +
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
 +
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
 +
* options
 +
===== Options =====
 +
* widget_options - Object
  
 +
==== showLocalityInfo ====
 +
===== Description =====
 +
Displays locality info for a specified occurrence.
 
===== Parameters =====
 
===== Parameters =====
−
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
+
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
 
* options
 
* options
 
===== Options =====
 
===== Options =====
−
* [[OJ_Break API Data Type Glossary#inst_id|inst_id]] - number
+
* widget_options - Object
−
* [[OJ_Break API Data Type Glossary#showSyns|showSyns]] - Boolean_flag
 
−
* [[OJ_Break API Data Type Glossary#showFossils|showFossils]] - Boolean_flag
 
−
* [[OJ_Break API Data Type Glossary#types_only|types_only]] - Boolean_flag
 
−
* [[OJ_Break API Data Type Glossary#show_num_spms|show_num_spms]] - Boolean_flag
 
−
* taxonFormat - string
 
−
* useTaxonItalics - boolean
 
  
−
===== Additional Requirements =====
+
==== showSpecimenInfo ====
−
None
+
===== Description =====
 +
Displays specimen info for a specified occurrence.
 +
===== Parameters =====
 +
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
 +
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
 +
* options
 +
===== Options =====
 +
* widget_options - Object
  
−
==== showSynonyms ====
+
=== Search ===
 +
==== showSearch ====
 
===== Description =====
 
===== Description =====
−
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
+
A JQuery UI autocomplete search bar which can search for taxa, occurrences, institutions, agents, journals, localities, and places.
 +
 
 +
===== Parameters =====
 +
* element_id
 +
* options
 +
 
 +
===== Options =====
 +
* search - the type of search to execute. Controls the passing of URL parameters to methods. Can be specified a either 'id' or 'name'. Defaults to 'id'
 +
* domains - array of the below object elements
 +
** type - a domain keyword for which data gets searched for
 +
** handler_url - a URL that will be passed the ID of the selected type option
 +
 
 +
===== Additional Information =====
 +
====== Category Options Formatting ======
 +
Below is an example of how the categories should be input:
 +
 
 +
<span style="color:green;">// Load search</span>
 +
search.showSearch(<span style="color:green">'search_id'</span>, {domains: [{type: <span style="color: green">'taxon'</span>, handler_url: <span style="color: green">'<nowiki>http://domain.url/index.html</nowiki>'</span>}, {type: <span style="color: green">'occurrence'</span>, handler_url: <span style="color: green">'<nowiki>http://domain.url/occurrence.html</nowiki>'</span>}]});
  
 +
=== Taxon ===
 +
==== showAssociations ====
 +
===== Description =====
 +
Displays all associations for a specified taxon.
 
===== Parameters =====
 
===== Parameters =====
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* tnuid
 
* options
 
* options
 
===== Options =====
 
===== Options =====
−
* [[OJ_Break API Data Type Glossary#showFossils|showFossils]] - Boolean_flag
+
* basic_only - Boolean_flag
−
* taxonFormat - string
+
* limit - Number
−
* useTaxonItalics - boolean
+
* offset - Number
 +
* widget_options
  
−
===== Additional Requirements =====
+
==== showInstitutions ====
−
None
+
===== Description =====
 +
Displays institutions for which specimens of the selected taxon level belong.
 +
===== Parameters =====
 +
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
 +
* tnuid
 +
* options
 +
===== Options =====
 +
* limit - Number
 +
* offset - Number
 +
* widget_options - Object
  
−
==== showCollections ====
+
==== showContributors ====
 
===== Description =====
 
===== Description =====
−
Displays all collections for which specimen of the selected taxon belong.
+
Displays all contributing agents related to the occurrence, taxonomy, literature, and media of a taxon.
 +
===== Parameters =====
 +
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
 +
* tnuid
 +
* options
 +
===== Options =====
 +
* inst_id
 +
* widget_options
  
 +
==== showDeterminers ====
 +
===== Description =====
 +
Displays determiners for a specified taxon.
 
===== Parameters =====
 
===== Parameters =====
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* tnuid
 
* options
 
* options
 
===== Options =====
 
===== Options =====
−
* generalFormat - string
+
* limit - Number
−
 
+
* offset - Number
−
===== Additional Requirements =====
+
* inst_id
−
None
+
* widget_options
  
 
==== showHabitats ====
 
==== showHabitats ====
 
===== Description =====
 
===== Description =====
 
Displays all identified habitats for a selected taxon.
 
Displays all identified habitats for a selected taxon.
 +
===== Parameters =====
 +
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
 +
* tnuid
 +
* options
 +
===== Options =====
 +
* limit - Number
 +
* offset - Number
 +
* widget_options
  
 +
==== showIncludedTaxa ====
 +
===== Description =====
 +
Displays taxa directly included within a taxon but not synonymous with it.
 
===== Parameters =====
 
===== Parameters =====
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* tnuid
 
* options
 
* options
 
===== Options =====
 
===== Options =====
−
* generalFormat - string
+
* inst_id
−
 
+
* show_syns
−
===== Additional Requirements =====
+
* show_fossiles
−
None
+
* types_only
 +
* useTaxonItalics - Boolean
 +
* limit - Number
 +
* offset - Number
 +
* widget_options
  
 
==== showLiterature ====
 
==== showLiterature ====
 
===== Description =====
 
===== Description =====
 
Displays relevent publications for a specified taxon with links to the literature when available.
 
Displays relevent publications for a specified taxon with links to the literature when available.
 +
===== Parameters =====
 +
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
 +
* tnuid
 +
* options
 +
===== Options =====
 +
* show_children - Boolean_flag
 +
* show_bib - Boolean_flag
 +
* useTaxonItalics - Boolean
 +
* limit - Number
 +
* offset - Number
 +
* widget_options
  
 +
==== showSubordinateTaxa ====
 +
===== Description =====
 +
Displays the count of valid taxa levels available below the current taxon rank.
 
===== Parameters =====
 
===== Parameters =====
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* tnuid
 
* options
 
* options
 
===== Options =====
 
===== Options =====
−
* [[OJ_Break API Data Type Glossary#showSyns|showSyns]]
+
* inst_id
−
* taxonFormat - string
+
* widget_options
  
−
===== Additional Requirements =====
+
==== showSynonyms ====
−
None
 
−
 
 
−
==== showAssociations ====
 
 
===== Description =====
 
===== Description =====
−
 
+
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
 
===== Parameters =====
 
===== Parameters =====
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* tnuid
 
* options
 
* options
 
===== Options =====
 
===== Options =====
−
* rank_grouping - string
+
* show_fossils
−
* taxonFormat - string
+
* useTaxonItalics - boolean
 +
* limit - Number
 +
* offset - Number
 +
* widget_options
  
−
===== Additional Requirements =====
+
==== showTaxonMedia ====
−
None
 
−
 
 
−
==== showImages ====
 
 
===== Description =====
 
===== Description =====
−
Displays a table of all images associated to a specific taxon.
+
Displays a table of all media associated to a specific taxon rank.
−
 
 
 
===== Parameters =====
 
===== Parameters =====
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* tnuid
 
* options
 
* options
 
===== Options =====
 
===== Options =====
−
* type - string
+
* inst_id
−
* taxonFormat - string
+
* row_count - Number
−
 
+
* media_type
−
===== Additional Requirements =====
+
* limit - Number
−
None
+
* offset - Number
 +
* widget_options
  
 
==== showTypes ====
 
==== showTypes ====
 
===== Description =====
 
===== Description =====
−
 
+
Displays information and specimen types for a specified taxon.
 
===== Parameters =====
 
===== Parameters =====
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
 
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* tnuid
 
* options
 
* options
 
===== Options =====
 
===== Options =====
−
* [[OJ_Break API Data Type Glossary#showSyns|showSyns]] - Boolean_flag
+
* show_children
−
* [[OJ_Break API Data Type Glossary#inst_id|inst_id]] - number
+
* inst_id
 
* primary_only - Boolean_flag
 
* primary_only - Boolean_flag
−
* taxon_author_search - string
+
* basic_only - Boolean_flag
 
* offset - number
 
* offset - number
 
* limit - number
 
* limit - number
 
* useTaxonItalics - boolean
 
* useTaxonItalics - boolean
−
* taxonFormat - string
+
* widget_options
  
−
===== Additional Requirements =====
+
=== Visual ===
−
None
+
==== showGoogleMap ====
−
 
 
−
==== showDeterminers ====
 
 
===== Description =====
 
===== Description =====
−
 
+
A Google map which displays locality markers for a specified taxon.
 
===== Parameters =====
 
===== Parameters =====
−
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
+
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
 
* options
 
* options
 
===== Options =====
 
===== Options =====
−
* generalFormat - string
+
* place_id - Number
 +
* inst_id - Number
 +
* use_sex_icons - Boolean_flag
 +
* show_children - Boolean_flag
 +
* limit - Number
 +
* offset - Number
 +
* markers - Number
 +
* widget_options - Object
  
 
===== Additional Requirements =====
 
===== Additional Requirements =====
−
None
+
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
 +
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]
  
−
==== showCollectingMethods ====
+
==== showTaxonHierarchy ====
 
===== Description =====
 
===== Description =====
−
 
+
An interactive, tree-based animation which allows a user to navigate through a selected taxon's hierarchy and all taxa available through the OJ_Break API.
 
===== Parameters =====
 
===== Parameters =====
−
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
+
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
−
* [[OJ_Break API Data Type Glossary#tnuid_2|tnuid]]
+
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
 +
* requestedNode
 
* options
 
* options
 +
 
===== Options =====
 
===== Options =====
−
* generalFormat - string
+
* show_num_spms - Boolean_flag
 +
* inst_id - Number
 +
* show_syns - Boolean_flag
 +
* show_fossils - Boolean_flag
 +
* types_only - Boolean_flag
 +
* nodeColor - string or hexadecimal number
 +
* backgroundColor - string or hexadecimal number
 +
* handler_url - File path string/URL
 +
* size - JavaScript object with two string properties:
 +
** width - either a number or string in pixels
 +
** height - either a number of string in pixels
 +
* imagePath - string of relative path to a folder containing necessary images.
 +
* widget_options - Object
  
 
===== Additional Requirements =====
 
===== Additional Requirements =====
−
None
+
* [http://en.wikipedia.org/wiki/Processing.js Processing.js] 1.4.1+
 +
* Pass requestedNode parameter a value of '''null''' when calling function. See below:
 +
<span style="color:green;">// Load taxon hierarchy</span>
 +
visual.showTaxonHierarchy(<span style="color:green">'canvas_id'</span>, tnuid, <span style="color: red;">null</span>, {<span style="color: green;"> /*options*/ </span>});
 +
 
 +
===== Additional Information =====
 +
====== URL Handler Option ======
 +
The ''handler_url'' option can be used to allow the nodes to have links attached to them, so that a user may follow the link for more information on that specific taxon.
 +
 
 +
<span style="color:green;">// Load taxon hierarchy</span>
 +
visual.showTaxonHierarchy(<span style="color:green">'canvas_id'</span>, tnuid, <span style="color: red;">null</span>, {nodeColor: <span style="color: green">'cyan'</span>, backgroundColor: <span style="color: green">'#FFFFFF'</span>, handler_url: <span style="color: green">'<nowiki>http://hol.osu.edu/index.html</nowiki>'</span>});
 +
 
 +
In this example, a default web page URL is given (note the use of http:// at the beginning). When provided a URL, the taxon hierachy animation will present a link button to the top right of the node that is currently being highlighted (see image below). This link will not be present if a URL is not specified. If this button is clicked, the ''handler_url'' link will be followed.
 +
 
 +
====== Size Option ======
 +
The taxon hierarchy application can be resized in one of two ways: via [http://en.wikipedia.org/wiki/Cascading_Style_Sheets CSS] (preferred) or by inputting the dimensions of the HTML canvas into the API method call as options. One way this can be done is by specifying the width and height as numbers:
 +
 
 +
<span style="color:green;">// Load taxon hierarchy</span>
 +
visual.showTaxonHierarchy(<span style="color:green">'canvas_id'</span>, tnuid, <span style="color: red;">null</span>, {size: {width: <span style="color:purple;">300</span>, height: <span style="color:purple;">900</span>}});
 +
 
 +
The dimensions of the canvas can also be input as pixels:
 +
 
 +
<span style="color:green;">// Load taxon hierarchy</span>
 +
visual.showTaxonHierarchy(<span style="color:green">'canvas_id'</span>, tnuid, <span style="color: red;">null</span>, {size: {width: <span style="color:green;">"300px"</span>, height: <span style="color:green;">"900px"</span>}});
 +
 
 +
Both of these methods (CSS and parameter passing) are valid, but they should never both be used at the same time since unexpected errors may occur.
 +
 
 +
====== Image Path Option ======
 +
Due to security restrictions, Processingjs is limited in its function to request images. As a consequence, any user wishing to use the animation must have copies of the required images available locally on their server. To access these images, a relative directory path must be input in the form of a optional parameter. The call may look something like this:
 +
 
 +
<span style="color:green;">// Load taxon hierarchy</span>
 +
visual.showTaxonHierarchy(<span style="color:green">'canvas_id'</span>, tnuid, <span style="color: red;">null</span>, {imagePath: <span style="color:green">"media/images/"</span>});
  
 +
<hr>
 
<!--
 
<!--
 
==== methodName ====
 
==== methodName ====
Line 348: Line 519:
 
===== Additional Requirements =====
 
===== Additional Requirements =====
 
-->
 
-->
 +
 +
 +
 +
[[Category:xBioD Library]]
 +
[[Category:APIs]]
 +
 +
 +
Portions of this page are modifications based on work created and [https://developers.google.com/readme/policies/ shared by Google] and used according to terms described in the [http://creativecommons.org/licenses/by/3.0/ Creative Commons 3.0 Attribution License].

Latest revision as of 19:33, 22 July 2015

Introduction

The xBio:D JavaScript library offers the functionality to create rich, dynamic, and interactive features for use with the OJ_Break API. The OJ_Break API provides procedures to retrieve data within the xBio:D database, and the xBio:D JS library is how that data gets presented. Users planning on working with the xBio:D JS library should be familiar with JavaScript programming and object-oriented programming.

Contents

API Access

All functionality in the xBio:D JS library depends on access of data from the OJ_Break API. See OJ_Break API Access for an overview of the API and how to obtain an API access key.

Example

An easy way to become familiar with the xBio:D JS library is to see a simple example of a web application which uses two xBio:D methods. The first is a Google Maps widget which takes data from the OJ_Break method getLocalities for a specified tnuid and displays the data onto an interactive map. Read more about the Google Maps JavaScript API. The second method used in the example is a listing of included taxa for a specified tnuid by using the OJ_Break method getIncludedTaxa.

Simple example of web application.


There are a few things to note about this example:

  • The <!DOCTYPE html> tag is necessary for HTML 5 applications (line 1)
  • Jquery 1.8 library is included with a <script> tag (line 7)
  • Jquery UI 1.10.4 library is included with a <script> tag (line 8)
  • The Google Map API JavaScript library is included with a <script> tag (line 9)
  • The xBio:D JS library is included with a <script> tag (line 10)
  • A function called loader intializes the xBio:D resources when the web page has finished loading (line 15)
  • Two objects where created to access the xBio:D components called visual and taxon (line 22 - 23)
  • The applications are created by calling there respective methods via the xBio:D library components (line 26 & 29 - 30)
  • In the <body> there are two <div> elements which create areas to hold the widgets. The first is called map_id and the second is included_id. (line 43 - 44)


These steps will be explained below.


Declaring Application as HTML 5

It is recommended for any web application to be declared as a true DOCTYPE. This can easily be done by using the HTML 5 DOCTYPE as seen below. This allows the application to be more cross-browser compliant. Please refer to the Google Maps Documentation on HTML 5 for more info. 

<!DOCTYPE html>

Loading JQuery Library

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js"></script>

The URL in the <script> tag above is the location of the JavaScript file which allows JQuery 1.8 to run on the web application. JQuery is used in the xBio:D JS library to get methods from the OJ_Break API and other scripts. It is a necessary component of any web app that intends to use xBio:D functionality.

Loading the Google Maps API

<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?sensor=false"></script>

The URL in the <script> tag above is the location of the JavaScript file which will load all the necessary defintions to allow access to the Maps API. Normally, an access key would need to be provided in order to use the Maps library. See Loading the Maps API for more info. This script file is necessary for web apps that use Google Maps as part of the application. It is a necessary file to have in this simple example, but is not required for all xBio:D applications.

Loading the xBio:D JavaScript Library

<script type="text/javascript" src="http://xbiod.osu.edu/xbiod_lib/xbiod.js"></script>

The URL in the <script> tage above is the location of the xBio:D JavaScript Library which is a required file for this simple example and any web application that will be using xBio:D applications.

Initializing the xBio:D JS Library

<script>
    // Call the loader for the current page
    $(document).ready(loader);

        function loader() {

            // Initialize xBio:D library
            xbiod.init(['visual','taxon'], /*API_KEY*/, function(){

To begin using the xBio:D library, first the components need to be loaded. This is done through the xBio:D init function which takes three parameters: an array of the components to be loaded, an API access key, and a callback function. In this example, the visual and taxon resources are passed to the init function for loading (all resources and their methods can be found in the Reference section below). This example also shows where a user would provide an OJ_Break API access key. See OJ_Break API Access for more information on access keys. Lastly, a callback method needs to be provided which will create the component objects.

Component Objects

// Load xBio:D components
var visual = new xbiod.visual();
var taxon = new xbiod.taxon();

An object derived from a class is instatiated using the new keyword and a namespace's constructor. The JavaScript namespace that represents the xBio:D visual applications is the visual namespace/component and similarly the namespace that represents the xBio:D taxon applications is the taxon namespace/component. Access to functionality from either of these components requires an object with a reference to that component. These objects allow methods from each component to be called to the web page.

Calling Application Methods

// Load map
visual.showGoogleMap('map_id', tnuid);
		
// Load included taxa
taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y', taxonFormat: '<a href="test.html?tnuid=%tnuid%">%taxon%</a> %author% - %num_spms%'});

Each application has a method associated with it which takes several parameters which will dictate what data it loads, where it will be contained, and options for how it should be presented. These methods and requirements can be found in the Reference section.

In the above example, the visual method showGoogleMap gets passed a <div> element ID string which decides where it will be contained and a tnuid which will dictate which taxon data the map will locate.

The taxon method showIncludedTaxa gets passed similar parameters (a specified <div> element ID string and a tnuid) however it also gets additional options in the form of a JavaScript object literal. In this example, the option show_num_spms is given the Boolean_flag 'Y' signifying that the application should display the number of specimens for that particular taxon and taxonFormat is assigned to present the data as links using the <a> tag.

Element Containers

Each method requires one or more unique <div> tag IDs as string parameters (seen in the example <body> below). This will be used to specify where the resource will be contained in the web page. 

<body>
    <div id="map_id"/>
    <div id="included_id"/>
</body>

Reference

Agent

showAgentInfo

Description

Displays information about an agent, including name, contact information, and a short biography.

Parameters
Options
  • widget_options - Object

showAgentOccurrences

Description

Displays collected occurrences for a specified agent on a Google Map. Creates two windows.

Parameters
  • element_id (?)
  • agent_id (?)
  • options
Options
  • info_element_id - ID String (defaults to element_id parameter)
  • generalFormat - HTML String
  • markers - String ('spiderfy' or undefined). Requires additional dependencies (see below).
  • offset - Number
  • limit - Number
  • icons - Object
  • widget_options
Additional Requirements

showAgentOccurrenceLocalityInfo

Description

Displays locality information for a certain agent's collecting occurrence.

Parameters
  • element_id (?)
  • loc_id (?)
  • options
Options

None

showDescribedTaxa

Description

Displays all taxa described by the specified agent.

Parameters
  • element_id (?)
  • author_id (?)
  • options
Options
  • taxonFormat - String
  • useTaxonItalics - Boolean
  • limit - Number
  • offset - Number
  • widget_options - Object

showPublications

Description

Displays all publications for a specified agent.

Parameters
  • element_id (?)
  • author_id (?)
  • options
Options
  • limit - Number
  • offset - Number
  • widget_options - Object

Occurrence

showBiologicalInfo

Description

Displays both the habitat and associations for a selected occurrence identifier.

Parameters
  • element_id (?)
  • occurrence_id (?)
  • options
Options
  • widget_options - Object

showOccurrenceInfo

Description

Displays collecting trip info for a specified occurrence.

Parameters
  • element_id (?)
  • occurrence_id (?)
  • options
Options
  • widget_options - Object

showDeterminations

Description

Displays determinations for a specified occurence.

Parameters
  • element_id (?)
  • occurrence_id (?)
  • options
Options
  • widget_options - Object

showLocalityInfo

Description

Displays locality info for a specified occurrence.

Parameters
  • element_id (?)
  • occurrence_id (?)
  • options
Options
  • widget_options - Object

showSpecimenInfo

Description

Displays specimen info for a specified occurrence.

Parameters
  • element_id (?)
  • occurrence_id (?)
  • options
Options
  • widget_options - Object

Search

showSearch

Description

A JQuery UI autocomplete search bar which can search for taxa, occurrences, institutions, agents, journals, localities, and places.

Parameters
  • element_id
  • options
Options
  • search - the type of search to execute. Controls the passing of URL parameters to methods. Can be specified a either 'id' or 'name'. Defaults to 'id'
  • domains - array of the below object elements
    • type - a domain keyword for which data gets searched for
    • handler_url - a URL that will be passed the ID of the selected type option
Additional Information
Category Options Formatting

Below is an example of how the categories should be input: 

// Load search
search.showSearch('search_id', {domains: [{type: 'taxon', handler_url: 'http://domain.url/index.html'}, {type: 'occurrence', handler_url: 'http://domain.url/occurrence.html'}]});

Taxon

showAssociations

Description

Displays all associations for a specified taxon.

Parameters
Options
  • basic_only - Boolean_flag
  • limit - Number
  • offset - Number
  • widget_options

showInstitutions

Description

Displays institutions for which specimens of the selected taxon level belong.

Parameters
Options
  • limit - Number
  • offset - Number
  • widget_options - Object

showContributors

Description

Displays all contributing agents related to the occurrence, taxonomy, literature, and media of a taxon.

Parameters
Options
  • inst_id
  • widget_options

showDeterminers

Description

Displays determiners for a specified taxon.

Parameters
Options
  • limit - Number
  • offset - Number
  • inst_id
  • widget_options

showHabitats

Description

Displays all identified habitats for a selected taxon.

Parameters
Options
  • limit - Number
  • offset - Number
  • widget_options

showIncludedTaxa

Description

Displays taxa directly included within a taxon but not synonymous with it.

Parameters
Options
  • inst_id
  • show_syns
  • show_fossiles
  • types_only
  • useTaxonItalics - Boolean
  • limit - Number
  • offset - Number
  • widget_options

showLiterature

Description

Displays relevent publications for a specified taxon with links to the literature when available.

Parameters
Options
  • show_children - Boolean_flag
  • show_bib - Boolean_flag
  • useTaxonItalics - Boolean
  • limit - Number
  • offset - Number
  • widget_options

showSubordinateTaxa

Description

Displays the count of valid taxa levels available below the current taxon rank.

Parameters
Options
  • inst_id
  • widget_options

showSynonyms

Description

Displays all taxa which are objectively or subjectively synonymous with a selected taxon.

Parameters
Options
  • show_fossils
  • useTaxonItalics - boolean
  • limit - Number
  • offset - Number
  • widget_options

showTaxonMedia

Description

Displays a table of all media associated to a specific taxon rank.

Parameters
Options
  • inst_id
  • row_count - Number
  • media_type
  • limit - Number
  • offset - Number
  • widget_options

showTypes

Description

Displays information and specimen types for a specified taxon.

Parameters
Options
  • show_children
  • inst_id
  • primary_only - Boolean_flag
  • basic_only - Boolean_flag
  • offset - number
  • limit - number
  • useTaxonItalics - boolean
  • widget_options

Visual

showGoogleMap

Description

A Google map which displays locality markers for a specified taxon.

Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • place_id - Number
  • inst_id - Number
  • use_sex_icons - Boolean_flag
  • show_children - Boolean_flag
  • limit - Number
  • offset - Number
  • markers - Number
  • widget_options - Object
Additional Requirements

showTaxonHierarchy

Description

An interactive, tree-based animation which allows a user to navigate through a selected taxon's hierarchy and all taxa available through the OJ_Break API.

Parameters
  • element_id (?)
  • tnuid (?)
  • requestedNode
  • options
Options
  • show_num_spms - Boolean_flag
  • inst_id - Number
  • show_syns - Boolean_flag
  • show_fossils - Boolean_flag
  • types_only - Boolean_flag
  • nodeColor - string or hexadecimal number
  • backgroundColor - string or hexadecimal number
  • handler_url - File path string/URL
  • size - JavaScript object with two string properties:
    • width - either a number or string in pixels
    • height - either a number of string in pixels
  • imagePath - string of relative path to a folder containing necessary images.
  • widget_options - Object
Additional Requirements
  • Processing.js 1.4.1+
  • Pass requestedNode parameter a value of null when calling function. See below:
// Load taxon hierarchy
visual.showTaxonHierarchy('canvas_id', tnuid, null, { /*options*/ });
Additional Information
URL Handler Option

The handler_url option can be used to allow the nodes to have links attached to them, so that a user may follow the link for more information on that specific taxon. 

// Load taxon hierarchy
visual.showTaxonHierarchy('canvas_id', tnuid, null, {nodeColor: 'cyan', backgroundColor: '#FFFFFF', handler_url: 'http://hol.osu.edu/index.html'});

In this example, a default web page URL is given (note the use of http:// at the beginning). When provided a URL, the taxon hierachy animation will present a link button to the top right of the node that is currently being highlighted (see image below). This link will not be present if a URL is not specified. If this button is clicked, the handler_url link will be followed.

Size Option

The taxon hierarchy application can be resized in one of two ways: via CSS (preferred) or by inputting the dimensions of the HTML canvas into the API method call as options. One way this can be done is by specifying the width and height as numbers: 

// Load taxon hierarchy
visual.showTaxonHierarchy('canvas_id', tnuid, null, {size: {width: 300, height: 900}});

The dimensions of the canvas can also be input as pixels: 

// Load taxon hierarchy
visual.showTaxonHierarchy('canvas_id', tnuid, null, {size: {width: "300px", height: "900px"}});

Both of these methods (CSS and parameter passing) are valid, but they should never both be used at the same time since unexpected errors may occur.

Image Path Option

Due to security restrictions, Processingjs is limited in its function to request images. As a consequence, any user wishing to use the animation must have copies of the required images available locally on their server. To access these images, a relative directory path must be input in the form of a optional parameter. The call may look something like this: 

// Load taxon hierarchy
visual.showTaxonHierarchy('canvas_id', tnuid, null, {imagePath: "media/images/"});


Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License.

Retrieved from "https://xbiod.osu.edu/index.php?title=XBio:D_Javascript_Library_Reference&oldid=2143"