Overview
JavaScript API
Documentation
JSON Explorer
Image Explorer
Example Code
CSIP
Strand Map Service

SMS JavaScript API Documentation

The JavaScript API lets Web developers insert interactive AAAS Strand Maps into Web pages using JavaScript and place custom content into the bubble inside the maps. The dynamic interfaces that are generated by this service require no plug-ins and are compatible in Internet Explorer, Firefox and Safari browsers.

Documentation for the JavaScript API v1.0

This documentation assumes familiarity with HTML, JavaScript and CSS.

 

Contents

 

Creating an interactive map using the SMS JavaScript API

Follow these simple steps to place an interactive strand map in your page and customize the content displayed within it.

 

Step 1: Include the following DOCTYPE declaration at the top of the HTML page:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

This Document Type Declarion is required for the interactive maps to function properly.

Step 2: Insert the map JavaScript library into the header of the HTML page:

<script type="text/javascript" src="http://strandmaps.nsdl.org/cms1-2/jsapi/maps?api=v1"></script>

Step 3: Create a script tag to include code from the JavaScript API to customize and display information in the map:

<script type="text/javascript" language="javascript">

// Your JavaScript code goes here...

</script>

or

<script type="text/javascript" src="your_javascript.js"></script>

Step 4: Create a style tag or specify an external style sheet to define styles for the page and to override the default CSS styles, which are automatically applied:

<style type="text/css">

// Your styles go here...

</style>

or

<LINK href="your_styles.css" rel="stylesheet" type="text/css">

Step 5: Insert DIV tags to include the desired elements from the service: A custom header, the strand map selector, the interactive strand map and/or a default content section for the page:

<!-- Place all content that goes above the strand selector and strand map in this element. -->
<div id="customHeader">
<p>This content is displayed at the top of the page</p>
</div>

<!-- The Strand Selector renders a widget for selecting the strand maps (optional) -->
Optional attributes:
-multiselect - The type of selector to display: 'true' to diplay a multi-level selector that includes topics and maps in sub-menus; 'false' displays a flat list of topics only (defaults to false)

<div id="strandSelector" multiselect="true"></div>

<!-- The Strand Map element renders the interactive maps and table of contents.
Optional attributes:
-mapColor - The color of the map boxes. Defaults to #E2E8F6.
-highlightColor - The color of the highlight around the map boxes. Defaults to #E2E8F6.
-mapHeight - The height of the map. If not specified, the map will resize itself to fit the maximum height in the browser window.
-mapWidth - The width of the map. If not specified, the map will resize itself to fit the maximum width in the browser window. -->
<div id="strandMap" mapColor="#A7DFC4" highlightColor="#A7DFC4"></div>

<!-- Place all content that goes below the strand selector and strand map in this element. -->
<div id="defaultContent" style="display:none">
<p>This content is displayed in the body of the page only when the interactive map is not being displayed.</p>
</div>

 

The JavaScript API

The JavaScript API provides objects and methods that allow you to customize the maps that are displayed within your page.

 

Class StrandMap

StrandMap is a singleton object that controls the appearance, features and behaviors associated with the interactive maps. It provides a handle to the InfoBubble object and allows you to register actions that are performed when map-level events occur, such as when a user clicks on a benchmark in a map. It also provides access to data about the basic objects in the concept map information space such as the benchmarks, other maps, chapters and details about each.

Methods

getMapId() -> String - Gets the internal SMS ID of the current map.

getMapJson() -> JSON - Gets the record data for the current map returned in JSON form. See this example JSON record for an example of this data format. The data returned from this function starts at the 'itemRecord' node.

getParentIds() -> Array of Strings - Gets the internal SMS IDs of all nodes in the SMS space for which the current map has relationship of 'is part of,' as an array of Strings.

getBenchmarkIds() -> Array of Strings - Gets the internal SMS IDs of all benchmarks within the current map, as an array of Strings.

getInfoBubble() -> InfoBubble - Gets the InfoBubble object.

getSelectedBenchmarkId() -> String - Gets the internal SMS ID for the selected benchmark. If no benchmark is selected, returns null. This is typically called after the onbenchmarkselect event is fired.

openInfoBubbleOnBenchmark(benchmarkId) - Opens the InfoBubble on the given benchmark and fires all associated events. If the given benchmark does not exist within the current map, nothing is done.

