xBio:D Wiki - User contributions [en]

OJ Break v2 Taxon Reference

2015-09-25T13:44:25Z

Tyler: /* TaxonReturnIncluded (extends TaxonReturn) */

'''Introduction'''

OJ_Break is the name of the xBio:D RESTful API service to facilitate discovery of data within the xBio:D database. The API can respond with HTML, JSON, XML, or JSON with padding (JSONP) and accepts HTTP GET and POST requests indiscriminately. The backend of the API is written in Oracle's PL/SQL database language, which is fast but often inflexible, while a Python presentation layer mitigates request handling and authentication.

OJ_Break Version 2 is a new and improved edition of the work started in Version 1. Version 2 introduces a completely restructured and standardized data model to further enhance the functionality of the xBio:D database.

== API Information and Access ==
This page specifies the methods and data defined by OJ_Break Version 2, more precisely those that are defined by the '''Taxon''' data domain. To get information on any of the other data domains defined in OJ_Break Version 2, visit the [[#See_also|See also]] section.

Using the OJ_Break Version 2 API requires calling methods with corresponding, method specific parameters (found on this page) and a few other required parameters. These required parameters include specifying a return ''format'', an API access ''key'', and a ''version'' number.

Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

Notice the specification of the ''version'' parameter at the end of the example method call. With the introduction of OJ_Break Version 2, the ''version'' parameter has a default value of ''2'' making the specification in the example unnecessary. To read more about using the OJ_Break Version 2 API, go to [[OJ_Break API Access]].

[[File:OJ_Break Data Model - Taxon.png|none|frame|Taxon Data Model]]

== Procedural Reference ==
=== Taxon ===
==== getTaxonInfo ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonComplete (extends TaxonRelationship)|TaxonComplete]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonInfo?tnuid=30148&inst_id=1&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonHierarchy ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonHierarchy?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonIncludedTaxa ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*rank'': [[#rank|rank]]
* ''*offset'': Number
* ''*limit'': Number
* ''*show_syns'': Boolean_flag
* ''*show_fossils'': Boolean_flag
* ''*types_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnIncluded (extends TaxonReturn)|TaxonReturnIncluded]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonIncludedTaxa?tnuid=30148&inst_id=1&show_syns=Y&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonSynonyms ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_fossils'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnSynonyms (extends TaxonReturn)|TaxonReturnSynonyms]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonSynonyms?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonAssociations ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*basic_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number

===== Return =====
* [[#TaxonReturnAssociations (extends TaxonReturn)|TaxonReturnAssociations]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonAssociations?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonLiteratureCitations ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_children'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnLiteratureCitations (extends TaxonReturn)|TaxonReturnLiteratureCitations]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonLiteratureCitations?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonOccurrences ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*place_id'': ''[[OJ_Break v2 Geographic Place Reference#place_id|place_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_children'': Boolean_flag
* ''*basic_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnOccurrences (extends TaxonReturn)|TaxonReturnOccurrences]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonOccurrences?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonTypes ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*basic_only'': Boolean_flag
* ''*show_children'': Boolean_flag
* ''*primary_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnOccurrences (extends TaxonReturn)|TaxonReturnOccurrences]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonTypes?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonLocalities ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*place_id'': [[OJ_Break v2 Geographic Place Reference#place_id|place_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_children'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnLocalities (extends TaxonReturn)|TaxonReturnLocalities]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonLocalities?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonDeterminers ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnDeterminers (extends TaxonReturn)|TaxonReturnDeterminers]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonDeterminers?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonInstitutions ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnInstitutions (extends TaxonReturn)|TaxonReturnInstitutions]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonInstitutions?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonHabitats ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnHabitats (extends TaxonReturn)|TaxonReturnHabitats]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonHabitats?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonMedia ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*media_type'': ''media_type''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnMedia (extends TaxonReturn)|TaxonReturnMedia]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonMedia?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

== Taxon Data Type Glossary ==
=== Classes ===
==== TaxonAssociation ====
* ''assoc_taxon'': [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]
* ''assoc_type'': ''[[#assoc_type|assoc_type]]''
* ''assoc_type_full'': ''[[#assoc_type_full|assoc_type_full]]''
* ''assoc_occurrences'': array of [[OJ_Break v2 Occurrence Reference#OccurrenceBasic|OccurrenceBasic]]

==== TaxonBasic ====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''guid'': ''[[#guid|guid]]''
* ''tcid'': ''[[#tcid|tcid]]''
* ''taxon'': ''[[#taxon|taxon]]''
* ''taxon_author'': ''[[#taxon_author|taxon_author]]''

==== TaxonComplete (extends [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]) ====
* ''stats'': [[#TaxonInfoStats (extends TaxonStats)|TaxonInfoStats]]
* ''contribs'': array of Contribution
* ''orig_desc'': [[OJ_Break v2 Literature Reference#LiteratureExtended|LiteratureExtended]]

==== TaxonExtended (extends [[#TaxonBasic|TaxonBasic]]) ====
* ''describer'': ''[[#describer|describer]]''
* ''status'': ''[[#status|status]]''
* ''valid'': ''[[#valid|valid]]''
* ''rank'': ''[[#rank|rank]]''
* ''valid_taxon'': [[#TaxonBasic|TaxonBasic]]
* ''fossil'': ''[[#fossil|fossil]]''
* ''homonym'': ''[[#homonym|homonym]]''
* ''common_names'': array of ''[[#common_name|common_name]]''
* ''source'': [[#TaxonSource|TaxonSource]]

==== TaxonHierarchy ====
Aggregate of one or more of the following classes:
* [[#TaxonHierKingdom|TaxonHierKingdom]] (1)
* [[#TaxonHierPhylum|TaxonHierPhylum]] (0 or 1)
* [[#TaxonHierDivision|TaxonHierDivision]] (0 or 1)
* [[#TaxonHierSubphylum|TaxonHierSubphylum]] (0 or 1)
* [[#TaxonHierClass|TaxonHierClass]]'' (0 or 1)
* [[#TaxonHierSubclass|TaxonHierSubclass]] (0 or 1)
* [[#TaxonHierInfraclass|TaxonHierInfraclass]] (0 or 1)
* [[#TaxonHierOrder|TaxonHierOrder]] (0 or 1)
* [[#TaxonHierSuborder|TaxonHierSuborder]] (0 or 1)
* [[#TaxonHierInfraorder|TaxonHierInfraorder]] (0 or 1)
* [[#TaxonHierCohort|TaxonHierCohort]] (0 or 1)
* [[#TaxonHierSubcohort|TaxonHierSubcohort]] (0 or 1)
* [[#TaxonHierSuperfamily|TaxonHierSuperfamily]] (0 or 1)
* [[#TaxonHierFamily|TaxonHierFamily]] (0 or 1)
* [[#TaxonHierSubfamily|TaxonHierSubfamily]] (0 or 1)
* [[#TaxonHierTribe|TaxonHierTribe]] (0 or 1)
* [[#TaxonHierSubtribe|TaxonHierSubtribe]] (0 or 1)
* [[#TaxonHierGenus|TaxonHierGenus]] (0 or 1)
* [[#TaxonHierSpecies|TaxonHierSpecies]] (0 or 1)
* [[#TaxonHierSubspecies|TaxonHierSubspecies]] (0 or 1)

==== TaxonHierClass ====
* ''Class'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierCohort ====
* ''Cohort'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierDivision ====
* ''Division'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierFamily ====
* ''Family'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierGenus ====
* ''Genus'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierInfraclass ====
* ''Infraclass'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierInfraorder ====
* ''Infraorder'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierKingdom ====
* ''Kingdom'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierOrder ====
* ''Order'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierPhylum ====
* ''Phylum'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSpecies ====
* ''Species'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubclass ====
* ''Subclass'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubcohort ====
* ''Subcohort'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubfamily ====
* ''Subfamily'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSuborder ====
* ''Suborder'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubphylum ====
* ''Subphylum'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubspecies ====
* ''Subspecies'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubtribe ====
* ''Subtribe'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSuperfamily ====
* ''Superfamily'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierTribe ====
* ''Tribe'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierUnit (extends [[#TaxonBasic|TaxonBasic]]) ====
* ''next'': [[#rank|''rank'']]

==== TaxonInfoStats (extends [[#TaxonStats|TaxonStats]]) ====
* ''child_stats'': array of [[#TaxonStats|TaxonStats]]
* ''num_records'': Number
* ''num_spms'': Number

==== TaxonRelationship (extends [[#TaxonExtended (extends TaxonBasic)|TaxonExtended]]) ====
* ''rel_type'': ''[[#rel_type|rel_type]]''
* ''parent_taxon'': [[#TaxonExtended|TaxonBasic]]
* ''hier'': [[#TaxonHierarchy|TaxonHierarchy]]

==== TaxonReturn ====
* ''general'': [[#TaxonBasic|TaxonBasic]]

==== TaxonReturnAssociations (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''associations'': array of [[#TaxonAssociation|TaxonAssociation]]

==== TaxonReturnDeterminers (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''determiners'': array of [[#TaxonExtended (extends TaxonBasic)|AgentExtended]]

==== TaxonReturnHabitats (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''hatitats'': array of [[#habitat|''habitat'']]

==== TaxonReturnIncluded (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''includedTaxa'': array of [[#TaxonExtended (extends TaxonBasic)|TaxonExtended]]

==== TaxonReturnInstitutions (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''institutions'': array of [[OJ_Break v2 Institution Reference#InstitutionBasic|InstitutionBasic]]

==== TaxonReturnLiteratureCitations (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''pub_citations'': array of [[OJ_Break v2 Literature Reference#LiteratureTaxonCitationExtended|LiteratureTaxonCitationExtended]]

==== TaxonReturnLocalities (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''localities'': array of [[OJ_Break v2 Locality Reference#LocalityExtended|LocalityExtended]]

==== TaxonReturnMedia (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''media'': array of [[OJ_Break v2 Media Reference#MediaExtended (extends MediaBasic)|MediaExtended]]

==== TaxonReturnOccurrences (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''occurrences'': array of [[OJ_Break v2 Occurrence Reference#OccurrenceExtended|OccurrenceExtended]]

==== TaxonReturnSynonyms (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''synonyms'': array of [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]

==== TaxonSource ====
* ''id'': Number
* ''name'': String
* ''logo'': URL
* ''url'': URL
* ''query'': URL

==== TaxonStats ====
* ''rank'': ''[[#rank|rank]]''
* ''rank_value'': ''[[#rank_value|rank_value]]''
* ''num_taxa'': Number

=== Elements ===
==== assoc_type ====
String - A description of the biological relationship between a specified taxon and another organism.
==== assoc_type_full ====
String - A complete description of the biological relationship between a specified taxon and another organism.
==== common_name ====
String - A common name for a taxon that can be included as a taxon name string but is never valid.
==== describer ====
String - the describer(s) of a taxon.
==== fossil ====
String - A modified boolean_flag, either Y, N or B, representing whether a taxon name is a extinct fossil, exclusively extant, or present today and in fossils.
==== guid ====
String - A globally unique identifier for an xBio:D domain resource in the form of a stable URI dereferenced by the ''bioguid.osu.edu'' domain.
==== habitat ====
String - Description or identifier of the ecological or environmental area that a particular species is known to inhabit.
==== homonym ====
Boolean_flag - Boolean_flag indicating whether or not the determination was a homonym
==== rank ====
String - The taxonomic (hierarchical) rank of a taxon name.
==== rank_value ====
Number - A number representing the rank of a taxon with higher numbers representing higher positions in the taxonomic hierarchy.
==== rel_type ====
String - The taxonomic (hierarchical) relationship between the taxonomic concept indicated by the taxon name and its parent taxonomic concept. Can be Member, Junior synonym, etc.
==== status ====
String - The nomenclatural status of a taxon name using a formalized vocabulary.
==== taxon ====
String - A taxon name string.
==== taxon_author ====
String - The author(s) of a taxon with parenthesis surrounding the name of the author(s) if necessary.
==== tcid ====
Number - The taxonomic concept identifier which uniquely identifies a taxon concept, which may have many name uses, within xBio:D.
==== tnuid ====
Number - The taxon name use identifier which uniquely identifies a taxon within xBio:D.
==== valid ====
String - A ''Valid'' or ''Invalid'' string representing the validity of a taxon name using subjective interpretations if warranted.

== See also ==
Visit any of the below links to find information about the other data domains defined by OJ_Break Version 2.

* [[OJ_Break v2 Agent Reference|Agent]]
* [[OJ_Break v2 Geographic Place Reference|Geographic Place]]
* [[OJ_Break v2 Institution Reference|Institution]]
* [[OJ_Break v2 Journal Reference|Journal]]
* [[OJ_Break v2 Literature Reference|Literature]]
* [[OJ_Break v2 Locality Reference|Locality]]
* [[OJ_Break v2 Media Reference|Media]]
* [[OJ_Break v2 Occurrence Reference|Occurrence]]
* [[OJ_Break v2 Search Reference|Search]]

XBio:D Javascript Library Reference

2015-05-01T21:17:07Z

Tyler:

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

== 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 [[OJ_Break API Access#key|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 [[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:wiki-test.png|alt=source code for a simple xBio:D web application.|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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* 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 =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* 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 =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* 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 =====
* [http://en.wikipedia.org/wiki/Processing.js 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-05-01T18:52:46Z

Tyler: /* Example */

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

== 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 [[OJ_Break API Access#key|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 [[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:wiki-test.png|alt=source code for a simple xBio:D web application.|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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster'). Require additional dependencies (see below).
* offset - Number
* limit - Number
* icons - Object
* widget_options

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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 =====
* [http://en.wikipedia.org/wiki/Processing.js 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-05-01T18:50:22Z

Tyler:

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

== 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 [[OJ_Break API Access#key|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 [[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]].





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

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster'). Require additional dependencies (see below).
* offset - Number
* limit - Number
* icons - Object
* widget_options

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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 =====
* [http://en.wikipedia.org/wiki/Processing.js 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-27T19:37:41Z

Tyler:

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster'). Require additional dependencies (see below).
* offset - Number
* limit - Number
* icons - Object
* widget_options

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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 =====
* [http://en.wikipedia.org/wiki/Processing.js 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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:

// 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/"});

<hr>


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

OJ Break v2 Occurrence Reference

2015-04-27T17:58:57Z

Tyler: /* Elements */

OJ Break v2 Occurrence Reference

2015-04-27T17:56:05Z

Tyler: /* Elements */

OJ Break v2 Media Reference

2015-04-27T17:44:51Z

Tyler: /* part */

'''Introduction'''

OJ_Break is the name of the xBio:D RESTful API service which enables the discovery of data within the xBio:D database. The API can respond with HTML, JSON, XML, or JSON with padding (JSONP) and accepts HTTP GET and POST requests indiscriminately. The backend of the API is written in Oracle's PL/SQL database language, which is fast but often inflexible, while a Python presentation layer mitigates request handling and authentication.

OJ_Break Version 2 is a new and improved edition of the work started in Version 1. Version 2 introduces a completely restructured and standardized data model to further enhance the functionality of the xBio:D database.

== API Information and Access ==
This page specifies the data defined by OJ_Break Version 2, more precisely those that are defined by the '''Media''' data domain. To get information on any of the other data domains defined in OJ_Break Version 2, visit the [[#See_also|See also]] section.

== Media Data Type Glossary ==
=== Classes ===
==== ImageExtended (extends [[#MediaExtended (extends MediaBasic)|MediaExtended]]) ====
* ''thumb'': URL
* ''raw'': URL

==== LocalityImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''locality'': [[OJ_Break v2 Locality Reference#LocalityBasic|LocalityBasic]]

==== MediaBasic ====
* ''media_id'': ''[[#media_id|media_id]]''
* ''media_type'': ''[[#media_type|media_type]]''
* ''media_url'': ''[[#media_url|media_url]]''
* ''media_source'': ''[[#media_source|media_source]]''
* ''public'': ''[[#public|public]]''

==== MediaExtended (extends [[#MediaBasic|MediaBasic]]) ====
* ''caption'': ''[[#caption|caption]]''
* ''copyright'': ''[[#copyright|copyright]]''
* ''license'': ''[[#license|license]]''
* ''enterer'': ''[[#enterer|enterer]]''

==== OccurrenceImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''occurrence'': [[OJ_Break v2 Occurrence Reference#OccurrenceTrimmed (extends OccurrenceBasic)|OccurrenceTrimmed]]
* ''parts'': array of ''[[#part|part]]''
* ''angle'': ''[[#angle|angle]]''
* ''technique'': ''[[#technique|technique]]''
* ''notes'': String

==== OccurrenceRecordingExtended (realizes [[#MediaExtended (extends MediaBasic)|MediaExtended]]) ====
* ''occurrence'': [[OJ_Break v2 Occurrence Reference#OccurrenceTrimmed|OccurrenceTrimmed]]

==== TaxonImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''taxon'': [[OJ_Break v2 Taxon Reference#TaxonBasic|TaxonBasic]]

==== VideaExtended (realizes [[#ImageExtended extends MediaExtended)|ImageExtended]]) ====
* ''taxon'': [[OJ_Break v2 Taxon Reference#TaxonBasic|TaxonBasic]]

=== Elements ===
==== angle ====
String - A description of the angle the media was taken.
==== caption ====
String - A summary of the media.
==== copyright ====
String - Copyright information.
==== enterer ====
String - The media enterer's name.
==== license ====
String - Licensing information.
==== media_id ====
Number - A numeric identifier that uniquely identifies a media piece.
==== media_source ====
String - The name of the source of the media.
==== media_type ====
String - A description of the type of the media.
==== media_url ====
URL - The location to the media file.
==== part ====
String - A description of the body part of the specimen the image shows.

==== public ====
Boolean_flag - A flag that specifies whether or not the media is public.
==== technique ====
String - A description of the method by which the media was taken.

== See also ==
Visit any of the below links to find information about the other data domains defined by OJ_Break Version 2.

* [[OJ_Break v2 Agent Reference|Agent]]
* [[OJ_Break v2 Geographic Place Reference|Geographic Place]]
* [[OJ_Break v2 Institution Reference|Institution]]
* [[OJ_Break v2 Journal Reference|Journal]]
* [[OJ_Break v2 Literature Reference|Literature]]
* [[OJ_Break v2 Locality Reference|Locality]]
* [[OJ_Break v2 Occurrence Reference|Occurrence]]
* [[OJ_Break v2 Search Reference|Search]]
* [[OJ_Break v2 Taxon Reference|Taxon]]

OJ Break v2 Media Reference

2015-04-27T17:36:30Z

Tyler: /* Elements */

'''Introduction'''

OJ_Break is the name of the xBio:D RESTful API service which enables the discovery of data within the xBio:D database. The API can respond with HTML, JSON, XML, or JSON with padding (JSONP) and accepts HTTP GET and POST requests indiscriminately. The backend of the API is written in Oracle's PL/SQL database language, which is fast but often inflexible, while a Python presentation layer mitigates request handling and authentication.

OJ_Break Version 2 is a new and improved edition of the work started in Version 1. Version 2 introduces a completely restructured and standardized data model to further enhance the functionality of the xBio:D database.

== API Information and Access ==
This page specifies the data defined by OJ_Break Version 2, more precisely those that are defined by the '''Media''' data domain. To get information on any of the other data domains defined in OJ_Break Version 2, visit the [[#See_also|See also]] section.

== Media Data Type Glossary ==
=== Classes ===
==== ImageExtended (extends [[#MediaExtended (extends MediaBasic)|MediaExtended]]) ====
* ''thumb'': URL
* ''raw'': URL

==== LocalityImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''locality'': [[OJ_Break v2 Locality Reference#LocalityBasic|LocalityBasic]]

==== MediaBasic ====
* ''media_id'': ''[[#media_id|media_id]]''
* ''media_type'': ''[[#media_type|media_type]]''
* ''media_url'': ''[[#media_url|media_url]]''
* ''media_source'': ''[[#media_source|media_source]]''
* ''public'': ''[[#public|public]]''

==== MediaExtended (extends [[#MediaBasic|MediaBasic]]) ====
* ''caption'': ''[[#caption|caption]]''
* ''copyright'': ''[[#copyright|copyright]]''
* ''license'': ''[[#license|license]]''
* ''enterer'': ''[[#enterer|enterer]]''

==== OccurrenceImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''occurrence'': [[OJ_Break v2 Occurrence Reference#OccurrenceTrimmed (extends OccurrenceBasic)|OccurrenceTrimmed]]
* ''parts'': array of ''[[#part|part]]''
* ''angle'': ''[[#angle|angle]]''
* ''technique'': ''[[#technique|technique]]''
* ''notes'': String

==== OccurrenceRecordingExtended (realizes [[#MediaExtended (extends MediaBasic)|MediaExtended]]) ====
* ''occurrence'': [[OJ_Break v2 Occurrence Reference#OccurrenceTrimmed|OccurrenceTrimmed]]

==== TaxonImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''taxon'': [[OJ_Break v2 Taxon Reference#TaxonBasic|TaxonBasic]]

==== VideaExtended (realizes [[#ImageExtended extends MediaExtended)|ImageExtended]]) ====
* ''taxon'': [[OJ_Break v2 Taxon Reference#TaxonBasic|TaxonBasic]]

=== Elements ===
==== angle ====
String - A description of the angle the media was taken.
==== caption ====
String - A summary of the media.
==== copyright ====
String - Copyright information.
==== enterer ====
String - The media enterer's name.
==== license ====
String - Licensing information.
==== media_id ====
Number - A numeric identifier that uniquely identifies a media piece.
==== media_source ====
String - The name of the source of the media.
==== media_type ====
String - A description of the type of the media.
==== media_url ====
URL - The location to the media file.
==== part ====
String -
==== public ====
Boolean_flag - A flag that specifies whether or not the media is public.
==== technique ====
String - A description of the method by which the media was taken.

== See also ==
Visit any of the below links to find information about the other data domains defined by OJ_Break Version 2.

* [[OJ_Break v2 Agent Reference|Agent]]
* [[OJ_Break v2 Geographic Place Reference|Geographic Place]]
* [[OJ_Break v2 Institution Reference|Institution]]
* [[OJ_Break v2 Journal Reference|Journal]]
* [[OJ_Break v2 Literature Reference|Literature]]
* [[OJ_Break v2 Locality Reference|Locality]]
* [[OJ_Break v2 Occurrence Reference|Occurrence]]
* [[OJ_Break v2 Search Reference|Search]]
* [[OJ_Break v2 Taxon Reference|Taxon]]

OJ Break v2 Locality Reference

2015-04-27T17:33:59Z

Tyler: /* Elements */

OJ Break v2 Locality Reference

2015-04-27T17:30:44Z

Tyler: /* Elements */

OJ Break v2 Literature Reference

2015-04-27T17:23:01Z

Tyler: /* Elements */

OJ Break v2 Institution Reference

2015-04-27T17:07:36Z

Tyler:

OJ Break v2 Search Reference

2015-04-22T21:05:36Z

Tyler:

OJ Break API Access

2015-04-22T20:51:08Z

Tyler: /* Arguments */

'''Introduction'''

In order to access the OJ_Break API, follow the instructions below. An API key linked to an xBio:D user account is required to use the API.

== Overview ==
All API requests must be formatted by first selecting the OJ_Break library then specifying the API method. Also, each method must include a ''format'', ''key'', and ''version'' argument.
The format for API calls is: '''''<nowiki>http://xbiod.osu.edu/OJ_Break/[method]?[argument1]=[value1]&...</nowiki>'''''
Example: '''''<nowiki>http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2</nowiki>'''''

The response for an API call will include a success or error code, a corresponding response message, and the included data returned by the method call displayed according to the value of the ''format'' parameter.
Response: '''''{"code":100,"message":"API resource successfully retrieved","data":{"taxon":"Heptascelio striatosternus","author":"Narendran & Ramesh Babu","stats":...'''''

== Arguments ==
=== Method Specific Parameters ===
When calling a method, the corresponding parameters necessary must be included and have valid values. All methods and their parameters are included in the [[OJ_Break API Help]] page. In the example below, the method [[OJ Break API Help#getTaxonStats|getTaxonStats]] needs the parameter [[OJ Break API Data Type Glossary#tnuid_2|tnuid]] to return the desired data.

Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

=== ''format'' ===
The ''format'' parameter specifies the structure of the data being received by an API call. The value for the parameter can be either '''json''' (default), '''jsonp''', '''html''', or '''xml'''.

*'''''json''''': JavaScript Object Notation is a lightweight data-interchange format made up of objects and arrays. Arrays can hold many elements of one data type, and objects can hold keys with associated values of many data types.
Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

* '''''xml''''': Extensible Markup Language is a hierarchy based data-structure that is easy to read by humans. The language is made up of tags, similar to HTML, to display data. Instead of data types, the '''xml''' parameter assigns each tag a ''type'' attribute that signifies the type of the tag value.
Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=xml&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

* '''''html''''': Hypertext Markup Language is the foundational language for the world wide web. Since web browsers are designed to interpret and display HTML, this is the most human-readable format and should generally not be used for machine-to-machine transactions.
Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

* '''''jsonp''''': JavaScript Object Notation with Padding returns the data in the JSON format but wrapped within a specified '''callback''' argument for procedural calls.
Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&callback=api&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

=== ''callback'' ===
The ''callback'' parameter is only necessary when ''format'' is specified as '''jsonp'''. This gives a procedural call to the value given by ''callback'' with the data retrieved.

Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&callback=test&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

=== ''key'' ===
The ''key'' parameter is a Database Manager defined API access code. The key used in the OJ_Break API reference is for testing and example purposes only.

==== Getting a Key ====
To get an API access key, go to the [http://osuc-mgr.osu.edu/ Database Manager website] and sign up or sign in with a valid username and password.

[[File:API_Access_tut_login.png|frame|none|Shown are the username and passwords fields to sign into Database Manager. If an account needs to be created, clicking the sign up button redirects to an account creation page.|link=http://osuc-mgr.osu.edu/]]

On the left side of the screen, click on '''Manage API Access'''.

[[File:API_Access_tut_manage.png|frame|none|The Manage API Access link is shown. This link will bring up the API Access page.|link=http://osuc-mgr.osu.edu/]]

Finally, click the '''Set Up Access''' button next to the 'API Key:' text. A unique access key will appear.

[[File:API_Access_tut2.png|frame|none|Shown here is the API Key button on the API Access page. Clicking the Set Up Access button will reveal a unique database key.|link=http://osuc-mgr.osu.edu/]]

== Responses ==
Every call to the API, regardless of the format, will return three main articles of information: ''code'', ''message'', and ''data''.

Roughly, the arrangement of the response will be similar to:
'''code:[''code''], message:[''code message''], data:[''method return'']'''
=== ''code'' ===
[[File:API_Access_tut_error.png|alt=A popup containing an error message stating that access is denied to the API.|frame|none|An example of an error alert. Error code 901 is shown to help describe possible causes.]]

The ''code'' key/tag contains a three digit number whose value depends on the state of the API request. Below is a list of all possible codes and their significance.
* '''100''': Success
* '''900''': Error
* '''901''': Error
* '''902''': Error
* '''903''': Error

=== ''message'' ===

The ''message'' response will accompany the received ''code'' number as an explanation for the state of the API request. Below is a list of the possible codes and their cooresponding messages.

* ''code'' '''100''': ''message'': '''"API resource successfully retrieved"'''
* ''code'' '''900''': ''message'': '''"API resource not specified"'''
* ''code'' '''901''': ''message'': '''"API resource could not complete request (reasons: resource not available, parameters missing, malformed parameter value, or internal system error)"'''
* ''code'' '''902''': ''message'': '''"API key is either missing or invalid"'''
* ''code'' '''903''': ''message'': '''"Server is not authorized to use the API for the specified API key"'''

=== ''data'' ===
All of the returned information from the API call will be found organized in the ''data'' key/tag. This information will only be present with a successful API retrieval.

[[Category:OJ_Break API]]

OJ Break API Access

2015-04-22T20:49:48Z

Tyler:

'''Introduction'''

In order to access the OJ_Break API, follow the instructions below. An API key linked to an xBio:D user account is required to use the API.

== Overview ==
All API requests must be formatted by first selecting the OJ_Break library then specifying the API method. Also, each method must include a ''format'', ''key'', and ''version'' argument.
The format for API calls is: '''''<nowiki>http://xbiod.osu.edu/OJ_Break/[method]?[argument1]=[value1]&...</nowiki>'''''
Example: '''''<nowiki>http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2</nowiki>'''''

The response for an API call will include a success or error code, a corresponding response message, and the included data returned by the method call displayed according to the value of the ''format'' parameter.
Response: '''''{"code":100,"message":"API resource successfully retrieved","data":{"taxon":"Heptascelio striatosternus","author":"Narendran & Ramesh Babu","stats":...'''''

== Arguments ==
=== Method Specific Parameters ===
When calling a method, the corresponding parameters necessary must be included and have valid values. All methods and their parameters are included in the [[OJ_Break API Help]] page. In the example below, the method [[OJ Break API Help#getTaxonStats|getTaxonStats]] needs the parameter [[OJ Break API Data Type Glossary#tnuid_2|tnuid]] to return the desired data.

Example: http://xbiod.osu.edu/OJ_Break/getTaxonStats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

=== ''format'' ===
The ''format'' parameter specifies the structure of the data being received by an API call. The value for the parameter can be either '''json''' (default), '''jsonp''', '''html''', or '''xml'''.

*'''''json''''': JavaScript Object Notation is a lightweight data-interchange format made up of objects and arrays. Arrays can hold many elements of one data type, and objects can hold keys with associated values of many data types.
Example: http://xbiod.osu.edu/OJ_Break/getTaxonStats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

* '''''xml''''': Extensible Markup Language is a hierarchy based data-structure that is easy to read by humans. The language is made up of tags, similar to HTML, to display data. Instead of data types, the '''xml''' parameter assigns each tag a ''type'' attribute that signifies the type of the tag value.
Example: http://xbiod.osu.edu/OJ_Break/getTaxonStats?tnuid=30148&format=xml&key=FBF57A9F7A666FC0E0430100007F0CDC

* '''''html''''': Hypertext Markup Language is the foundational language for the world wide web. Since web browsers are designed to interpret and display HTML, this is the most human-readable format and should generally not be used for machine-to-machine transactions.
Example: http://xbiod.osu.edu/OJ_Break/getTaxonStats?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC

* '''''jsonp''''': JavaScript Object Notation with Padding returns the data in the JSON format but wrapped within a specified '''callback''' argument for procedural calls.
Example: http://xbiod.osu.edu/OJ_Break/getTaxonStats?tnuid=30148&callback=api&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC

=== ''callback'' ===
The ''callback'' parameter is only necessary when ''format'' is specified as '''jsonp'''. This gives a procedural call to the value given by ''callback'' with the data retrieved.

Example: http://xbiod.osu.edu/OJ_Break/getTaxonStats?tnuid=30148&callback=test&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC

=== ''key'' ===
The ''key'' parameter is a Database Manager defined API access code. The key used in the OJ_Break API reference is for testing and example purposes only.

==== Getting a Key ====
To get an API access key, go to the [http://osuc-mgr.osu.edu/ Database Manager website] and sign up or sign in with a valid username and password.

[[File:API_Access_tut_login.png|frame|none|Shown are the username and passwords fields to sign into Database Manager. If an account needs to be created, clicking the sign up button redirects to an account creation page.|link=http://osuc-mgr.osu.edu/]]

On the left side of the screen, click on '''Manage API Access'''.

[[File:API_Access_tut_manage.png|frame|none|The Manage API Access link is shown. This link will bring up the API Access page.|link=http://osuc-mgr.osu.edu/]]

Finally, click the '''Set Up Access''' button next to the 'API Key:' text. A unique access key will appear.

[[File:API_Access_tut2.png|frame|none|Shown here is the API Key button on the API Access page. Clicking the Set Up Access button will reveal a unique database key.|link=http://osuc-mgr.osu.edu/]]

== Responses ==
Every call to the API, regardless of the format, will return three main articles of information: ''code'', ''message'', and ''data''.

Roughly, the arrangement of the response will be similar to:
'''code:[''code''], message:[''code message''], data:[''method return'']'''
=== ''code'' ===
[[File:API_Access_tut_error.png|alt=A popup containing an error message stating that access is denied to the API.|frame|none|An example of an error alert. Error code 901 is shown to help describe possible causes.]]

The ''code'' key/tag contains a three digit number whose value depends on the state of the API request. Below is a list of all possible codes and their significance.
* '''100''': Success
* '''900''': Error
* '''901''': Error
* '''902''': Error
* '''903''': Error

=== ''message'' ===

The ''message'' response will accompany the received ''code'' number as an explanation for the state of the API request. Below is a list of the possible codes and their cooresponding messages.

* ''code'' '''100''': ''message'': '''"API resource successfully retrieved"'''
* ''code'' '''900''': ''message'': '''"API resource not specified"'''
* ''code'' '''901''': ''message'': '''"API resource could not complete request (reasons: resource not available, parameters missing, malformed parameter value, or internal system error)"'''
* ''code'' '''902''': ''message'': '''"API key is either missing or invalid"'''
* ''code'' '''903''': ''message'': '''"Server is not authorized to use the API for the specified API key"'''

=== ''data'' ===
All of the returned information from the API call will be found organized in the ''data'' key/tag. This information will only be present with a successful API retrieval.

[[Category:OJ_Break API]]

OJ Break v2 Institution Reference

2015-04-22T20:34:06Z

Tyler: /* API Information and Access */

OJ Break v2 Geographic Place Reference

2015-04-22T20:33:35Z

Tyler: /* API Information and Access */

OJ Break v2 Agent Reference

2015-04-22T20:33:08Z

Tyler: /* API Information and Access */

OJ Break v2 Taxon Reference

2015-04-22T20:32:36Z

Tyler:

'''Introduction'''

OJ_Break is the name of the xBio:D RESTful API service to facilitate discovery of data within the xBio:D database. The API can respond with HTML, JSON, XML, or JSON with padding (JSONP) and accepts HTTP GET and POST requests indiscriminately. The backend of the API is written in Oracle's PL/SQL database language, which is fast but often inflexible, while a Python presentation layer mitigates request handling and authentication.

OJ_Break Version 2 is a new and improved edition of the work started in Version 1. Version 2 introduces a completely restructured and standardized data model to further enhance the functionality of the xBio:D database.

== API Information and Access ==
This page specifies the methods and data defined by OJ_Break Version 2, more precisely those that are defined by the '''Taxon''' data domain. To get information on any of the other data domains defined in OJ_Break Version 2, visit the [[#See_also|See also]] section.

Using the OJ_Break Version 2 API requires calling methods with corresponding, method specific parameters (found on this page) and a few other required parameters. These required parameters include specifying a return ''format'', an API access ''key'', and a ''version'' number.

Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

Notice the specification of the ''version'' parameter at the end of the example method call. With the introduction of OJ_Break Version 2, the ''version'' parameter has a default value of ''2'' making the specification in the example unnecessary. To read more about using the OJ_Break Version 2 API, go to [[OJ_Break API Access]].

== Procedural Reference ==
=== Taxon ===
==== getTaxonInfo ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonComplete (extends TaxonRelationship)|TaxonComplete]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonInfo?tnuid=30148&inst_id=1&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonHierarchy ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonHierarchy?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonIncludedTaxa ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*rank'': [[#rank|rank]]
* ''*offset'': Number
* ''*limit'': Number
* ''*show_syns'': Boolean_flag
* ''*show_fossils'': Boolean_flag
* ''*types_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnIncluded (extends TaxonReturn)|TaxonReturnIncluded]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonIncludedTaxa?tnuid=30148&inst_id=1&show_syns=Y&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonSynonyms ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_fossils'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnSynonyms (extends TaxonReturn)|TaxonReturnSynonyms]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonSynonyms?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonAssociations ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*basic_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number

===== Return =====
* [[#TaxonReturnAssociations (extends TaxonReturn)|TaxonReturnAssociations]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonAssociations?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonLiteratureCitations ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_children'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnLiteratureCitations (extends TaxonReturn)|TaxonReturnLiteratureCitations]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonLiteratureCitations?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonOccurrences ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*place_id'': ''[[OJ_Break v2 Geographic Place Reference#place_id|place_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_children'': Boolean_flag
* ''*basic_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnOccurrences (extends TaxonReturn)|TaxonReturnOccurrences]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonOccurrences?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonTypes ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*basic_only'': Boolean_flag
* ''*show_children'': Boolean_flag
* ''*primary_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnOccurrences (extends TaxonReturn)|TaxonReturnOccurrences]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonTypes?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonLocalities ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*place_id'': [[OJ_Break v2 Geographic Place Reference#place_id|place_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_children'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnLocalities (extends TaxonReturn)|TaxonReturnLocalities]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonLocalities?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonDeterminers ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnDeterminers (extends TaxonReturn)|TaxonReturnDeterminers]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonDeterminers?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonInstitutions ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnInstitutions (extends TaxonReturn)|TaxonReturnInstitutions]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonInstitutions?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonHabitats ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnHabitats (extends TaxonReturn)|TaxonReturnHabitats]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonHabitats?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonMedia ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*media_type'': ''media_type''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnMedia (extends TaxonReturn)|TaxonReturnMedia]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonMedia?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

== Taxon Data Type Glossary ==
=== Classes ===
==== TaxonAssociation ====
* ''assoc_taxon'': [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]
* ''assoc_type'': ''[[#assoc_type|assoc_type]]''
* ''assoc_type_full'': ''[[#assoc_type_full|assoc_type_full]]''
* ''assoc_occurrences'': array of [[OJ_Break v2 Occurrence Reference#OccurrenceBasic|OccurrenceBasic]]

==== TaxonBasic ====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''taxon'': ''[[#taxon|taxon]]''
* ''taxon_author'': ''[[#taxon_author|taxon_author]]''

==== TaxonComplete (extends [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]) ====
* ''stats'': [[#TaxonInfoStats (extends TaxonStats)|TaxonInfoStats]]
* ''contribs'': array of Contribution
* ''orig_desc'': [[OJ_Break v2 Literature Reference#LiteratureExtended|LiteratureExtended]]

==== TaxonExtended (extends [[#TaxonBasic|TaxonBasic]]) ====
* ''describer'': ''[[#describer|describer]]''
* ''status'': ''[[#status|status]]''
* ''valid'': ''[[#valid|valid]]''
* ''rank'': ''[[#rank|rank]]''
* ''valid_taxon'': [[#TaxonBasic|TaxonBasic]]
* ''fossil'': ''[[#fossil|fossil]]''
* ''homonym'': ''[[#homonym|homonym]]''
* ''common_names'': array of ''[[#common_name|common_name]]''
* ''source'': [[#TaxonSource|TaxonSource]]

==== TaxonHierarchy ====
Aggregate of one or more of the following classes:
* [[#TaxonHierKingdom|TaxonHierKingdom]] (1)
* [[#TaxonHierPhylum|TaxonHierPhylum]] (0 or 1)
* [[#TaxonHierDivision|TaxonHierDivision]] (0 or 1)
* [[#TaxonHierSubphylum|TaxonHierSubphylum]] (0 or 1)
* [[#TaxonHierClass|TaxonHierClass]]'' (0 or 1)
* [[#TaxonHierSubclass|TaxonHierSubclass]] (0 or 1)
* [[#TaxonHierInfraclass|TaxonHierInfraclass]] (0 or 1)
* [[#TaxonHierOrder|TaxonHierOrder]] (0 or 1)
* [[#TaxonHierSuborder|TaxonHierSuborder]] (0 or 1)
* [[#TaxonHierInfraorder|TaxonHierInfraorder]] (0 or 1)
* [[#TaxonHierCohort|TaxonHierCohort]] (0 or 1)
* [[#TaxonHierSubcohort|TaxonHierSubcohort]] (0 or 1)
* [[#TaxonHierSuperfamily|TaxonHierSuperfamily]] (0 or 1)
* [[#TaxonHierFamily|TaxonHierFamily]] (0 or 1)
* [[#TaxonHierSubfamily|TaxonHierSubfamily]] (0 or 1)
* [[#TaxonHierTribe|TaxonHierTribe]] (0 or 1)
* [[#TaxonHierSubtribe|TaxonHierSubtribe]] (0 or 1)
* [[#TaxonHierGenus|TaxonHierGenus]] (0 or 1)
* [[#TaxonHierSpecies|TaxonHierSpecies]] (0 or 1)
* [[#TaxonHierSubspecies|TaxonHierSubspecies]] (0 or 1)

==== TaxonHierClass ====
* ''Class'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierCohort ====
* ''Cohort'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierDivision ====
* ''Division'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierFamily ====
* ''Family'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierGenus ====
* ''Genus'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierInfraclass ====
* ''Infraclass'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierInfraorder ====
* ''Infraorder'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierKingdom ====
* ''Kingdom'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierOrder ====
* ''Order'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierPhylum ====
* ''Phylum'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSpecies ====
* ''Species'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubclass ====
* ''Subclass'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubcohort ====
* ''Subcohort'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubfamily ====
* ''Subfamily'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSuborder ====
* ''Suborder'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubphylum ====
* ''Subphylum'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubspecies ====
* ''Subspecies'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubtribe ====
* ''Subtribe'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSuperfamily ====
* ''Superfamily'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierTribe ====
* ''Tribe'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierUnit (extends [[#TaxonBasic|TaxonBasic]]) ====
* ''next'': [[#rank|''rank'']]

==== TaxonInfoStats (extends [[#TaxonStats|TaxonStats]]) ====
* ''child_stats'': array of [[#TaxonStats|TaxonStats]]
* ''num_records'': Number
* ''num_spms'': Number

==== TaxonRelationship (extends [[#TaxonExtended (extends TaxonBasic)|TaxonExtended]]) ====
* ''rel_type'': ''[[#rel_type|rel_type]]''
* ''parent_taxon'': [[#TaxonBasic|TaxonBasic]]
* ''hier'': [[#TaxonHierarchy|TaxonHierarchy]]

==== TaxonReturn ====
* ''general'': [[#TaxonBasic|TaxonBasic]]

==== TaxonReturnAssociations (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''associations'': array of [[#TaxonAssociation|TaxonAssociation]]

==== TaxonReturnDeterminers (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''determiners'': array of [[#TaxonExtended (extends TaxonBasic)|AgentExtended]]

==== TaxonReturnHabitats (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''hatitats'': array of [[#habitat|''habitat'']]

==== TaxonReturnIncluded (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''includedTaxa'': array of [[#TaxonExtended (extends TaxonBasic)|AgentExtended]]

==== TaxonReturnInstitutions (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''institutions'': array of [[OJ_Break v2 Institution Reference#InstitutionBasic|InstitutionBasic]]

==== TaxonReturnLiteratureCitations (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''pub_citations'': array of [[OJ_Break v2 Literature Reference#LiteratureTaxonCitationExtended|LiteratureTaxonCitationExtended]]

==== TaxonReturnLocalities (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''localities'': array of [[OJ_Break v2 Locality Reference#LocalityExtended|LocalityExtended]]

==== TaxonReturnMedia (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''media'': array of [[OJ_Break v2 Media Reference#MediaExtended (extends MediaBasic)|MediaExtended]]

==== TaxonReturnOccurrences (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''occurrences'': array of [[OJ_Break v2 Occurrence Reference#OccurrenceExtended|OccurrenceExtended]]

==== TaxonReturnSynonyms (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''synonyms'': array of [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]

==== TaxonSource ====
* ''id'': Number
* ''name'': String
* ''logo'': URL
* ''url'': URL
* ''query'': URL

==== TaxonStats ====
* ''rank'': ''[[#rank|rank]]''
* ''rank_value'': ''[[#rank_value|rank_value]]''
* ''num_taxa'': Number

=== Elements ===
==== assoc_type ====
String - A description of the biological relationship between a specified taxon and another organism.
==== assoc_type_full ====
String - A complete description of the biological relationship between a specified taxon and another organism.
==== common_name ====
String - A common name for a taxon that can be included as a taxon name string but is never valid.
==== describer ====
String - the describer(s) of a taxon.
==== fossil ====
String - A modified boolean_flag, either Y, N or B, representing whether a taxon name is a extinct fossil, exclusively extant, or present today and in fossils.
==== habitat ====
String - Description or identifier of the ecological or environmental area that a particular species is known to inhabit.
==== homonym ====
Boolean_flag - Boolean_flag indicating whether or not the determination was a homonym
==== rank ====
String - The taxonomic (hierarchical) rank of a taxon name.
==== rank_value ====
Number - A number representing the rank of a taxon with higher numbers representing higher positions in the taxonomic hierarchy.
==== rel_type ====
String - The taxonomic (hierarchical) relationship between the taxonomic concept indicated by the taxon name and its parent taxonomic concept. Can be Member, Junior synonym, etc.
==== status ====
String - The nomenclatural status of a taxon name using a formalized vocabulary.
==== taxon ====
String - A taxon name string.
==== taxon_author ====
String - The author(s) of a taxon with parenthesis surrounding the name of the author(s) if necessary.
==== tnuid ====
Number - The taxon name use identifier which uniquely identifies a taxon.
==== valid ====
String - A ''Valid'' or ''Invalid'' string representing the validity of a taxon name using subjective interpretations if warranted.

== See also ==
Visit any of the below links to find information about the other data domains defined by OJ_Break Version 2.

* [[OJ_Break v2 Agent Reference|Agent]]
* [[OJ_Break v2 Geographic Place Reference|Geographic Place]]
* [[OJ_Break v2 Institution Reference|Institution]]
* [[OJ_Break v2 Journal Reference|Journal]]
* [[OJ_Break v2 Literature Reference|Literature]]
* [[OJ_Break v2 Locality Reference|Locality]]
* [[OJ_Break v2 Media Reference|Media]]
* [[OJ_Break v2 Occurrence Reference|Occurrence]]
* [[OJ_Break v2 Search Reference|Search]]

OJ Break v2 Search Reference

2015-04-22T20:30:46Z

Tyler:

OJ Break v2 Occurrence Reference

2015-04-22T20:29:29Z

Tyler:

OJ Break v2 Media Reference

2015-04-22T20:28:55Z

Tyler:

'''Introduction'''

OJ_Break is the name of the xBio:D RESTful API service which enables the discovery of data within the xBio:D database. The API can respond with HTML, JSON, XML, or JSON with padding (JSONP) and accepts HTTP GET and POST requests indiscriminately. The backend of the API is written in Oracle's PL/SQL database language, which is fast but often inflexible, while a Python presentation layer mitigates request handling and authentication.

OJ_Break Version 2 is a new and improved edition of the work started in Version 1. Version 2 introduces a completely restructured and standardized data model to further enhance the functionality of the xBio:D database.

== API Information and Access ==
This page specifies the data defined by OJ_Break Version 2, more precisely those that are defined by the '''Media''' data domain. To get information on any of the other data domains defined in OJ_Break Version 2, visit the [[#See_also|See also]] section.

== Media Data Type Glossary ==
=== Classes ===
==== ImageExtended (extends [[#MediaExtended (extends MediaBasic)|MediaExtended]]) ====
* ''thumb'': URL
* ''raw'': URL

==== LocalityImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''locality'': [[OJ_Break v2 Locality Reference#LocalityBasic|LocalityBasic]]

==== MediaBasic ====
* ''media_id'': ''[[#media_id|media_id]]''
* ''media_type'': ''[[#media_type|media_type]]''
* ''media_url'': ''[[#media_url|media_url]]''
* ''media_source'': ''[[#media_source|media_source]]''
* ''public'': ''[[#public|public]]''

==== MediaExtended (extends [[#MediaBasic|MediaBasic]]) ====
* ''caption'': ''[[#caption|caption]]''
* ''copyright'': ''[[#copyright|copyright]]''
* ''license'': ''[[#license|license]]''
* ''enterer'': ''[[#enterer|enterer]]''

==== OccurrenceImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''occurrence'': [[OJ_Break v2 Occurrence Reference#OccurrenceTrimmed (extends OccurrenceBasic)|OccurrenceTrimmed]]
* ''parts'': array of ''[[#part|part]]''
* ''angle'': ''[[#angle|angle]]''
* ''technique'': ''[[#technique|technique]]''
* ''notes'': String

==== OccurrenceRecordingExtended (realizes [[#MediaExtended (extends MediaBasic)|MediaExtended]]) ====
* ''occurrence'': [[OJ_Break v2 Occurrence Reference#OccurrenceTrimmed|OccurrenceTrimmed]]

==== TaxonImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''taxon'': [[OJ_Break v2 Taxon Reference#TaxonBasic|TaxonBasic]]

==== VideaExtended (realizes [[#ImageExtended extends MediaExtended)|ImageExtended]]) ====
* ''taxon'': [[OJ_Break v2 Taxon Reference#TaxonBasic|TaxonBasic]]

=== Elements ===
==== angle ====
String - A description of the angle the media was taken.
==== caption ====
String - A summary of the media.
==== copyright ====
String - Copyright information.
==== enterer ====
String - The media enterer's name.
==== license ====
String - Licensing information.
==== media_id ====
Number - A numeric identifier that uniquely identifies a media piece.
==== media_source ====
String - The name of the source of the media.
==== media_type ====
String - A description of the type of the media.
==== media_url ====
URL - The location to the media file.
==== public ====
Boolean_flag - A flag that specifies whether or not the media is public.
==== technique ====
String - A description of the method by which the media was taken.

== See also ==
Visit any of the below links to find information about the other data domains defined by OJ_Break Version 2.

* [[OJ_Break v2 Agent Reference|Agent]]
* [[OJ_Break v2 Geographic Place Reference|Geographic Place]]
* [[OJ_Break v2 Institution Reference|Institution]]
* [[OJ_Break v2 Journal Reference|Journal]]
* [[OJ_Break v2 Literature Reference|Literature]]
* [[OJ_Break v2 Locality Reference|Locality]]
* [[OJ_Break v2 Occurrence Reference|Occurrence]]
* [[OJ_Break v2 Search Reference|Search]]
* [[OJ_Break v2 Taxon Reference|Taxon]]

OJ Break v2 Locality Reference

2015-04-22T20:28:00Z

Tyler:

OJ Break v2 Literature Reference

2015-04-22T20:27:19Z

Tyler:

OJ Break v2 Journal Reference

2015-04-22T20:26:31Z

Tyler:

OJ Break v2 Institution Reference

2015-04-22T20:25:25Z

Tyler:

OJ Break v2 Geographic Place Reference

2015-04-22T20:24:27Z

Tyler:

OJ Break v2 Agent Reference

2015-04-22T20:23:22Z

Tyler:

OJ Break v2 Taxon Reference

2015-04-22T20:21:52Z

Tyler:

'''Introduction'''

OJ_Break is the name of the xBio:D RESTful API service to facilitate discovery of data within the xBio:D database. The API can respond with JavaScript Object Notation (JSON), XML, or JSON with padding (JSONP) and accepts HTTP GET and POST requests indiscriminately. The backend of the API is written in Oracle's PL/SQL database language, which is fast but often inflexible, while a Python presentation layer mitigates request handling and authentication.

OJ_Break Version 2 is a new and improved edition of the work started in Version 1. Version 2 introduces a completely restructured and standardized data model to further enhance the functionality of the xBio:D database.

== API Information and Access ==
This page specifies the methods and data defined by OJ_Break Version 2, more precisely those that are defined by the '''Taxon''' data domain. To get information on any of the other data domains defined in OJ_Break Version 2, visit the [[#See_also|See also]] section.

Using the OJ_Break Version 2 API requires calling methods with corresponding, method specific parameters (found on this page) and a few other required parameters. These required parameters include specifying a return ''format'', an API access ''key'', and a ''version'' number.

Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

Notice the specification of the ''version'' parameter at the end of the example method call. With the introduction of OJ_Break Version 2, the ''version'' parameter has a default value of ''2'' making the specification in the example unnecessary. To read more about using the OJ_Break Version 2 API, go to [[OJ_Break API Access]].

== Procedural Reference ==
=== Taxon ===
==== getTaxonInfo ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonComplete (extends TaxonRelationship)|TaxonComplete]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonInfo?tnuid=30148&inst_id=1&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonHierarchy ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonHierarchy?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonIncludedTaxa ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*rank'': [[#rank|rank]]
* ''*offset'': Number
* ''*limit'': Number
* ''*show_syns'': Boolean_flag
* ''*show_fossils'': Boolean_flag
* ''*types_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnIncluded (extends TaxonReturn)|TaxonReturnIncluded]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonIncludedTaxa?tnuid=30148&inst_id=1&show_syns=Y&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonSynonyms ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_fossils'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnSynonyms (extends TaxonReturn)|TaxonReturnSynonyms]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonSynonyms?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonAssociations ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*basic_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number

===== Return =====
* [[#TaxonReturnAssociations (extends TaxonReturn)|TaxonReturnAssociations]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonAssociations?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonLiteratureCitations ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_children'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnLiteratureCitations (extends TaxonReturn)|TaxonReturnLiteratureCitations]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonLiteratureCitations?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonOccurrences ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*place_id'': ''[[OJ_Break v2 Geographic Place Reference#place_id|place_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_children'': Boolean_flag
* ''*basic_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnOccurrences (extends TaxonReturn)|TaxonReturnOccurrences]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonOccurrences?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonTypes ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*basic_only'': Boolean_flag
* ''*show_children'': Boolean_flag
* ''*primary_only'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnOccurrences (extends TaxonReturn)|TaxonReturnOccurrences]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonTypes?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonLocalities ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*place_id'': [[OJ_Break v2 Geographic Place Reference#place_id|place_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''*show_children'': Boolean_flag
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnLocalities (extends TaxonReturn)|TaxonReturnLocalities]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonLocalities?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonDeterminers ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnDeterminers (extends TaxonReturn)|TaxonReturnDeterminers]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonDeterminers?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonInstitutions ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnInstitutions (extends TaxonReturn)|TaxonReturnInstitutions]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonInstitutions?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonHabitats ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnHabitats (extends TaxonReturn)|TaxonReturnHabitats]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonHabitats?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

==== getTaxonMedia ====
===== Description =====
===== Parameters =====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''*media_type'': ''media_type''
* ''*inst_id'': ''[[OJ_Break v2 Institution Reference#inst_id|inst_id]]''
* ''*offset'': Number
* ''*limit'': Number
* ''format'': String
* ''key'': String
* ''version'': Number
===== Return =====
* [[#TaxonReturnMedia (extends TaxonReturn)|TaxonReturnMedia]]

===== Example =====
http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonMedia?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

== Taxon Data Type Glossary ==
=== Classes ===
==== TaxonAssociation ====
* ''assoc_taxon'': [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]
* ''assoc_type'': ''[[#assoc_type|assoc_type]]''
* ''assoc_type_full'': ''[[#assoc_type_full|assoc_type_full]]''
* ''assoc_occurrences'': array of [[OJ_Break v2 Occurrence Reference#OccurrenceBasic|OccurrenceBasic]]

==== TaxonBasic ====
* ''tnuid'': ''[[#tnuid|tnuid]]''
* ''taxon'': ''[[#taxon|taxon]]''
* ''taxon_author'': ''[[#taxon_author|taxon_author]]''

==== TaxonComplete (extends [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]) ====
* ''stats'': [[#TaxonInfoStats (extends TaxonStats)|TaxonInfoStats]]
* ''contribs'': array of Contribution
* ''orig_desc'': [[OJ_Break v2 Literature Reference#LiteratureExtended|LiteratureExtended]]

==== TaxonExtended (extends [[#TaxonBasic|TaxonBasic]]) ====
* ''describer'': ''[[#describer|describer]]''
* ''status'': ''[[#status|status]]''
* ''valid'': ''[[#valid|valid]]''
* ''rank'': ''[[#rank|rank]]''
* ''valid_taxon'': [[#TaxonBasic|TaxonBasic]]
* ''fossil'': ''[[#fossil|fossil]]''
* ''homonym'': ''[[#homonym|homonym]]''
* ''common_names'': array of ''[[#common_name|common_name]]''
* ''source'': [[#TaxonSource|TaxonSource]]

==== TaxonHierarchy ====
Aggregate of one or more of the following classes:
* [[#TaxonHierKingdom|TaxonHierKingdom]] (1)
* [[#TaxonHierPhylum|TaxonHierPhylum]] (0 or 1)
* [[#TaxonHierDivision|TaxonHierDivision]] (0 or 1)
* [[#TaxonHierSubphylum|TaxonHierSubphylum]] (0 or 1)
* [[#TaxonHierClass|TaxonHierClass]]'' (0 or 1)
* [[#TaxonHierSubclass|TaxonHierSubclass]] (0 or 1)
* [[#TaxonHierInfraclass|TaxonHierInfraclass]] (0 or 1)
* [[#TaxonHierOrder|TaxonHierOrder]] (0 or 1)
* [[#TaxonHierSuborder|TaxonHierSuborder]] (0 or 1)
* [[#TaxonHierInfraorder|TaxonHierInfraorder]] (0 or 1)
* [[#TaxonHierCohort|TaxonHierCohort]] (0 or 1)
* [[#TaxonHierSubcohort|TaxonHierSubcohort]] (0 or 1)
* [[#TaxonHierSuperfamily|TaxonHierSuperfamily]] (0 or 1)
* [[#TaxonHierFamily|TaxonHierFamily]] (0 or 1)
* [[#TaxonHierSubfamily|TaxonHierSubfamily]] (0 or 1)
* [[#TaxonHierTribe|TaxonHierTribe]] (0 or 1)
* [[#TaxonHierSubtribe|TaxonHierSubtribe]] (0 or 1)
* [[#TaxonHierGenus|TaxonHierGenus]] (0 or 1)
* [[#TaxonHierSpecies|TaxonHierSpecies]] (0 or 1)
* [[#TaxonHierSubspecies|TaxonHierSubspecies]] (0 or 1)

==== TaxonHierClass ====
* ''Class'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierCohort ====
* ''Cohort'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierDivision ====
* ''Division'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierFamily ====
* ''Family'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierGenus ====
* ''Genus'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierInfraclass ====
* ''Infraclass'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierInfraorder ====
* ''Infraorder'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierKingdom ====
* ''Kingdom'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierOrder ====
* ''Order'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierPhylum ====
* ''Phylum'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSpecies ====
* ''Species'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubclass ====
* ''Subclass'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubcohort ====
* ''Subcohort'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubfamily ====
* ''Subfamily'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSuborder ====
* ''Suborder'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubphylum ====
* ''Subphylum'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubspecies ====
* ''Subspecies'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSubtribe ====
* ''Subtribe'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierSuperfamily ====
* ''Superfamily'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierTribe ====
* ''Tribe'': [[#TaxonHierUnit (extends TaxonBasic)|TaxonHierUnit]]

==== TaxonHierUnit (extends [[#TaxonBasic|TaxonBasic]]) ====
* ''next'': [[#rank|''rank'']]

==== TaxonInfoStats (extends [[#TaxonStats|TaxonStats]]) ====
* ''child_stats'': array of [[#TaxonStats|TaxonStats]]
* ''num_records'': Number
* ''num_spms'': Number

==== TaxonRelationship (extends [[#TaxonExtended (extends TaxonBasic)|TaxonExtended]]) ====
* ''rel_type'': ''[[#rel_type|rel_type]]''
* ''parent_taxon'': [[#TaxonBasic|TaxonBasic]]
* ''hier'': [[#TaxonHierarchy|TaxonHierarchy]]

==== TaxonReturn ====
* ''general'': [[#TaxonBasic|TaxonBasic]]

==== TaxonReturnAssociations (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''associations'': array of [[#TaxonAssociation|TaxonAssociation]]

==== TaxonReturnDeterminers (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''determiners'': array of [[#TaxonExtended (extends TaxonBasic)|AgentExtended]]

==== TaxonReturnHabitats (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''hatitats'': array of [[#habitat|''habitat'']]

==== TaxonReturnIncluded (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''includedTaxa'': array of [[#TaxonExtended (extends TaxonBasic)|AgentExtended]]

==== TaxonReturnInstitutions (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''institutions'': array of [[OJ_Break v2 Institution Reference#InstitutionBasic|InstitutionBasic]]

==== TaxonReturnLiteratureCitations (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''pub_citations'': array of [[OJ_Break v2 Literature Reference#LiteratureTaxonCitationExtended|LiteratureTaxonCitationExtended]]

==== TaxonReturnLocalities (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''localities'': array of [[OJ_Break v2 Locality Reference#LocalityExtended|LocalityExtended]]

==== TaxonReturnMedia (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''media'': array of [[OJ_Break v2 Media Reference#MediaExtended (extends MediaBasic)|MediaExtended]]

==== TaxonReturnOccurrences (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''occurrences'': array of [[OJ_Break v2 Occurrence Reference#OccurrenceExtended|OccurrenceExtended]]

==== TaxonReturnSynonyms (extends [[#TaxonReturn|TaxonReturn]]) ====
* ''synonyms'': array of [[#TaxonRelationship (extends TaxonExtended)|TaxonRelationship]]

==== TaxonSource ====
* ''id'': Number
* ''name'': String
* ''logo'': URL
* ''url'': URL
* ''query'': URL

==== TaxonStats ====
* ''rank'': ''[[#rank|rank]]''
* ''rank_value'': ''[[#rank_value|rank_value]]''
* ''num_taxa'': Number

=== Elements ===
==== assoc_type ====
String - A description of the biological relationship between a specified taxon and another organism.
==== assoc_type_full ====
String - A complete description of the biological relationship between a specified taxon and another organism.
==== common_name ====
String - A common name for a taxon that can be included as a taxon name string but is never valid.
==== describer ====
String - the describer(s) of a taxon.
==== fossil ====
String - A modified boolean_flag, either Y, N or B, representing whether a taxon name is a extinct fossil, exclusively extant, or present today and in fossils.
==== habitat ====
String - Description or identifier of the ecological or environmental area that a particular species is known to inhabit.
==== homonym ====
Boolean_flag - Boolean_flag indicating whether or not the determination was a homonym
==== rank ====
String - The taxonomic (hierarchical) rank of a taxon name.
==== rank_value ====
Number - A number representing the rank of a taxon with higher numbers representing higher positions in the taxonomic hierarchy.
==== rel_type ====
String - The taxonomic (hierarchical) relationship between the taxonomic concept indicated by the taxon name and its parent taxonomic concept. Can be Member, Junior synonym, etc.
==== status ====
String - The nomenclatural status of a taxon name using a formalized vocabulary.
==== taxon ====
String - A taxon name string.
==== taxon_author ====
String - The author(s) of a taxon with parenthesis surrounding the name of the author(s) if necessary.
==== tnuid ====
Number - The taxon name use identifier which uniquely identifies a taxon.
==== valid ====
String - A ''Valid'' or ''Invalid'' string representing the validity of a taxon name using subjective interpretations if warranted.

== See also ==
Visit any of the below links to find information about the other data domains defined by OJ_Break Version 2.

* [[OJ_Break v2 Agent Reference|Agent]]
* [[OJ_Break v2 Geographic Place Reference|Geographic Place]]
* [[OJ_Break v2 Institution Reference|Institution]]
* [[OJ_Break v2 Journal Reference|Journal]]
* [[OJ_Break v2 Literature Reference|Literature]]
* [[OJ_Break v2 Locality Reference|Locality]]
* [[OJ_Break v2 Media Reference|Media]]
* [[OJ_Break v2 Occurrence Reference|Occurrence]]
* [[OJ_Break v2 Search Reference|Search]]

OJ Break v2 Institution Reference

2015-04-21T14:45:28Z

Tyler: /* Elements */

OJ Break v2 Institution Reference

2015-04-21T14:44:09Z

Tyler: /* InstitutionBasic */

OJ Break v2 Occurrence Reference

2015-04-21T14:42:10Z

Tyler:

XBio:D Javascript Library Reference

2015-04-21T14:41:23Z

Tyler: /* Options */

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster'). Require additional dependencies (see below).
* offset - Number
* limit - Number
* icons - Object
* widget_options

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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 =====
* [http://en.wikipedia.org/wiki/Processing.js 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-21T14:40:50Z

Tyler: /* Valid Color Options */

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster'). Require additional dependencies (see below).
* offset - Number
* limit - Number
* icons - Object
* widget_options

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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

===== Additional Requirements =====
* [http://en.wikipedia.org/wiki/Processing.js 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-21T14:38:58Z

Tyler: /* Options */

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster'). Require additional dependencies (see below).
* offset - Number
* limit - Number
* icons - Object
* widget_options

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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

===== Additional Requirements =====
* [http://en.wikipedia.org/wiki/Processing.js 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 =====
====== Valid Color Options ======
Below is a list of the available colors that can be used as the background or node color:
* red
* scarlet
* orange
* yellow
* green
* blue
* cyan
* violet
* purple
* grey/gray
* white

NOTE: any color (that is, not limited to the above list) can be chosen by specifying its hexadecimal color string (for example, '#70CFF5').

====== 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-21T14:11:36Z

Tyler:

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster')
* offset - Number
* limit - Number
* icons - Object
* widget_options
===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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

===== Additional Requirements =====
* [http://en.wikipedia.org/wiki/Processing.js 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 =====
====== Valid Color Options ======
Below is a list of the available colors that can be used as the background or node color:
* red
* scarlet
* orange
* yellow
* green
* blue
* cyan
* violet
* purple
* grey/gray
* white

NOTE: any color (that is, not limited to the above list) can be chosen by specifying its hexadecimal color string (for example, '#70CFF5').

====== 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-20T21:28:59Z

Tyler: /* Options */

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster')
* offset - Number
* limit - Number
* icons - Object
* widget_options
===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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

===== Additional Requirements =====
* [http://en.wikipedia.org/wiki/Processing.js 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 =====
====== Valid Color Options ======
Below is a list of the available colors that can be used as the background or node color:
* red
* scarlet
* orange
* yellow
* green
* blue
* cyan
* violet
* purple
* grey/gray
* white

NOTE: any color (that is, not limited to the above list) can be chosen by specifying its hexadecimal color string (for example, '#70CFF5').

====== 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-20T21:27:14Z

Tyler: /* Options */

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster')
* offset - Number
* limit - Number
* icons - Object
* widget_options
===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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

===== Additional Requirements =====
* [http://en.wikipedia.org/wiki/Processing.js 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 =====
====== Valid Color Options ======
Below is a list of the available colors that can be used as the background or node color:
* red
* scarlet
* orange
* yellow
* green
* blue
* cyan
* violet
* purple
* grey/gray
* white

NOTE: any color (that is, not limited to the above list) can be chosen by specifying its hexadecimal color string (for example, '#70CFF5').

====== 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-20T21:25:50Z

Tyler: /* Options */

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster')
* offset - Number
* limit - Number
* icons - Object
* widget_options
===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* widget_options

==== showContributors ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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

===== Additional Requirements =====
* [http://en.wikipedia.org/wiki/Processing.js 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 =====
====== Valid Color Options ======
Below is a list of the available colors that can be used as the background or node color:
* red
* scarlet
* orange
* yellow
* green
* blue
* cyan
* violet
* purple
* grey/gray
* white

NOTE: any color (that is, not limited to the above list) can be chosen by specifying its hexadecimal color string (for example, '#70CFF5').

====== 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-20T21:23:46Z

Tyler: /* Valid Category Keywords */

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster')
* offset - Number
* limit - Number
* icons - Object
* widget_options
===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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'
* category - array of the below object elements
** type - a category keyword that will control 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* widget_options

==== showContributors ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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

===== Additional Requirements =====
* [http://en.wikipedia.org/wiki/Processing.js 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 =====
====== Valid Color Options ======
Below is a list of the available colors that can be used as the background or node color:
* red
* scarlet
* orange
* yellow
* green
* blue
* cyan
* violet
* purple
* grey/gray
* white

NOTE: any color (that is, not limited to the above list) can be chosen by specifying its hexadecimal color string (for example, '#70CFF5').

====== 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-20T21:22:13Z

Tyler: /* Category Options Formatting */

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster')
* offset - Number
* limit - Number
* icons - Object
* widget_options
===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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'
* category - array of the below object elements
** type - a category keyword that will control 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: '<nowiki>http://domain.url/index.html</nowiki>'}, {type: 'occurrence', handler_url: '<nowiki>http://domain.url/occurrence.html</nowiki>'}]});

====== Valid Category Keywords ======
Below is a list of available category keywords that the ''category'' array option can take (Note: the keyword spelling must match exactly what is seen below):
* '''all'''
* '''taxa'''
* '''cuids'''
* '''inst'''
* '''agents'''
* '''journals'''
* '''orgs'''
* '''coll_methods'''
* '''locs'''
* '''places'''

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* widget_options

==== showContributors ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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

===== Additional Requirements =====
* [http://en.wikipedia.org/wiki/Processing.js 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 =====
====== Valid Color Options ======
Below is a list of the available colors that can be used as the background or node color:
* red
* scarlet
* orange
* yellow
* green
* blue
* cyan
* violet
* purple
* grey/gray
* white

NOTE: any color (that is, not limited to the above list) can be chosen by specifying its hexadecimal color string (for example, '#70CFF5').

====== 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-20T21:19:13Z

Tyler: /* Description */

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster')
* offset - Number
* limit - Number
* icons - Object
* widget_options
===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== 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'
* category - array of the below object elements
** type - a category keyword that will control 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', {category: [{type: 'taxa', handler_url: '<nowiki>http://hol.osu.edu/index.html</nowiki>'}, {type: 'cuids', handler_url: '<nowiki>http://hol.osu.edu/spmInfo.html</nowiki>'}]});

====== Valid Category Keywords ======
Below is a list of available category keywords that the ''category'' array option can take (Note: the keyword spelling must match exactly what is seen below):
* '''all'''
* '''taxa'''
* '''cuids'''
* '''inst'''
* '''agents'''
* '''journals'''
* '''orgs'''
* '''coll_methods'''
* '''locs'''
* '''places'''

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* widget_options

==== showContributors ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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

===== Additional Requirements =====
* [http://en.wikipedia.org/wiki/Processing.js 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 =====
====== Valid Color Options ======
Below is a list of the available colors that can be used as the background or node color:
* red
* scarlet
* orange
* yellow
* green
* blue
* cyan
* violet
* purple
* grey/gray
* white

NOTE: any color (that is, not limited to the above list) can be chosen by specifying its hexadecimal color string (for example, '#70CFF5').

====== 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-20T21:17:43Z

Tyler: /* Description */

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster')
* offset - Number
* limit - Number
* icons - Object
* widget_options
===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* 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 =====
* widget_options - Object

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== Search ===
==== showSearch ====
===== Description =====
A JQuery UI autocomplete search bar which can search for taxa, cuids, institutions, agents, journals, organizations, collecting methods, 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'
* category - array of the below object elements
** type - a category keyword that will control 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', {category: [{type: 'taxa', handler_url: '<nowiki>http://hol.osu.edu/index.html</nowiki>'}, {type: 'cuids', handler_url: '<nowiki>http://hol.osu.edu/spmInfo.html</nowiki>'}]});

====== Valid Category Keywords ======
Below is a list of available category keywords that the ''category'' array option can take (Note: the keyword spelling must match exactly what is seen below):
* '''all'''
* '''taxa'''
* '''cuids'''
* '''inst'''
* '''agents'''
* '''journals'''
* '''orgs'''
* '''coll_methods'''
* '''locs'''
* '''places'''

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* widget_options

==== showContributors ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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

===== Additional Requirements =====
* [http://en.wikipedia.org/wiki/Processing.js 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 =====
====== Valid Color Options ======
Below is a list of the available colors that can be used as the background or node color:
* red
* scarlet
* orange
* yellow
* green
* blue
* cyan
* violet
* purple
* grey/gray
* white

NOTE: any color (that is, not limited to the above list) can be chosen by specifying its hexadecimal color string (for example, '#70CFF5').

====== 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

XBio:D Javascript Library Reference

2015-04-20T21:17:06Z

Tyler: /* Options */

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

== 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 [[OJ_Break API Access#key|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 [[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]].



1 <!DOCTYPE HTML>
2 <html>
3 <head>
4 <meta charset="UTF-8"/>
5 <title>xBio:D API Test</title>
6 <link rel="stylesheet" type="text/css" href="xbiod.css">
7 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js</nowiki>"></script>
8 <script type="text/javascript" src="<nowiki>http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js</nowiki>"></script>
9 <script type="text/javascript" src="<nowiki>https://maps.googleapis.com/maps/api/js?sensor=false</nowiki>"></script>
10 <script type="text/javascript" src="<nowiki>http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js</nowiki>"></script>
11 <script>
12 // Call the loader for the current page
13 $(document).ready(loader);
14
15 function loader() {
16
17 // Initialize xBio:D library
18 xbiod.init(['visual','taxon'], /*API_KEY*/, function() {
19 var tnuid = 605;
20
21 // Load xBio:D components
22 var visual = new xbiod.visual();
23 var taxon = new xbiod.taxon();
24
25 // Load map
26 visual.showGoogleMap('map_id', tnuid);
27
28 // Load included taxa
29 taxon.showIncludedTaxa('included_id', tnuid, {show_num_spms: 'Y'});
31
32 });
33 }
34 </script>
35 <style type="text/css">
36 html { height: 100% }
37 body { height: 100%; margin: 0; padding: 0 }
38 #map_id { height: 50% }
39 #included_id { height: 100% }
40 </style>
41 </head>
42 <body>
43 <div id="map_id"/>
44 <div id="included_id"/>
45 </body>
46 </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)
* 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 '''<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)

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 [https://developers.google.com/maps/documentation/javascript/tutorial#HTML5 Google Maps Documentation on HTML 5] for more info.

<!DOCTYPE html>

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

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 ===
<script type="text/javascript" src=<nowiki>"https://maps.googleapis.com/maps/api/js?sensor=false"</nowiki>></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 [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 ===
<script type="text/javascript" src=<nowiki>"http://osuc.biosci.ohio-state.edu/JSLib/xbiod_lib/xbiod.js"</nowiki>></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 [[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 ====
// 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 [[XBio:D Javascript Library Reference#Reference|Reference]] section.

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

<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 =====
* 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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* agent_id ([[OJ_Break API Data Type Glossary#collector_id_2|?]])
* options

===== Options =====
* info_element_id - ID String (defaults to element_id parameter)
* generalFormat - HTML String
* markers - String ('spiderfy' or 'cluster')
* offset - Number
* limit - Number
* icons - Object
* widget_options
===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* author_id ([[OJ_Break API Data Type Glossary#author_id_2|?]])
* options
===== Options =====
* limit - Number
* offset - Number
* widget_options - Object

=== Occurrence ===
==== showBiologicalInfo ====
===== Description =====
Displays both the habitat and associations for a selected occurrence identifier (cuid).

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

==== showOccurrenceInfo ====
===== Description =====
Displays collecting trip 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

==== showDeterminations ====
===== Description =====
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 =====
* element_id ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* occurrence_id ([[OJ_Break API Data Type Glossary#occurrence_id|?]])
* options
===== Options =====
* widget_options - Object

==== showSpecimenInfo ====
===== 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

=== Search ===
==== showSearch ====
===== Description =====
A JQuery UI autocomplete search bar which can search for taxa, cuids, institutions, agents, journals, organizations, collecting methods, 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'
* category - array of the below object elements
** type - a category keyword that will control 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', {category: [{type: 'taxa', handler_url: '<nowiki>http://hol.osu.edu/index.html</nowiki>'}, {type: 'cuids', handler_url: '<nowiki>http://hol.osu.edu/spmInfo.html</nowiki>'}]});

====== Valid Category Keywords ======
Below is a list of available category keywords that the ''category'' array option can take (Note: the keyword spelling must match exactly what is seen below):
* '''all'''
* '''taxa'''
* '''cuids'''
* '''inst'''
* '''agents'''
* '''journals'''
* '''orgs'''
* '''coll_methods'''
* '''locs'''
* '''places'''

=== Taxon ===
==== showAssociations ====
===== Description =====
Displays all associations for a specified taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* widget_options

==== showContributors ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* limit - Number
* offset - Number
* inst_id
* widget_options

==== showHabitats ====
===== Description =====
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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== Options =====
* inst_id
* widget_options

==== showSynonyms ====
===== Description =====
Displays all taxa which are objectively or subjectively synonymous with a selected taxon.
===== Parameters =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 =====
* [[xBio:D Javascript Library Reference#Element_Containers|element_id]]
* tnuid
* options
===== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* options
===== Options =====
* pnids ([[OJ_Break API Data Type Glossary#pnid_2|?]]) - array of number
* inst_id ([[OJ_Break API Data Type Glossary#inst_id_2|?]])
* precDecimals ([[OJ_Break API Data Type Glossary#precDecimals|?]])
* showChildren ([[OJ_Break API Data Type Glossary#showChildren|?]])

===== Additional Requirements =====
* [https://developers.google.com/maps/documentation/javascript/ Google Maps API v3]
* [http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclusterer/docs/reference.html MarkerClusterer]
* [https://github.com/jawj/OverlappingMarkerSpiderfier Overlapping Marker Spiderfier]

==== 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 ([[xBio:D Javascript Library Reference#Element_Containers|?]])
* tnuid ([[OJ_Break API Data Type Glossary#tnuid_2|?]])
* requestedNode
* options

===== Options =====
* show_num_spms
* inst_id
* show_syns
* show_fossils
* types_only
* nodeColor - string or hexadecimal number
* backgroundColor - string or hexadecimal number
* handler_url - URL string
* 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

===== Additional Requirements =====
* [http://en.wikipedia.org/wiki/Processing.js 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 =====
====== Valid Color Options ======
Below is a list of the available colors that can be used as the background or node color:
* red
* scarlet
* orange
* yellow
* green
* blue
* cyan
* violet
* purple
* grey/gray
* white

NOTE: any color (that is, not limited to the above list) can be chosen by specifying its hexadecimal color string (for example, '#70CFF5').

====== 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: '<nowiki>http://hol.osu.edu/index.html</nowiki>'});

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.

[[File:link_button_tut.png|none|frame|Link button present on highlighted node. This button would not be present if handler_url option was not specified.]]

====== 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:

// 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/"});

<hr>


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

OJ Break v2 Media Reference

2015-04-20T20:00:03Z

Tyler: /* See also */

'''Introduction'''

OJ_Break is the name of the xBio:D RESTful API service which enables the discovery of data within the xBio:D database. The API can respond with JavaScript Object Notation (JSON), XML, or JSON with padding (JSONP) and accepts HTTP GET and POST requests indiscriminately. The backend of the API is written in Oracle's PL/SQL database language, which is fast but often inflexible, while a Python presentation layer mitigates request handling and authentication.

OJ_Break Version 2 is a new and improved edition of the work started in Version 1. Version 2 introduces a completely restructured and standardized data model to further enhance the functionality of the xBio:D database.

== API Information and Access ==
This page specifies the data defined by OJ_Break Version 2, more precisely those that are defined by the '''Media''' data domain. To get information on any of the other data domains defined in OJ_Break Version 2, visit the [[#See_also|See also]] section.

== Media Data Type Glossary ==
=== Classes ===
==== ImageExtended (extends [[#MediaExtended (extends MediaBasic)|MediaExtended]]) ====
* ''thumb'': URL
* ''raw'': URL

==== LocalityImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''locality'': [[OJ_Break v2 Locality Reference#LocalityBasic|LocalityBasic]]

==== MediaBasic ====
* ''media_id'': ''[[#media_id|media_id]]''
* ''media_type'': ''[[#media_type|media_type]]''
* ''media_url'': ''[[#media_url|media_url]]''
* ''media_source'': ''[[#media_source|media_source]]''
* ''public'': ''[[#public|public]]''

==== MediaExtended (extends [[#MediaBasic|MediaBasic]]) ====
* ''caption'': ''[[#caption|caption]]''
* ''copyright'': ''[[#copyright|copyright]]''
* ''license'': ''[[#license|license]]''
* ''enterer'': ''[[#enterer|enterer]]''

==== OccurrenceImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''occurrence'': [[OJ_Break v2 Occurrence Reference#OccurrenceTrimmed (extends OccurrenceBasic)|OccurrenceTrimmed]]
* ''parts'': array of ''[[#part|part]]''
* ''angle'': ''[[#angle|angle]]''
* ''technique'': ''[[#technique|technique]]''
* ''notes'': String

==== OccurrenceRecordingExtended (realizes [[#MediaExtended (extends MediaBasic)|MediaExtended]]) ====
* ''occurrence'': [[OJ_Break v2 Occurrence Reference#OccurrenceTrimmed|OccurrenceTrimmed]]

==== TaxonImageExtended (realizes [[#ImageExtended (extends MediaExtended)|ImageExtended]]) ====
* ''taxon'': [[OJ_Break v2 Taxon Reference#TaxonBasic|TaxonBasic]]

==== VideaExtended (realizes [[#ImageExtended extends MediaExtended)|ImageExtended]]) ====
* ''taxon'': [[OJ_Break v2 Taxon Reference#TaxonBasic|TaxonBasic]]

=== Elements ===
==== angle ====
String - A description of the angle the media was taken.
==== caption ====
String - A summary of the media.
==== copyright ====
String - Copyright information.
==== enterer ====
String - The media enterer's name.
==== license ====
String - Licensing information.
==== media_id ====
Number - A numeric identifier that uniquely identifies a media piece.
==== media_source ====
String - The name of the source of the media.
==== media_type ====
String - A description of the type of the media.
==== media_url ====
URL - The location to the media file.
==== public ====
Boolean_flag - A flag that specifies whether or not the media is public.
==== technique ====
String - A description of the method by which the media was taken.

== See also ==
Visit any of the below links to find information about the other data domains defined by OJ_Break Version 2.

* [[OJ_Break v2 Agent Reference|Agent]]
* [[OJ_Break v2 Geographic Place Reference|Geographic Place]]
* [[OJ_Break v2 Institution Reference|Institution]]
* [[OJ_Break v2 Journal Reference|Journal]]
* [[OJ_Break v2 Literature Reference|Literature]]
* [[OJ_Break v2 Locality Reference|Locality]]
* [[OJ_Break v2 Occurrence Reference|Occurrence]]
* [[OJ_Break v2 Search Reference|Search]]
* [[OJ_Break v2 Taxon Reference|Taxon]]

OJ Break v2 Occurrence Reference

2015-04-20T19:59:08Z

Tyler: /* Occurrence */

OJ Break v2 Locality Reference

2015-04-20T19:58:17Z

Tyler: /* Locality */

OJ Break v2 Literature Reference

2015-04-20T19:57:27Z

Tyler: /* Literature */

OJ Break v2 Journal Reference

2015-04-20T19:56:28Z

Tyler: /* Journal */