Ijax javascript library

Examples

This very simple example shows how easy it is to incorporate a dynamic share price in to your own web page.

View the source of the page to see that the steps are as simple as:

  • Reference Iguana's Ijax javascript library
  • Initialize the library with your site code
  • Optionally set some formatting styles
  • Call the function Ijax.quote with the code you're interested in and a callback function
  • In the callback function, use the quote provided to set various elements on the page by their CSS ID, optionally making use of the Ijax formatting functions

This more complex example shows all of the requests on a single page.

Initialization

You must call Ijax.initialize(site, default_params) before any other Ijax functions.

The site parameter is assigned to you by Iguana.

The optional default_params parameter can be used to set any number of defaults.

Defaults

You can use the default_params parameter to Ijax.initialize or Ijax.set_default_param(param, value) to set defaults.

The major defaults that you might want to override are:

baseurl defaults to http://ijax.iguana2.com/. You would override this only if you hosted your own Ijax server.

method defaults to Ijax.METHOD_DYNAMIC_SCRIPTS. You could override it with Ijax.METHOD_XML_HTTP_REQUEST but you should read the cross domain discussion first.

onFailure is a function that is called in the event of an error. Please read the error page.

onAuthenticate is a function that is called if any request causes the error Ijax.ERR_AUTH_REQUIRED. Note that onFailure is called first so you should not try to reauthenticate in the onFailure function.

By default, both of these callbacks do nothing.

In addition, you can set any number of default parameters to simplify your requests. Note that if you do this, then all the parameters you set defaults for will be passed to all requests.

You can use Ijax.set_default_params(object) to set multiple defaults in one go.

Authentication

You call Ijax.authenticate(token) to set the authentication token that the Ijax library will send with each request. Please read the authentication page to learn how to obtain a token.

You can also set the token when you initialize Ijax like this:

Ijax.initialize('my_site_code', { auth: 'abc123' })

If the token expires, then the onAuthenticate function is called. Since you may make any number of Ijax requests before the first one reponds that the token has expired, calls to onAuthenticate are serialized by Ijax.

In your onAuthenticate function you should obtain a new token and possibly restart any requests that failed. The simplest way of doing this might be to reload the page. A more sophisticated solution would make an AJAX request to your own server (no cross domain problem) and cause it to make an XML request to the Ijax server (authenticated by IP) for a new token.

Requests

The request functions take the primary parameter (e.g. code), a function to callback on success (on_result) and optionally, any extra parameters as an object.

The responses generally mirror the XML DTD except that the JSON data uses lists where appropriate.

code should be a valid ticker code; codes should be a comma separated list of valid ticker codes.

Use the simulator to explore the data.

Ijax.quote(code, on_result, params) 
Ijax.index_quote(code, on_result, params) 
Ijax.depth(code, on_result, params) 
Ijax.trades(code, on_result, params) 
Ijax.watchlist(codes, on_result, params) 
Ijax.indexlist(code, on_result, params) 
Ijax.recent_news(exchange, on_result, params) 
Ijax.news_history(code, on_result, params) 
Ijax.stock_history(code, on_result, params) 
Ijax.index_history(code, on_result, params) 
Ijax.market_scan(keyword, on_result, params)
Ijax.market_summary(on_result, params)
Ijax.top_rises(on_result, params)
Ijax.top_falls(on_result, params)
Ijax.top_volume(on_result, params)
Ijax.top_value(on_result, params)
Ijax.code_search(code_prefix, keyword, on_result, params) 

Adding extra parameters

Use the params argument to add extra parameters such as { depth_levels: 10 }.

Note that you can't override the callback or callback_param parameters because they are used by the Ijax library.

You can install an error handler for a specific request with:

{ onFailure: function(error) { ... } }

You can also replace the response handler for a specific request with:

{ onSuccess: function(response) { ... } }

If you do provide an onSuccess method, then your on_result function will not be called unless you call it from your new onSuccess handler.

Accessing the full response

The onSuccess callbacks are passed parts of the response as function arguments to keep them simple. The full response that you see on simulator is available via this.response.

For example, within the onSuccess method of a depth request you could refer to this.response.depth.bids.total_volume.

Formatting data for display

The following functions format their argument appropriately for display.

For example, stock prices when formatted in dollars should have at least 2 decimal places (whole cents) but not more than 4.

Volume, turnover and value over formatted with thousand separators (commas). Turnover is shown to whole dollars only, value is in whole cents. You might use the former when display quotes and the latter for trades.