benchmarkId - An internal SMS ID for a given benchmark.

getSelectedBenchmarkRecordJson() -> JSON - Gets the record data for the selected benchmark returned in JSON form, or null if no benchmark is currently selected. The data returned from this function starts at the 'itemRecord' node.

getReferringMapId() -> String - Gets the internal SMS ID of the map that was clicked to view this map, which occurs when a user views the related benchmarks in the interactive map viewer, or null if not available.

getSelectedBenchmarkHtml() -> String - Gets HTML that describes the selected benchmark, or null if none is currently selected.

setPrintViewContent(content) - Sets the content to display in the print view portion of the map.

content - HTML content

enableMisconceptions(Boolean) - Enables or disables the ability to view misconceptions for a given map. When enabled, the user is presented with a link button to view/hide the misconceptions for those maps that have them, displayed directly over the map. Default behavior is disabled.

Events

onload - This event is fired when the StrandMap first loads and is ready to accept calls to its methods.

onbenchmarkselect -This event is fired each time a benchmark is selected.

onprintviewdisplay - This event is fired each time the print view is displayed. If a benchmark is displayed in the print view it will be returned from the getSelectedBenchmarkId() and getSelectedBenchmarkRecordJson() methods.

 

Class InfoBubble

InfoBubble is a singleton object that controls the content, appearance, features and behaviors associated with the information bubble widget that appears in the maps. It allows you to add or remove tabs, register actions that are performed when the bubble is opened and closed, and access data associated with the bubble.

Methods

setTitle(title) - Sets the title displayed in the bubble.

title - HTML content

getTitle() -> String - Gets the title displayed in the bubble.

setContent(content) - Sets the content displayed in the top portion of the bubble. If no tabs are added to the InfoBubble, this will be the only content displayed.

content - HTML content

getContent() -> String - Gets the content displayed in the top portion of the bubble.

setBuiltinContent(contentType) - Sets the content area with built-in content, which displays a full description of the benchmark.

contentType - Values include:
    benchmarkonly - Displays a full description of the benchmark and the associated grade range.
    benchmarkdetails - Displays a full description of the benchmark, the associated grade range, and any aligned NSES standards.
    benchmarkrelatedmaps - Displays a list of maps in which the selected benchmark appears, with links to those maps.

setMaxSize(width,height) - Sets the maximum size of the bubble and adjustst it's size if it is visible. Default size is 650w X 600h if not specified.

width - The maximum width of the bubble, in pixels
height - The maximum height of the bubble, in pixels

addTab(infoBubbleTab) - Adds a tab in the InfoBubble. Tabs appear in the order they are added.

infoBubbleTab - An InfoBubbleTab instance.

addBuiltinTab(tabType, label) -> InfoBubbleTab - Adds a built-in tab to the InfoBubble.

tabType - Values include:
    relatedbenchmarks - Displays the related benchmarks for the selected benchmark.
    nses - Displays the NSES standards aligned to the selected benchmark.
    nsdlaligned - Displays the educational resources from NSDL that are aligned to the selected benchmark. Define an optional array in your JavaScript smsCollectionsAligned with a list of collection keys to limit the scope of aligned resources to those from the specified collections. Default is to show all.
    nsdlrelated - Displays the educational resources from NSDL that are related to the selected benchmark by performing a keyword search over the library. Define an optional array in your JavaScript smsCollectionsRelated with a list of collection keys to limit the scope of aligned resources to those from the specified collections. Default is to show all.

label - The label for tab (text).

selectTab(infoBubbleTab) - Selects the given tab and fires the 'onselect' event on the tab.

infoBubbleTab - An InfoBubbleTab instance.

hideTab(infoBubbleTab) - Makes a tab non-visible without changing it's contents.

infoBubbleTab - An InfoBubbleTab instance.

showTab(infoBubbleTab) - Makes a tab visible without changing it's contents, reversing the action applied with method hideTab(infoBubbleTab).

infoBubbleTab - An InfoBubbleTab instance.

hideTabPane(showLoadingMsg) - Makes the entire tab pane non-visible without changing it's contents. This method works independently from the hideTab(infoBubbleTab) and showTab(infoBubbleTab) methods.

showLoadingMsg - A boolean value. If set to true, a 'Loading...' message is displayed in place of the tab pane until showTabPane() is called.

