XBio:D Javascript Library Reference

From xBio:D Wiki
Revision as of 16:48, 26 August 2014 by Tyler (talk | contribs) (→‎Component Objects)
Jump to navigation Jump to search

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

  <!DOCTYPE HTML>
   <html>
   <head>
	<meta charset="UTF-8"/>
	<title>xBio:D API test</title>
	<link rel="stylesheet" type="text/css" href="xbiod.css">
	<script type="text/javascript">
		src="http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js"
	</script>
	<script type="text/javascript">
		src="https://maps.googleapis.com/maps/api/js?sensor=false"
	</script>
	<script  type="text/javascript" src="http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"></script>
	<script>
		// Call the loader for the current page
		$(document).ready(loader);

		function loader() {

			// Initialize xBio:D library
			xbiod.init(['visual','taxon'], '{API_KEY}', function() {
				var tnuid = 605;

				// Load xBio:D components
				var visual = new xbiod.visual();
				var taxon = new xbiod.taxon();
		
				// 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%'
				});
			});
		}
	</script>
        <style  type="text/css">
		html { height: 100% }
		body { height: 100%; margin: 0; padding: 0 }
		#map_id { height: 50% }
		#included_id { height: 50% }
        </style>
    </head>
    <body>
	<div id="map_id"/>
	<div id="included_id"/>
    </body>
    </html>

View simple example here (test.html)


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 - 9)
  • The Google Map API JavaScript library is included with a <script> tag (line 10 - 12)
  • The xBio:D JS library is included with a <script> tag (line 13)
  • A function called loader intializes the xBio:D resources when the web page has finished loading (line 16)
  • Two objects where created to access the xBio:D components called visual and taxon (line 25 - 26)
  • The applications are created by calling there respective methods via the xBio:D library components (line 29 & 32 - 33)
  • 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 40 - 41)


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://osuc.biosci.ohio-state.edu/JSLib/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 namespace 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, 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 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 unique <div> 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. 

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

Reference

Person

showCollectingTripLocalityInfo

Description
Parameters
  • element_id (?)
  • loc_id (?)
  • per_id (?)
  • options
Options
  • tnuid (?) - number
  • inst_id (?) - number
  • pnid (?) - number
  • showChildren (?) - Boolean_flag
  • completeSpmInfo - Boolean_flag
  • generalFormat - string


showCollectingTrips

Description
Parameters
  • element_id (?)
  • collector_id (?)
  • options
Options
  • generalFormat - string
Additional Requirements


showDescribedTaxa

Description
Parameters
  • element_id (?)
  • author_id (?)
  • options
Options
  • taxonFormat - string


showPublications

Description
Parameters
  • element_id (?)
  • author_id (?)
  • options
Options

None

Record

showBiologicalInfo

Description
Parameters
  • element_id (?)
  • cuid (?)
  • options
Options
  • generalFormat - string


showCollectingTripsInfo

Description
Parameters
  • element_id (?)
  • cuid (?)
  • options
Options
  • generalFormat - string


showDeterminations

Description
Parameters
  • element_id (?)
  • cuid (?)
  • options
Options
  • generalFormat - string


showLocalityInfo

Description
Parameters
  • element_id (?)
  • cuid (?)
  • options
Options
  • generalFormat - string


showSpecimenInfo

Description
Parameters
  • element_id (?)
  • cuid (?)
  • options
Options
  • generalFormat - string

Taxon

showAssociations

Description
Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • rank_grouping - string
  • taxonFormat - string


showCollections

Description

Displays all collections for which specimen of the selected taxon belong.

Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • generalFormat - string


showCollectingMethods

Description
Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • generalFormat - string


showContributors

Description
Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • inst_id (?)
  • generalFormat - string


showDeterminers

Description
Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • generalFormat - string


showHabitats

Description

Displays all identified habitats for a selected taxon.

Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • generalFormat - string


showIncludedTaxa

Description

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

Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • inst_id (?) - number
  • showSyns (?) - Boolean_flag
  • showFossils (?) - Boolean_flag
  • types_only (?) - Boolean_flag
  • show_num_spms (?) - Boolean_flag
  • taxonFormat - string
  • useTaxonItalics - boolean


showLiterature

Description

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

Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • showSyns (?)
  • taxonFormat - string
  • useTaxonItalics - boolean


showSubordinateTaxa

Description
Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • inst_id (?)
  • generalFormat - string


showSynonyms

Description

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

Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • showFossils (?) - Boolean_flag
  • taxonFormat - string
  • useTaxonItalics - boolean


showTaxonImages

Description

Displays a table of all images associated to a specific taxon.

Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • type - string
  • taxonFormat - string


showTypes

Description
Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • showSyns (?) - Boolean_flag
  • inst_id (?) - number
  • primary_only - Boolean_flag
  • taxon_author_search - string
  • offset - number
  • limit - number
  • useTaxonItalics - boolean
  • taxonFormat - string

Visual

showGoogleMap

Description
Parameters
  • element_id (?)
  • tnuid (?)
  • options
Options
  • pnids (?) - array of number
  • inst_id (?) - number
  • precDecimals (?) - number
  • showChildren (?) - Boolean_flag
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
  • showSyns (?) - Boolean_flag
  • showFossils (?) - Boolean_flag
  • typesOnly (?) - Boolean_flag
  • node_color - string or hexadecimal number
  • background_color - string or hexadecimal number
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, {backgroundColor: 'black'});
Retrieved from "https://xbiod.osu.edu/index.php?title=XBio:D_Javascript_Library_Reference&oldid=1244"