Ijax.fmt_price(price)
Ijax.fmt_dollars_price(price)
Ijax.fmt_cents_price(price)
Ijax.fmt_volume(volume)
Ijax.fmt_turnover(turnover)
Ijax.fmt_value(value)
Ijax.fmt_change(price_change)
Ijax.fmt_dollars_change(change)
Ijax.fmt_cents_change(change)
Ijax.fmt_index_price(price)
Ijax.fmt_index_change(change)
Ijax.fmt_pct_change(pct_change)
Ijax.fmt_date(date)
Ijax.fmt_time(time)
Ijax.fmt_datetime(time)
Ijax.fmt_time_ex(time, fmt)

Ijax.fmt_price and Ijax.fmt_price_change look at the default price_in_dollars to determine whether to call the dollars or cents formatting functions. You can set the default during initialization with Ijax.set_default_param('price_in_dollars', 0 or 1).

Setting format defaults

You can customize aspects of the formatting with Ijax.set_fmt_style.

For example, Ijax.set_fmt_style('up_prefix_html', '<img src="up_arrow.png">') would cause all positive changes to appear with up_arrow.png in front of them.

You can use Ijax.set_fmt_styles(object) to set multiple styles in one go.

The styles that can be set and their defaults are:

  price_in_dollars: 1
  dollars_price_prefix_html: ''
  no_price_html: ''
  up_class: ''
  up_prefix_html: '+'
  down_class: ''
  down_prefix_html: '-'
  no_change_html: ''
  no_pct_change_html: ''
  no_volume_html: ''
  turnover_prefix_html: '$'
  no_turnover_html: ''
  value_prefix_html: '$'
  no_value_html: ''
  pct_change_suffix_html: '%'
  date_fmt: 'Y-m-d'
  time_fmt: 'H:i:s'
  datetime_fmt: 'Y-m-d H:i:s'

The no_something_html defaults are used when the value is zero. You might want them to be "0", "n/c", "$0.00", "-" or &nsbp; or blank, for instance.

The up and down_class are helpful because you might want to change the color of the text depending on the direction of the change.

You would otherwise use normal CSS to control the appearance of the other fields.

The date and time formatting specifiers are a subset of the PHP date function because the times are represented as local times. The valid specifiers are:

a
am or pm
A
AM or PM
d
Day of month: 01 - 31
D
Short weekday name: Mon - Sun
F
Long month name: January - December
g
Hours: 1 - 12
G
Hours: 01 - 12
h
Hours: 0 - 23
H
Hours: 00 - 23
i
Minutes: 00 - 59
j
Day of month: 1 - 31
l
Long weekday name: Monday - Sunday
m
Month: 01 - 12
M
Short month name: Jan - Dec
s
Seconds: 01 - 59
S
Ordinal suffix of day of month: st, nd, rd or th
t
Number of days in the month: 28 - 31
U
Unix timestamp: integer
w
Day of the week: 0 - 6
y
Year: 00 - 99
Y
Year: 0000 - 9999
%
the next character, i.e. %d is d

Setting elements directly

For convenience, the following functions perform the formatting as above and then use document.setElementById() to set the element with CSS ID "id":

Ijax.set_elem(id, text)
Ijax.set_price_elem(id, price)
Ijax.set_change_elem(id, price_change)
Ijax.set_volume_elem(id, volume)
Ijax.set_turnover_elem(id, turnover)
Ijax.set_value_elem(id, value)
Ijax.set_index_price_elem(id, price)
Ijax.set_index_change_elem(id, index_change)
Ijax.set_pct_change_elem(id, pct_change)
Ijax.set_date_elem(id, date)
Ijax.set_time_elem(id, time)
Ijax.set_datetime_elem(id, time)

Internal Formats

Prices are transmitted as dollars to 4 decimal places.

Dates and times are transmitted as strings in the following formats:

Date
YYYY-MM-DD
Time
HH:MI:SS
Datetime
YYYY-MM-DD HH:MI:SS

Note that times are in the local timezone of the relevant exchange.

Use Ijax.parse_date to convert an Ijax time to a javascript Date object.

Viewing announcements

If you are permissioned to view company announcements, there are several ways that this may be configured for you.

The simplest method involves you linking to a framed page on the Iguana news website.

You can obtain a url to use, given an issuer and a news item, by calling:

Ijax.iguana_news_url(issuer, item)

If you choose a different method to include announcements on you website, then we can provide sample code to help you.