showTabPane() - Makes the entire tab pane visible without changing it's contents, reversing the action applied with method hideTabs(). This method works independently from the hideTab(infoBubbleTab) and showTab(infoBubbleTab) methods.

 

Events

onopen - This event is fired each time the InfoBubble is opened.

onclose - This even is fired each time the InfoBubble is closed.

 

Class InfoBubbleTab

InfoBubbleTab objects are used to control the tabs that appear inside the InfoBubble widget. Each InfoBubbleTab object describes a single tab, its content and any action that occurs when a user selects the tab.

Constructor

InfoBubbleTab(label) - Constructs a new InfoBubbleTab with the given label.

label - The label displayed on the tab.

Methods

setContent(content) - Sets the content displayed in the tab.

content - HTML content

getContent() -> String - Gets the content currently displayed in the tab.

Events

onselect - This event is fired each time the tab is selected.

 

Namespace SMSEvent

This namespace contains functions used to register event handlers for all objects.

Methods

addListener(object, eventName, handler) - Adds a listener and handler on the given object for the given event.

object - The object to listen on
eventName - The event to listen for
handler - The function that is called when the given event is fired.

 

Included APIs:

The SMS service includes two externally developed open source JavaScript APIs that can be used in conjunction with the SMS API to simplify your coding: Prototype and Scriptaculous. These libraries are included in your page automatically when you use the API and do not need to be referenced separately. The SMS JavaScript uses these in it's own implementation.

  • Prototype - "Prototype is a JavaScript Framework that aims to ease development of dynamic web applications. Featuring a unique, easy-to-use toolkit for class-driven development and the nicest Ajax library around, Prototype is quickly becoming the codebase of choice for web application developers everywhere." Prototype v1.5.1.1 is included for you.
  • Scriptaculous - "script.aculo.us provides you with easy-to-use, cross-browser user interface JavaScript libraries to make your web sites and web applications fly." Scriptaculous v1.7.1_b3 is included for you. Note that only the Effects library is provided by the SMS.

 

CSS Styles:

The SMS service provides a set of CSS styles that are applied automatically. These styles are used to define default colors and fonts for the content that is displayed in the maps and information bubble, as well as to control the sizing and margins of the objects that are displayed. When customizing your map you can override the default styles to apply your own color, font and other preferences. To do so, simply include a style element in the header of your page or specify an external style sheet after the point in your code where the service JavaScript is referenced. Use the links below to view the styles that are being applied by the service.

 

Example Code:

 

JSON Data

The service provides data in JSON (JavaScript Object Notation) form for all objects in the SMS information space, via URL. The space contains objects for maps, grade groups, strands, benchmarks, clusters, chapters and the atlas. These data may be accessed using JavaScript and optionally returned asynchronously to a callback function. Using the service and the relationships supplied in the datum for each object, it is possible to traverse the nodes in the graph and discover the attributes of all objects.

See the JSON Explorer to access and explore the JSON data from the SMS service.

JSON is widely used in AJAX style JavaScript programming and is found in public APIs such as those provided Yahoo! and in rich Web applications such as GMail. For more information about this data format and how it may be used, see Douglas Crockford's site JSON.org and JSON: The Fat-Free Alternative to XML and the Yahoo! developer documentation.

JSON Requests and Responses

SMS JSON service requests are expressed as HTTP argument/value pairs. These requests must be in either GET or POST format. Responses are returned in JSON format, which varies in structure and content depending on the request as shown below in the examples section of this document.

The JSON responses contain the same data that is returned by the CSIP service when requesting the SMS-JSON format, as described in the CSIP Query documentation. The JSON format is a direct transformation from the CSIP XML output to JSON.

  • Base URL - the base URL used to access the service. This is the portion of the request that precedes the request arguments. For example http://strandmaps.nsdl.org/cms1-2/jsapi/json
  • Request arguments - the argument=value pairs that make up the request and follow the base URL.
  • JSON response envelope - the JSON container used to return data. This container returns different types of data depending on the request made.

URL Pattern

The format of the request consists of the base URL followed by the ? character followed by one or more argument=value pairs, which are separated by the & character. All arguments must be encoded using the syntax rules for URIs. This is the same encoding scheme that is described by the OAI-PMH.

Sample Request

http://strandmaps.nsdl.org/cms1-2/jsapi/json?
ObjectID=SMS-MAP-0048&Format=SMS-JSON&callBack=myCallbackFn&DetailLevel=Detailed

Arguments

  • ObjectID (required) - The SMS object identifier
  • Format (required) - The format. Must be either SMS-JSON (to retrieve details about the object) or SVG-JSON (to retrieve the object's visualization SVG in JSON format).
  • callBack (optional) - A callback function to wrap the JSON response in. If none is supplied, the JSON will be returned without a callback function.
  • DetailLevel (optional) - The data detail level (defaults to 'Detailed' if not specified)

Examples

http://strandmaps.nsdl.org/cms1-2/jsapi/json?
ObjectID=SMS-MAP-0048&callBack=myCallbackFn&Format=SMS-JSON&DetailLevel=Detailed (view) - Full data for map ID SMS-MAP-0048.

 

Map Images

The service provides access to images for all map visualizations via URLs. The images may be useful for applications or pages that wish to access or display images without the interactive features. Images are available for maps, strands, grade groups, and related benchmarks in JPG, PNG, PDF and SVG format. Images are not available for clusters, chapters or the atlas object.

See the Image Explorer to access and explore the images from the service. The images may also be retrieved using the CSIP service.

Default Map Images

Default images are available in blue color (hex code #E2E8F6), with no scaling applied and a concept box size of 4. The URL pattern to access these images is as follows:

URL Pattern

http://strandmaps.nsdl.org/cms1-2/jsapi/map_images/default/{sms-id}.{ext}

{sms-id} - The SMS ID for a map, strand, grade band or related benchmark.

{ext} - The image extension. One of JPG, PNG, PDF or SVG (case sensitive).

Examples

http://strandmaps.nsdl.org/cms1-2/jsapi/map_images/default/SMS-MAP-0048.PNG (view) - PNG image for map "Changes in the Earth's Surface."

http://strandmaps.nsdl.org/cms1-2/jsapi/map_images/default/SMS-MAP-1232.JPG (view) - JPG image for map "Mathematical Processes."

http://strandmaps.nsdl.org/cms1-2/jsapi/map_images/default/SMS-BMK-1717.PDF (view) - PDF for benchmarks related to "Scientists' explanations about what happens in the world come partly from what they observe, partly from what they think."

Custom Map Images

Custom map images are available in all Web colors, scaled from 1% to 200%, and generated with a variety of concept box sizes.

URL Pattern

http://strandmaps.nsdl.org/cms1-2/jsapi/map_images/{color}/{concept-size}/{scale}/{sms-id}.{ext}

{color} - The color of the image. Value must be a valid named or hexadecimal color. See Web Colors on Wikipedia for a list of named and hexadecimal color values.

{concept-size} - The size of the concept boxes in the image. Value must be an integer from 1 to 6, where 1 generates a smaller map with minimum text displayed in the boxes and 6 generates a larger map with the maximum text displayed. Default images use a value of 4.

{scale} - The scaling percentage applied to the image. Value must be an integer from 1 to 200. Scaling is applied only to JPG and PNG images. Scaling is ignored for PDF and SVG images, however a value must still be supplied.

{sms-id} - The SMS ID for a map, strand, grade band or related benchmark.

{ext} - The image extension. One of JPG, PNG, PDF or SVG (case sensitive).

Examples

http://strandmaps.nsdl.org/cms1-2/jsapi/map_images/LightBlue/6/15/SMS-MAP-0048.PNG (view) - PNG image, color LightBlue, concept size 6, scaled to 15%, for map "Changes in the Earth's Surface."

http://strandmaps.nsdl.org/cms1-2/jsapi/map_images/8ECF8E/4/100/SMS-MAP-1232.JPG (view) - JPG image, color #8ECF8E, concept size 4, scaled to 100%, for map "Mathematical Processes."

http://strandmaps.nsdl.org/cms1-2/jsapi/map_images/Gold/6/50/SMS-BMK-1717.PDF (view) - PDF, color Gold, concept size 6, for benchmarks related to "Scientists' explanations about what happens in the world come partly from what they observe, partly from what they think." Note that scaling is ignored for PDF and SVG images.

 

Author: John Weatherley
Last revised $Date: 2011/06/09 22:11:25 $