HTML5 Documentation

Version

HTML5 - v1.4.x

Current Version

Released November 2017

v1.4.4 is the current stable release. You can get the JS here:

https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.4.4/js/chartworks.min.js

See the Change Log for previous versions.

What's New

The v1.4.4 release is small with a few items for customization and performance. Enjoy!

  • Ability to set the height of the lower indicator panel by percent of the overall chart area through panel.lower.size.percent.
  • Chart performance has been improved by dropping the number of API requests needed to generate the chart.

Also see the Change Log for more information on previous versions.

Quick Start

Authentication

Before jumping into the Quick Start guide make sure you understand Authentication. In the below examples we will be using demo-token as our demo authentication token. This token is a required input into the Chart Config. Details on how to generate a real authentication token can be found in the Authentication section. Our demo-token is only entitled for delayed data for the following securities:

  • Apple Inc (symbol: AAPL) trading on the NASDAQ
  • IHS Markit (symbol: INFO) trading on the NASDAQ

Requests to chart any other securities will fail.

Minimum Example

The HTML5 charts were built for easy integration. In the simplest form all it takes is the below HTML and Javascript to get a chart up and running on your page:

<!DOCTYPE html>
<html>
<head>
    <style>
        .chart {
            height: 440px;
        }
    </style>
</head>
<body>
    <!-- Target where HTML5 chart will load -->
    <div class="chart" id="chartTarget"></div>

    <!-- Chartworks JS -->
    <script src="https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.4.4/js/chartworks.min.js"></script>

    <!-- Chartworks Config -->
    <script>
        new ChartworksBuilder({
            "token": "demo-token",
            "target": "#chartTarget",
            "symbol": "AAPL",
            "exchange": "NSQ"
        });

    </script>

    <noscript>Please enable Javascript</noscript>

</body>
</html>


The result:



Full Example

This example uses most of the config parameters along with some of the Events and Methods. It represents what the setup might look like in a real-world implementation.

<!DOCTYPE html>
<html>
<head>
    <style>
        /* make chart fluid */
        html, body {
            height: 100%;
            margin: 0;
            overflow: hidden;
            background-color: #000;
        }
        .chart {
            height: 100%;
        }
        a {
            color: #337ab7;
            text-decoration: none;
        }
    </style>
</head>
<body>
    <!-- Target where HTML5 chart will load -->
    <div class="chart" id="chartTarget"></div>

    <!-- Chartworks JS -->
    <script src="https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.4.4/js/chartworks.min.js"></script>

    <!-- Chartworks Config -->
    <script>
        new ChartworksBuilder({
            "token": "demo-token",
            "target": "#chartTarget",
            "symbol": "AAPL",
            "exchange": "NSQ",
            "timeframe": "1y",
            "realTime": false,
            "typeAheadAPI": "https://api.markitondemand.com/apiman-gateway/MOD/chartworks-xref/1.0/xref/predictive?search=%s",
            "compareMenuOptions": [{
                "symbol": "INFO",
                "exchange": "NSQ",
                "displayName": "IHS Markit Ltd."
            }],
            "cultureCode": "en-US",
            "style.indicator.price.lineColor": "orange",
            "style.indicator.price.fillColor": "rgba(95, 179, 241, 0.1)",
            "style.indicator.price.lineWidth": "3",
            "panel.lower.indicator": "Volume",
            "feature.symbolSearch": true,
            "feature.comparison": true,
            "feature.timeframe": true,
            "feature.indicators": true,
            "feature.intraday": true,
            "feature.events": true,
            "feature.markerType": true,
            "feature.saveLoad": true,
            "feature.tools": true,
            "theme": "dark",
            "onShare": function(args) {
                var sharePenURL = "http://codepen.io/chartworks/pen/ZpgQEb?chartID=" + args.chartID;

                // show dialog with link to our chart
                this.showDialog("<a href=" + sharePenURL + " target=\"_blank\">View Your Shared Chart in CodePen</a>");
            },
            "onPrimarySymbolChange": function(args) {
                console.log(args.symbol, args.exchangeId);

                // display a nice message when trying to get unentitled data
                if (args.symbol != "AAPL" && args.symbol != "INFO") {
                    this.showDialog("Alert", "This demo is only entitled to symbols AAPL and INFO on the NASDAQ. All other symbols will fail.");
                }
            },
            "onAPIError": function(apiError) {
                // handle 401 (unauthorized)
                if (apiError.status === 401) {

                    // show dialog that we are getting a new token
                    this.showDialog("Token expired", "Loading new token...");

                    // use getInvalidTokenCount to ensure we don't get stuck in an
                    // endless loop if we keep creating bad tokens
                    if (this.getInvalidTokenCount() < 5) {
                        var objChart = this;
                        getNewToken(function(newToken) {
                            // set token
                            objChart.setConfigParam('token', newToken);

                            // load data
                            objChart.loadData();
                        });
                    } else { // fail after 5 unsuccessful tries
                        this.showDialog("Warning", "Max number of auth attempts reached. Your token generation is no good!");
                    }
                } else { // print other errors in the console
                    console.log(apiError.status, apiError.statusMsg);
                }
            }
        });

        // Your code should generate a new token.
        // This is just an example
        function getNewToken(onComplete) {
            // timeout to simulate a slow request
            setTimeout(function() {
                var token = "demo-token";
                onComplete(token);
            }, 1000);
        }
    </script>

    <noscript>Please enable Javascript</noscript>

</body>
</html>


The result:

Chart Breakpoints

The HTML5 chart was built with responsive displays in mind. It has a single break-point at a width of 780px. Charts that are less than 780px wide when rendered will only show a time-frame navigation in the top menu. Charts that are 780px or wider will display the drawing tools as well as the full set of options in the top menu. If you render a chart that is 780px or wider you can suppress menu items from appearing in the config if you wish. However, if you wish to override the breakpoint you can do so with template.size. The template.size gives you the ability to show the 'large' chart in areas less than 779px wide and vice versa show 'small' chart in areas greater than 779px.

Small Template: 779px wide or less

The small chart only shows the timeframe selector by default. You can optionally show a comparison menu and rollover information via feature.small.comparison and feature.small.dataLegend. Customize your timeframes as well via feature.small.timeframes.

type_ahead

Large Template: 780px wide or more

type_ahead

Chart Height and Width

There are a few different ways to setup the height and width of the HTML5 charts. Implementation situations vary so we tried to make the charts flexible. Height and width can be set in two locations:

  • In the CSS
  • In the chart config via the panel.lower.size.height and panel.upper.size.height params

Your implementation will dictate which you use. We'll walk through the main use cases below.

Fluid Setup

This setup allows the chart to use the entire height and width of the target element. All of the height/width logic is handled in the CSS and the panel.lower.size.height and panel.upper.size.height parameters are not included in the chart config. When additional lower indicators are added to the chart all other panels get slightly smaller to fit the new panel. This setup works especially well when you give the chart an entire page.

Fixed Overall Height

If you are looking for your overall chart to stay the same height regardless of the number of lower indicators added you can set the height in the CSS and the panel.lower.size.height and panel.upper.size.height parameters are not included in the chart config. When additional lower indicators are added to the chart all other panels get slightly smaller to fit the new panel. Note that this height includes the menus as well.

Fixed Panel Height

In this case we are defining the height of the top panel as well as the height of each lower indicator panel using the panel.lower.size.height and panel.upper.size.height parameters in the chart config. CSS is not used. When additional lower indicators are added to the chart the overall chart hight will 'grow' by the panel.lower.size.height thus the chart will continue to get taller with each new lower indicator added.

Width

Width is straight-forward, always handled in CSS.

Type Ahead Searches

End users expect their symbol searches to include type ahead functionality so we've built this into our HTML5 charts. If you are using a Commonly Known Symbol Set or a Custom Symbol Set then we will supply the API URL that you will put in the Chart Config typeAheadAPI input; basically we handle everything for you in this case.

type_ahead

If you are instead using Exchange Symbol + Exchange Code for your symbol set you'll need to setup a simple API that powers the type ahead searches in the UI.

Type Ahead API URL Format

The API is fairly simple, in the Chart Config the typeAheadAPI input takes an API URL (we recommend using HTTPS). In the URL insert %s for where the search term should be added. For example your URL might look like this:

https://yourTypeAheadApi.com?searchTerm=%s

In this case the %s will be replaced with whatever the user types into the search field. For example if the user types in aap the following URL will get called:

https://yourTypeAheadApi.com?searchTerm=aap

You can alternatively add the search parameter in the path:

https://yourTypeAheadApi.com/searchTerm/%s

Using our same example from above the resulting API call would be:

https://yourTypeAheadApi.com/searchTerm/aap

Type Ahead API Response Format

Your type ahead API should return a JSON array of results. The UI will display the results in the order they come back in the JSON array. The HTML5 UI does no additional filtering or searching on the results when they are handed back. The HTML5 UI will simply highlight the search term in the results. You can see this in the screenshot above where the user is searching for "go" and you can see each instance of "go" highlighted in the results.

The response array should be under the data.items object (see example) and should consist of the following fields:

symbol

string: required

The symbol of the security. See Symbology for more details.

exchange

string: optional/required

The exchange code for the symbol. This input is required if you are utilizing the Exchange Symbol + Exchange Code as your symbol set; otherwise it is optional. See Symbology for more details.

displayName

string: required

The name you would like displayed in the type ahead menu for this security.

displaySymbol

string: optional

By default the chart displays the symbol in the type ahead menu. If a value is passed for 'displaySymbol' this value will be displayed in the type ahead menu instead of symbol. In some cases a client may wish to override the symbol and instead display an alternative symbol in the menu. For example, if the client is using the RIC symbol set and therefor must pass in 'MSFT.O' in the symbol field to chart MSFT on the NASDAQ but would rather just display 'MSFT' in the menu they can pass "displaySymbol": "MSFT" in the JSON to achieve this.

displayExchange

string: optional

By default, starting with v1.3, no exchange is appended to the symbol in the type ahead menu. If you wish to also display an exchange code you can include 'displayExchange' in your JSON response for it to be displayed in the menu.

Example API Response 1

{"data":
    {"items":
        [{
            "symbol": "AAP",
            "exchange": "NYSE",
            "displayName": "Advance Auto Parts Inc"
        },{
            "symbol": "AAPL",
            "exchange": "NSQ",
            "displayName": "Apple Inc"
        }]
    }
}

Example API Response 2

{"data":
    {"items":
        [{
            "symbol": "AAP.N",
            "displayName": "Advance Auto Parts Inc",
            "displaySymbol": "AAP",
            "displayExchange": "NYSE"
        },{
            "symbol": "AAPL.O",
            "displayName": "Apple Inc",
            "displaySymbol": "AAPL",
            "displayExchange": "NASDAQ"
        }]
    }
}

End to End Example

The below is an example API response for a user that typed in goo into the search.

API Call:

https://yourTypeAheadApi.com?searchTerm=goo

API Response

{"data":
    {"items":
        [{
            "symbol": "GOOGL",
            "exchange": "NSQ",
            "displayName": "Alphabet Inc"
        },{
            "symbol": "GT",
            "exchange": "NSQ",
            "displayName": "Goodyear Tire & Rubber Co"
        },{
            "symbol": "DKS",
            "exchange": "NYSE",
            "displayName": "Dick's Sporting Goods Inc"
        }]
    }
}

UI Result

type_ahead_goo

User Click/Select Option

type_ahead_goo_click

Upon click/select the chart pulls the symbol and exchange parameters (in this case "GOOGL" and "NSQ") and use these to either render a new chart or to add a comparison depending on the search context.

Compare Menu

The compare menu is composed of two sections: the symbol search and a predefined list of securities to check. The symbol search is powered by the Type Ahead API and the predefined list of securities is based on the 'compareMenuOptions' parameter in the Chart Config which takes a JSON array to populate the list. Also see compareSymbols.

compare_menu

JSON Inputs for compareMenuOptions

In the Chart Config the compareMenuOptions accepts a JSON array composed of the following parameters:

symbol

string: required

The symbol that is to be charted as a comparison. See Symbology for more details.

exchange

string: optional/required

The exchange code for the symbol that is to be charted as a comparison. This input is required if you are utilizing the Exchange Symbol + Exchange Code as your symbol set; otherwise it is optional. See Symbology for more details.

displayName

string: required

The name you would like displayed in the Compare menu for this item.

Example

The below is an example JSON array for the compareMenuOptions parameter in the Chart Config.

"compareMenuOptions": [{
    "symbol": "SPY",
    "exchange": "NYSE",
    "displayName": "SPDR S&P 500 ETF Trust"
}, {
    "symbol": "QQQ",
    "exchange": "NSQ",
    "displayName": "PowerShares QQQ Trust"
}]

If no JSON array is passed into the config then no default options will be displayed in the Compare menu.

Extended Hours

Extended hours on intraday charts is available for US exchanges (additional data entitlements may be required). Extended hours are shaded on the chart for both pre and post market hours.

extendedHours

There are a number of ways to enable extended hours on your chart. To enable extended hours by default you can use the extendedHours config param. Optionally, on large charts, you can enable the settings menu via feature.settings to be displayed in the top right which gives the user access to toggle on/off extended hours:

settings_menu_extended_hours

You can always use the setConfigParam method to toggle extended hours on/off in your own code as well.

chartworks.setConfigParam("extendedHours", true);

Currency Cross Rates

Currency cross rates represent a unique challenge as not all published symbol sets have symbols for all of the various currency cross rates. Often the major cross rates have symbols but the more obscure pairings generally do not. To solve this issue the chart config now accepts an optional crossRate parameter. Please note that additional data entitlements may be required to display currency cross rates.

The crossRate parameter acts just like the symbol input except it takes the two currency codes separated by a pipe '|' that you wish to chart the cross rate of on the chart. For example if you wished to chart the US Dollar vs Great British Pound as simple config would look like this:

new ChartworksBuilder({
    "token": "your-token",
    "target": "#chartTarget",
    "crossRate": "GBP|USD"
});

The resulting chart would be:

cust_events

The crossRate parameter can also be passed into the compareMenuOptions and compareSymbols config inputs. The below example would load with GBP vs USD compared to EUR vs USD and then have more currency comparison options listed in the 'Comparison' menu for the user to easily add to the chart.

new ChartworksBuilder({
    "token": "your-token",
    "target": "#chartTarget",
    "crossRate": "GBP|USD",
    "displaySymbol": "GBP vs USD",
    "compareSymbols":[{
        "displaySymbol": "EUR vs USD",
        "crossRate": "EUR|USD"
    }],
    "compareMenuOptions": [{
        "displayName": "US Dollar (USD) / Australian Dollar (AUD)",
        "displaySymbol": "USD vs AUD",
        "crossRate": "USD|AUD"
    },{
        "displayName": "US Dollar (USD) / Euro (EUR)",
        "displaySymbol": "USD vs EUR",
        "crossRate": "USD|EUR"
    },{
        "displayName": "US Dollar (USD) / Swiss Franc (CHF)",
        "displaySymbol": "USD vs CHF",
        "crossRate": "USD|CHF"
    }],
    "typeAheadAPI": "your-type-ahead-api"
});

Chart Config

The chart config supplies all of the inputs to render the chart. Check out the full example to see what this looks like. In the example you'll see all the config parameters listed below pass into ChartworksBuilder:

window.chartworks = new ChartworksBuilder({
    "token": "demo-token",
    "target": "#chartTarget",
    ...
    ..
    .
});

chartID

string: optional

Description: The unique ID generated during an onShare event can be passed into the chart config to load that shared chart. Also see feature.share.

Default: NULL

Example

"chartID": "1d355737"

compareMenuOptions

JSON array: optional

Description: JSON array for the compare menu. See the Compare Menu section for more details. Also see compareSymbols.

Default: NULL

Example

"compareMenuOptions": [{
    "symbol": ".SPX",
    "exchange": "NYS",
    "displayName": "S&P 500 Index"
}, {
    "symbol": "COMP",
    "exchange": "NSQ",
    "displayName": "NASDAQ Index"
}, {
    "symbol": "UKX",
    "exchange": "FSI",
    "displayName": "FTSE 100 Index"
}]

compareSymbols

JSON array: optional

Description: When passed a JSON array the symbols in the JSON array are loaded as comparisons when the chart renders. If you are looking to load a chart with a comparison already showing the compareSymbols input allows you to do so without the user having to manually add the comparisons. Also see compareMenuOptions.

Default: NULL

JSON Inputs for compareSymbols

In the Chart Config the compareSymbols accepts a JSON array composed of the following parameters:

symbol

string: required

The symbol that is to be charted as a comparison. See Symbology for more details.

exchange

string: optional/required

The exchange code for the symbol that is to be charted as a comparison. This input is required if you are utilizing the Exchange Symbol + Exchange Code as your symbol set; otherwise it is optional. See Symbology for more details.

displaySymbol

string: optional

The symbol you would like displayed on the chart.

displayExchange

string: optional

The exchange name you would like displayed on the chart.

Example

The below is an example JSON array for the compareSymbols parameter in the Chart Config.

"compareSymbols": [{
    "symbol": "SPY",
    "exchange": "NYSE",
    "displaySymbol": "SPY",
    "displayExchange": "NY"
}, {
    "symbol": "QQQ",
    "exchange": "NSQ",
    "displaySymbol": "QQQ.O"
}]

crossRate

string: optional

Description: The two currency codes separated by a pipe '|' that you wish to chart the cross rate of on the chart. See Currency Cross Rates for more details.

Default: NULL

Example

"crossRate": "USD|GBP"

cultureCode

string: optional

Description: Localized language and number/date formats.

Accepted Inputs:

  • "en-US" for English (United States) [default]
  • "en-AU" for English (Australia)
  • "en-GB" for English (United Kingdom)
  • "fr-CA" for French (Canada)
  • "ja-JP" for Japanese (Japan)
  • "it-IT" for Italian (Italy)

Default: "en-US"

Example

"cultureCode": "ja-JP"

customEvents

JSON array: optional

Description: JSON array for custom chart events. See loadCustomEvents for details on the JSON parameters. Also see loadCustomEvents and clearCustomEvents in the Methods section for additional ways to interact with custom events.

Default: NULL

Example

"customEvents": [{
    "label": "My Custom Events",
    "display": true,
    "dataset": [{
        "date": "2016-07-19",
        "iconImage": "img/sm_ghost.png",
        "rolloverTitle": "My Custom Event #1",
        "rolloverBodyText": "Text for custom event #1."
    }, {
        "date": "2016-04-18T10:18:00",
        "iconCharacter": "X",
        "iconCharacterColor": "#cce6ff",
        "iconBackgroundColor": "#2BA92B",
        "rolloverTitle": "My Custom Event #2",
        "rolloverBodyHTML": "Visit <a href=\"https://www.chartworks.io\" target=\"_blank\" style=\"color:red!important\">chartworks.io</a>"
    }]
}]

custom_events_ghost cust_events

displayExchange

string: optional

Description: By default, starting with v1.3, no exchange is appended to the symbol in the UI. If you wish to also display an exchange code you can supply a string into displayExchange for it to be displayed in the UI.

Default: NULL

Example

"displayExchange": "NASDAQ"

displaySymbol

string: optional

Description: By default the chart displays the symbol in the UI. If a value is passed for displaySymbol this value will be displayed in the UI instead of symbol. In some cases a client may wish to override the symbol and instead display an alternative symbol in the UI. For example, if the client is using the RIC symbol set and therefor must pass in 'MSFT.O' in the symbol field to chart MSFT on the NASDAQ but would rather just display 'MSFT' in the UI they can pass in "displaySymbol": "MSFT" to achieve this.

Default: NULL

Example

"displaySymbol": "MSFT"

exchange

string: required/optional

Description: The financial exchange code for the passed symbol. Required only if you are using the Exchange Symbol and Exchange Code as your symbol set. See Symbology.

See the full list of available exchange codes on the symbology page.

Example

"exchange": "NSQ"

extendedHours

boolean: optional

Description: Show (true) or hide (false) extended market hours on intraday charts. Only available on US exchanges. May require additional data entitlements.

Default: false

Example

"extendedHours": true

feature.attribution

boolean: optional

Description: Show (true) or hide (false) chartworks attribution under the chart with link that opens https://www.chartworks.io in a new tab.

Default: false

Example

"feature.attribution": true

feature.attribution.position

string: optional

Description: Provides options for where the attribution is displayed. By default the attribution is displayed in the bottom left under the chart. panelBottomLeft displays the attribution within the main chart panel.

Accepted Inputs:

  • "panelBottomLeft" for attribution to be displayed in the bottom left of the main chart panel.

Default: NULL

Example

"feature.attribution.position": "panelBottomLeft"

feature.attribution.value

string: optional

Description: Provides ability to change the attribution string value.

Default: "chart by Chartworks"

Example

"feature.attribution.value": "My Company"

feature.comparison

boolean: optional

Description: Show (true) or hide (false) the comparison selector in the top menu. If the chart width is less than 780px the comparison selector will always be hidden.

Default: true

Example

"feature.comparison": false

feature.dataLegendOHLC

boolean: optional

Description: Show (true) or hide (false) the Open, High, Low rollover data points for chart styles that do not use Open, High, Low data points to draw (e.g. Line, Area, Dot and Bar styles) on small and large charts. See feature.small.dataLegendOHLC to set dataLegendOHLC for small charts only.

Default: false

Example

"feature.dataLegendOHLC": true

feature.events

boolean: optional

Description: Show (true) or hide (false) the events selector in the top menu. If the chart width is less than 780px the events selector will always be hidden.

Default: true

Example

"feature.events": false

feature.indicators

boolean: optional

Description: Show (true) or hide (false) the indicators selector in the top menu. If the chart width is less than 780px the indicators selector will always be hidden.

Default: true

Example

"feature.indicators": false

feature.indicators.editColors

boolean: optional

Description: Show (true) or hide (false) the color palettes in the indicator/symbol menus.

Default: true

Example

"feature.indicators.editColors": false

feature.intraday

boolean: optional

Description: Show (true) or hide (false) intraday timeframe options in the menu ('1 Day' and '5 Day') . Good to toggle to false if the security you are charting will never have intraday data (for example a Mutual Fund).

Default: true

Example

"feature.intraday": false

feature.markerType

boolean: optional

Description: Show (true) or hide (false) the marker selector in the top menu. If the chart width is less than 780px the marker selector will always be hidden.

Default: true

Example

"feature.markerType": false

feature.legend.addOverlay

boolean: optional

Description: Enable (true) or disable (false) users from being able to add indicators to lower indicators.

Default: true

Example

"feature.legend.addOverlay": false

feature.legend.autoExpand

string: optional

Description: When set to "comparison" the legend will show as expanded on chart load. By default it's collapsed on load.

Default: NULL

Example

"feature.legend.autoExpand": "comparison"

feature.panZoom

boolean: optional

Description: Enable (true) or disable (false) users from being able to pan/zoom the chart.

Default: true

Example

"feature.panZoom": false

feature.events.dividends.iconImage

string: optional

Description: A base64 image or path to a local image that replaces the default dividend event icon. Base64 is recommended.

Default: null

Example

"feature.events.dividends.iconImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABcAAAAXCAYAAADgKtSgAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAAAZiS0dEAP8A/wD/oL2nkwAAAAlwSFlzAAAASAAAAEgARslrPgAABjpJREFUSMe1lUtoXOcZhp//XGbOzJkZjUajGd0ztmRZ40i25cZObNchqVvShEJom02TQqCFdtNFvOmykFW6KDTQrlraQilJN3ahCYbSxE0cx46d2E4sW7Fl62JJc5NGmvto5pz//KeLJPYq0E0/eOGDDx544Xt54f844usO+qOv4+9sBfT4+C4tGJkRhrlXaGaPr9yaL907qtuck9XFZRHqc9StV/43uLHvt3itTd0amj0WjCV/1tfX+9TwQHQg3Rs0rKBGp6soVboyV2wUt7Yq/+nWt/7YyV+9pNspKedPfT08duwNvJ1qzOqfeCU1NPSL4wfT/U/ORMikTMKWQBfg+dDu+KxsuJyfa/Lhp6XNjXz+953yvdcNK16vXXzxofuvlvSJPyGcaqx3ePLX2anMqZefHY0+c8gm1aOjCfCUQno+nvLRNUjGNGYyQcYGI3alrZ9wpEjI2uoHsfEXuq3Vfz6EP3LsVfKfndHHD337l3snR0+98PSgsXfYQCkPR3q4UiKl90CulLjSQymPVEww3B/Uqi1v1vNcZ/niHy6MPfZTv7b2Hnooc5J9jx4nPbL7ROaRod88+Y3B6MRQACkdup0WyvPwlYcn3QdSnkS6XbrdFkopesI+dhCt1WxOR+P9HyWT/fc3mi30Jx5/hpW5f5kz+w++Or03fTSbsek0N7k3f4nC/c8oF1cIhS2CpsD3OgjfoVErsTB3gdLqHNuba1hWgGTMwJdtW+5UjLkP/vp2djKr9KOHn2Ag1T85uTv1q+x4TyygNVlfnmPfnlEOzU5jW4Lc/bske8Po7CBUi/Xlm2T3jHDo4DThgM/K4i3iUZOY5eK1t/uCung7bhtlY3zAoNXq7h/v7w4M2NvkNuo8dugAs7OzBINBMpldNOpnob1EIGDSdVxSfRGOHj2GbdtMTOwhEo2yuHCD4VSMTn93oJXw9tu2dVt7/vgIQ5FWdjTeMHqMEmHLYGoqSygU+uJXhYYd0ugNlOkxSvQGytghDSE0AEKhEFNTWcKWQY9RYjTeMAYjrezz3xzBOPK9FPPXGpF+a4towMG2oiAEjuOglCKfzxPRcgxGt75IhQ+dCuTzecbGRtE0DYTAtiAeKKNZDdJWI3LkuRT6i+MuxWJ5KjMonu1PuHSUw3YnCZgUiuuUc+8w0XuTjZVllm8uYhp1RgabrG402HFjuBLW1hax3UsMh4s41TKlteLfrdLyFeOTa3dptuV5t+bnq8Iciop7tPQiheYAYaPMgXSeu9eLXHhzEbMrWQgH+NbLExyYynO/coPCZhLTLWLXF6nVFLIq881K+fwn1ysY73yaZ3GLeVtvvrXLlj/vswV6YoU9xxNEYxrS91m7VWA04mMnTeo7ktXPc2RnJNOJAs2ax9K1Cmp7h1zLZ6llvPXGpfb8eB9oH680eGlauTfuVd+PJHR3YjZCKuCxfHUTV3VBdwgGFJGETrBHI5owME0PdAepOixfK5MyJRMHI0QSujt3r/r+S9PK/XilgTa5H66UJEtV72LZY9FPBEhP21jSp5DrIAIC3dYwe/QH0kMawoRCroslfdLTEUgEKHssLVW9i1dKksn9oJ05C7m6x+nrMl9vq1uuB1pvgHTGYnvdQekCK2Eiwjpm1ECENEIJEyUE2+sO6YyFlgjgelBvq5unr8v8et3jzFnQAGpNH9//m+t01KbcAYROOB7AbyncusfkwQh+wqCtgZ4OMDFj0615+G1FOG4CGrID3Y7a9P033XrTB76EJ22BED/G1IShpIbf0dA1Hd/1VeX2jpu2NA6f7GXfyV4OPx2nTxdU7uy4vuMrXTPwOzrK1TA1YQjxI5K2eAgPmpCJEsJnTAgd5Rp4rkajpQrn3q29tnS5cdVf7bjxtod3v+MuXa5fPXeu9lqjpQqe1FDSQGg6wmcsEyUUNL9sNYBK22e9gZzPd5cSt+tyoC4Np+1wd93J/fnf1d9dv9P9y/F91sm+mD61VfdufzjfefejlZ3mT74T/27vQms4GHIp5ttyPt9dyjWQ423/Yc0FgeeOmKyW1Uh2NPCDVMLY7Xu+vlpy3jt92fnH5KBQCwX/K6dqclCwUPC1Hz4e+P5YOvCUZghV2nIXP19zz4wltfWzV1y6wH8BhgoFdoEHRuQAAAAldEVYdGRhdGU6Y3JlYXRlADIwMTUtMTEtMjBUMTU6NTA6NTgrMDg6MDAYhRUdAAAAJXRFWHRkYXRlOm1vZGlmeQAyMDE1LTExLTE4VDEwOjMxOjM0KzA4OjAwUsYY9wAAAEd0RVh0c29mdHdhcmUASW1hZ2VNYWdpY2sgNi43LjctMTAgMjAxNC0wMy0wNiBRMTYgaHR0cDovL3d3dy5pbWFnZW1hZ2ljay5vcmdvn6KiAAAAGHRFWHRUaHVtYjo6RG9jdW1lbnQ6OlBhZ2VzADGn/7svAAAAGHRFWHRUaHVtYjo6SW1hZ2U6OmhlaWdodAAxMjAC+spiAAAAF3RFWHRUaHVtYjo6SW1hZ2U6OldpZHRoADEyMN5Wme8AAAAZdEVYdFRodW1iOjpNaW1ldHlwZQBpbWFnZS9wbmc/slZOAAAAF3RFWHRUaHVtYjo6TVRpbWUAMTQ0NzgxMzg5NHYuTUoAAAATdEVYdFRodW1iOjpTaXplADE5LjhLQkJw1rOeAAAASnRFWHRUaHVtYjo6VVJJAGZpbGU6Ly8vdXNyL3NoYXJlL25naW54L3d3dy9jcmF3bGVyL0FwcC8uLi9pbWdfZnVsbC9lbW9qaTMzLnBuZ+taP0gAAAAASUVORK5CYII="

type_ahead

feature.events.splits.iconImage

string: optional

Description: A base64 image or path to a local image that replaces the default split event icon. Base64 is recommended.

Default: null

Example

"feature.events.splits.iconImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAFjklEQVRIib2WXWwcVxWAv3NnZnd2vfbu2ps4tdMkrjGhruuYGiUSpEgNUkCUICCVkJCqIHhpX0BCKBLqMyqKKAKpFXmtIqiQSCpCSn/UNFVwC02bxBjXUWNs58eJ7Nje9drrmZ2/e3lY27GhVRAPPdKZczXn3PPNvVfn3IFPQeReAVPHIDdTzFpp1Ws50p9KSS4MTS2JzEgS6LHatorXdfT/hFR+kkeyTr/VbP9Y5exvqFy6pLI5hZ2GOEB7Na1rwbyuxWeS5fg3xotGir+q/u+Q+aNtuVTR/rmzNfOUvePhlNp+ACn0QbqIiMIYDUEFsziKnn6L+MY/w+iOfzysxM+Uji3U7gmZP9pWcrelX0nt2rrX6j2CtD0CIghgABEw5u5kYwxm4RLJ2IuE1+5cqM8Ej5eOLcx/ImT6p225Qmf6bKqnY6/d+xSS2QIimNXIjcFm9SEAxmD8OeKx44Tjty8s3gq+sv2Xd1dkrQ1+fyhL34PZ59yu/Lft3YfBbUVMHaN90D4kDZXEx6yOWfPpOiiFyrUj4XinCqKW/ox+9eTVaDPk+cMtA007c8dTOz9nSb4HjM/8/Az/uDxCtbrA1rYUoj3Q3rodHb3CxNVxMq4mm04Qy0GxDEFl4D5Ln3luyJ9Zh/zoUTg4UHjW3ZkfVKUeEoHTL5/l1ZN/IdXUTHOxSEdbAomHJB4maUBuzgbcmLzO6ydPU66U6flMK0qBxHOWWQldr17703s3Vrf09SdbcvsfLUxleraUaOvl1J+voCXFwcf30uLUER1jVk9k87kYUDZLkcsbr1xAmZDvHHoQFsbwx+fmh/662PXVE0s1G6Cr3em3m1MlHBuSCnv27aC73UKicYhjMKuKWU0tgCBig9jkxeaJQ51MzCaQVMCxsZtTpa52px94VwG05FSfuDYoC6Iq3uwU1ycn0UkVYzzCOOCdi3MsexEGw7IX8c7FOcI4wBgPnVS5PjmJNzsFURWUhbg2LTnVB2ADuK7KNQpAIxqaCza/e/EjmjI2dtrCr0VkWl32DRYRNJmsYni0zN/O3yaTc4iDhBU/5ntHdiNJ0ihWkUbeNUjNT7xsEoEOMCLsaoXvP93N6EiF+nJEa0eewc8XsI3H2qQf/HA7Fy8vUr7t4zY79PUX6XATjE4g0ZBE1PzEW4dMV/RYKYxBB2AJiKGjydDx5Sw4AtqA8jZVcNbA/kEH9qYhNhDVkUQwIqA1OoiZrugxAAXw2of10WglLhudgK0RSyO2RkQjJkFs01DHwAYVh4afBFEalAZLY7QmWonLr31YH12HnHjfW6wuxG+aUIMCY4OxpGHtDdbaoGvvLcGoVbUayzShplqO3zzxvre4vl0TS+iRieCF0o70t1J5OyWOanhsMAreeLuKX014+JEm8nmLcjnm0ns17u92+eJgDhFpfG4MJtDElTAcmQhemFhCb2or58eDW4cfSnXn25w90mSDq5CUgAXbH3D54O1lhs8tc2lomX8N++RaHQ4eKqJEEEsatROBLkfcGFt56fDx8vNL4X9AlgJ0Utd/39dpf81tsbeKayG2ICLYltC7N4dbsCmWHB76UguPfb2AtdqeRQuEoMsx5Y9WRn9xqvrk2Ylo6b+6MMCdm3FtJdDn9rSpA5mM2iKWQlQjkYVwX6fDA5/NsG2bjaUF0SAhmBWNnotYuLIy9uuXq0+cPO9d23hHboJUgfGpaP7qTHimN0dn3pbdIqLudi1pdJZEIDTgaUwlJpoO4vHLy3985qXKkVPv+hO32CyfeMcXMrjPfrPlwGMD2ac770/tTxfsgmSsRh0lBuNrgsVo8dbNYOjcsP/bn51eemvRp/5xue75t+I6uPt3OR3f/UJmoLvd7stmVJPn65WJ2Xj0Dx/4w0PXotv16OOTf6ryb733qQA8X0wCAAAAAElFTkSuQmCC"

type_ahead

feature.saveLoad

boolean: optional

Description: Show (true) or hide (false) the save/load icon in the top menu and allow users to save/load both saved templates and saved charts.

  • Save/Load template: saves the users chart settings including indicators, timeframe and styles as a named template. It does not save the symbol or chart drawings/annotations.
  • Save/Load chart: saves the users chart and settings including symbol, drawings/annotations, indicators, timeframe and styles as a named chart.

If the chart width is less than 780px the save/load icon will always be hidden.

Default: false

Example

"feature.saveLoad": true

type_ahead

feature.saveLoadCharts

boolean: optional

Description: Show (true) or hide (false) the save/load icon in the top menu with only the 'Save chart' and 'Load chart' as an option.

  • Save/Load chart: saves the users chart and settings including symbol, drawings/annotations, indicators, timeframe and styles as a named chart.

If the chart width is less than 780px the save/load icon will always be hidden.

Default: false

Example

"feature.saveLoadCharts": true

type_ahead

feature.saveLoadTemplates

boolean: optional

Description: Show (true) or hide (false) the save/load icon in the top menu with only 'Save template' and 'Load template' as options.

  • Save/Load template: saves the users chart settings including indicators, timeframe and styles as a named template. It does not save the symbol or chart drawings/annotations.

If the chart width is less than 780px the save/load icon will always be hidden.

Default: false

Example

"feature.saveLoadTemplates": true

type_ahead

feature.settings

boolean: optional

Description: Show (true) or hide (false) settings menu on the large chart template. By default, when set to true all sub menu items will appear. To enable/disable specific setting menu items see feature.settings.extendedHours and feature.settings.print.

settings_menu_extended_hours

Default: false

Example

"feature.settings": true

feature.settings.downloadImage

boolean: optional

Description: Show (true) or hide (false) the 'Download Image' option in the settings menu.

Default: false, if feature.settings is set to true default becomes true

Example

"feature.settings.downloadImage": true

feature.settings.extendedHours

boolean: optional

Description: Show (true) or hide (false) the 'Extended Hours' option in the settings menu.

Default: false, if feature.settings is set to true default becomes true

Example

"feature.settings.extendedHours": true

feature.settings.print

boolean: optional

Description: Show (true) or hide (false) the 'Print' option in the settings menu.

Default: false, if feature.settings is set to true default becomes true

Example

"feature.settings.print": true

feature.share

boolean: optional

Description: Show (true) or hide (false) the share button in the top menu. Note that the onShare event must be defined for the share button to appear.

Default: false

Example

"feature.share":true

feature.symbolSearch

boolean: optional

Description: Show (true) or hide (false) the symbol search in the top menu. If the chart width is less than 780px the symbol search will always be hidden.

Default: true

Example

"feature.symbolSearch":false

feature.timeframe

boolean: optional

Description: Show (true) or hide (false) the timeframe and frequency selectors in the top menu. If the chart width is less than 780px the timeframe and frequency selectors will always be hidden.

Default: true

Example

"feature.timeframe": false

feature.tools

boolean: optional

Description: Show (true) or hide (false) the tools menu on the left side. If the chart width is less than 780px the tools menu will always be hidden.

Default: true

Example

"feature.tools": false

feature.small.comparison

boolean: optional

Description: Show (true) or hide (false) the comparison menu on the small chart. See Chart Breakpoints and template.size for more details on the small chart.

Default: false

Example

"feature.small.comparison":true

feature.small.dataLegend

boolean: optional

Description: Show (true) or hide (false) the rollover data legend on the small chart. See Chart Breakpoints and template.size for more details on the small chart.

Default: false

Example

"feature.small.dataLegend":true

feature.small.dataLegendOHLC

boolean: optional

Description: Show (true) or hide (false) the Open, High, Low rollover data points for chart styles that do not use Open, High, Low data points to draw (e.g. Line, Area, Dot and Bar styles) on small charts. Note, feature.small.dataLegend must be set to true for feature.small.dataLegendOHLC to display. See feature.dataLegendOHLC to set dataLegendOHLC for both small and large charts at once. See Chart Breakpoints and template.size for more details on the small chart.

Default: false

Example

"feature.small.dataLegendOHLC":true

type_ahead

feature.small.timeframes

JSON array: optional

Description: Show a custom set of timeframe options on the small chart.

Accepted Array Values:

  • "1d" for 1 Day
  • "5d" for 5 Days
  • "1m" for 1 Month
  • "3m" for 3 Months
  • "6m" for 6 Months
  • "ytd" for Year To Date
  • "1y" for 1 Year
  • "3y" for 3 Years
  • "5y" for 5 Years
  • "10y" for 10 Years
  • "15y" for 15 Years
  • "20y" for 20 Years

Default: ["1d","1m","3m","6m","ytd","1y","3y","5y","10y"]

Example

"feature.small.timeframes": ["1d","5d","1m","3m","6m","ytd"]

panel.lower.indicator

string: optional

Description: Lower indicator to load.

Accepted Inputs:

  • "adl" for Accumulation / Distribution
  • "avgTrueRange" for Average True Range
  • "awesomeOscillator" for Awesome Oscillator
  • "percentb" for Bollinger Band %B
  • "bollingerBandWidth" for Bollinger Band Width
  • "chaikins" for Chaikin's Volatility
  • "dividendYield" for Dividend Yield
  • "dmi" for Directional Moving Index (DMI)
  • "dmiAdx" for Directional Moving Index: ADX (DMI: ADX)
  • "dmiAdxr" for Directional Moving Index: ADXR (DMI: ADXR)
  • "macd" for Moving Average Convergence Divergence (MACD)
  • "macdHistogram" for Moving Average Convergence Divergence - Histogram (MACD)
  • "massIndex" for Mass Index
  • "momentum" for Momentum
  • "moneyFlow" for Money Flow
  • "moneyFlowIndex" for Money Flow Index
  • "onBalanceVolume" for On Balance Volume
  • "proc" for Price Rate of Change
  • "rsi" for Relative Strength Index (RSI)
  • "rollingDividend" for Rolling Dividend
  • "fastStochastics" for Fast Stochastics
  • "slowStochastics" for Slow Stochastics
  • "ultimateOscillator" for Ultimate Oscillator
  • "volume" for Volume
  • "vroc" for Volume Rate of Change (VROC)
  • "williamsPctR" for Williams %R

Default: NULL

Example

"panel.lower.indicator": "macd"

panel.lower.size.height

integer: optional

Description: Height in pixels of the lower chart panel.

Default: 100

Example

"panel.lower.size.height": 150

panel.lower.size.percent

integer: optional

Description: The height in percent of the lower chart panel.

Default: Disabled by default

Example

"panel.lower.size.percent": 20

panel.upper.size.height

integer: optional

Description: Height in pixels of the upper chart panel (does not include the menu height). Note that an additional ~40px will be added to this height for the x-axis labels.

Default: 300

Example

"panel.upper.size.height": 500

poll.rate

integer: optional

Description: Poll rate in seconds; minimum poll rate is 10 seconds. Polling defaults to off on load (0 seconds). When poll.rate is passed into the chart config the chart will start to poll for new data after the chart load has completed. For options to start or stop the poll after chart load has completed see startPoll and stopPoll. Our recomendation is to set the poll.rate at 60 seconds as that is the minimum frequency on any timeframe.

Default: 0

Example

"poll.rate": 60

realTime

boolean: optional

Description: If the user_tier (see Authentication section) is entitled to real-time exchange data the realTime parameter can be set to true to get back real-time charting data. If the realTime parameter is set to true but the user_tier is not entitled to real-time data the chart will default back to displaying delayed data. Setting the realTime parameter to false will return delayed charting data. Number of minutes intraday data is delayed varies by exchange.

Default: false

Example

"realTime": true

style.indicator.price.fillColor

string: optional

Description: Fill color of the Area price styles.

Default: "rgba(95, 179, 241, 0.13)"

Examples

"style.indicator.price.fillColor": "orange"

or

"style.indicator.price.fillColor": "#ffa500"

or

"style.indicator.price.fillColor": "rgba(255, 165, 0, 0.8)"

style.indicator.price.lineColor

string: optional

Description: Color of the price line. Applies to all price styles except OHLC, HLC and Candle Sticks.

Default: "#2496f1"

Examples

"style.indicator.price.lineColor": "orange"

or

"style.indicator.price.lineColor": "#ffa500"

or

"style.indicator.price.lineColor": "rgba(255, 165, 0, 0.8)"

style.indicator.price.lineColorDown

string: optional

Description: Color of the down price marker. Applies to OHLC, HLC and Candle Sticks price styles.

Default: "#fd0000" for non "cultureCode":"ja-JP" charts, "#2496f1" for "cultureCode":"ja-JP" charts.

Examples

"style.indicator.price.lineColorDown": "red"

or

"style.indicator.price.lineColorDown": "#ff0000"

or

"style.indicator.price.lineColorDown": "rgba(255, 0, 0, 0.5)"

style.indicator.price.lineColorNeutral

string: optional

Description: Color of the neutral price marker. Applies to OHLC, HLC and Candle Sticks price styles.

Default: "#999999"

Examples

"style.indicator.price.lineColorNeutral": "gray"

or

"style.indicator.price.lineColorNeutral": "#808080"

or

"style.indicator.price.lineColorNeutral": "rgba(128, 128, 128, 0.8)"

style.indicator.price.lineColorUp

string: optional

Description: Color of the up price marker. Applies to OHLC, HLC and Candle Sticks price styles.

Default: "#2496f1" for non "cultureCode":"ja-JP" charts, "#fd0000" for "cultureCode":"ja-JP" charts.

Examples

"style.indicator.price.lineColorUp": "green"

or

"style.indicator.price.lineColorUp": "#008000"

or

"style.indicator.price.lineColorUp": "rgba(0, 128, 0, 0.8)"

style.indicator.price.lineWidth

integer: optional

Description: Width of the price line. Appies to the Area and Line price styles.

Default: 2

Example

"style.indicator.price.lineWidth": 3

style.indicator.price.markerType

string: optional

Description: Marker style used for the price chart.

Accepted Inputs:

  • "area"
  • "bar"
  • "candlestick"
  • "dot"
  • "hlc"
  • "line"
  • "ohlc"

Default: "area"

Example

"style.indicator.price.markerType": "candlestick"

style.palette

array: optional

Description: An array of colors used for the chart color palettes across the chart (including comparisons, upper/lower indicators). If fewer than 14 colors are supplied default colors will be used until there are a total of 14 colors in the palette. Also see style.indicator.price.lineColor for how to customize the line color on chart load.

Default Light Theme: ["#2496F1","#F98254","#009487","#9D9D9D","#E220A8","#192F41","#FD0000","#DD4BF9","#76C147","#AD81C7","#04BBD3","#FCD32E","#4B7BBB","#00C02F"]

Default Dark Theme: ["#2496F1","#F98254","#009487","#9D9D9D","#E220A8","#FFFFFF","#FD0000","#DD4BF9","#76C147","#AD81C7","#04BBD3","#FCD32E","#4B7BBB","#00C02F"]

Example

"style.palette": ["#FF6037","#FF9966","#FF9933","#FFCC33","#FFFF66","#CCFF00","#66FF66","#AAF0D1","#50BFE6","#FF6EFF","#EE34D2","#FF00CC"]

cust_events

symbol

string: required

Description: The financial symbol for the chart to graph. See Symbology.

Example

"symbol": "AAPL"

target

string: required

Description: The HTML element where the chart will be loaded.

Example

"target": "#yourTarget"

template.size

string: optional

Description: Used to override the default template size used for the chart. By default, on chart load, Chartworks will measure the space allotted to it and determine if the small or large version of the chart should be shown (see Chart Breakpoints). However, if you wish to override this behavior you can instead pass in "template.size": "large" or "template.size": "small" to force the chart to display either the small or large template size.

Accepted Inputs

  • "small"
  • "large"

Default: Dynamically selected (see Chart Breakpoints)

Example

"template.size": "large"

theme

string: optional

Description: Color theme for the chart.

Accepted Inputs:

  • "light" for the light theme
  • "dark" for the dark theme

Default: "light"

Example

"theme": "dark"

timeframe

string: optional

Description: The timeframe of the chart.

Accepted Inputs

  • "1d" for 1 Day
  • "5d" for 5 Days
  • "1m" for 1 Month
  • "3m" for 3 Months
  • "6m" for 6 Months
  • "ytd" for Year To Date
  • "1y" for 1 Year
  • "3y" for 3 Years
  • "5y" for 5 Years
  • "10y" for 10 Years

Default: "1y"

Example

"timeframe": "1y"

token

string: required

Description: Authentication token. See Authentication for more details on how to obtain a token.

Example

"token": "9CwutfDn1xriBoLOtBQ5HcDPIjbq"

typeAheadAPI

string: optional

Description: Type ahead search API. Search parameter is in the URL as %s. See Type Ahead API for details on what the API should return.

Default: NULL

Examples

"typeAheadAPI": "https://yourTypeAheadApi.com?searchTerm=%s"

or

"typeAheadAPI": "https://yourTypeAheadApi.com/searchTerm/%s"

xid

string: optional

Description: In some cases clients may have access to Markit Digital's in-house symbol set named 'xid'. If you have access and wish to pass in 'xid' as your symbol set you can simply pass in xid in the config. If xid is passed in the symbol and exchange config params will be ignored. If using xid you should pass in displaySymbol (optionally can pass displayExchange as well).

Default: NULL

Example

"xid": "36276"

Events

onAPIError

Called any time the APIs encounter a non-200 API response (only applies to Markit APIs). Primary use is to signal when a passed token has expired or was not accepted. This will result in a status 401 and should be handled by the client by generating a new token and passing the new token into the config (see setConfigParam).

Example 401 Handling

Note that we initially pass in an invalid token ("BAD-TOKEN") into the chart config which will result in an 401 unauthorized error. We then generate a new token and reload the data.

new ChartworksBuilder({
    "token": "BAD-TOKEN",
    "target": "#chartTarget",
    "symbol": "AAPL",
    "exchange": "NSQ",
    "onAPIError": function(apiError) {
        // handle 401 (unauthorized)
        if (apiError.status === 401) {

            // show dialog that we are getting a new token
            this.showDialog("Token expired", "Loading new token...");

            // use getInvalidTokenCount to ensure we don't get stuck in an
            // endless loop if we keep creating bad tokens
            if (this.getInvalidTokenCount() < 5) {
                var objChart = this;
                getNewToken(function(newToken) {
                    // set token
                    objChart.setConfigParam('token', newToken);

                    // load data
                    objChart.loadData();
                });
            } else { // fail after 5 unsuccessful tries
                this.showDialog("Warning", "Max number of auth attempts reached. Your token generation is no good!");
            }
        } else { // print other errors in the console
            console.log(apiError.status, apiError.statusMsg);
        }
    }
});

// Your code should generate a new token.
// This is just an example.
function getNewToken(onComplete) {
    // timeout to simulate slow token generation
    setTimeout(function() {
        // create a good token
        var token = "demo-token";
        onComplete(token);
    }, 1000);
}

onChartLoad

Called each time chart data API completes.

Example

new ChartworksBuilder({
    "token": "demo-token",
    "target": "#chartTarget",
    "symbol": "AAPL",
    "exchange": "NSQ",
    "onChartLoad": function() {
        console.log("api done loading");
    }
});

onPrimarySymbolChange

Called any time the primary chart symbol is changed. Implemented as an input in the chart config. Returns the symbol and exchange.

Example

new ChartworksBuilder({
    "token": "demo-token",
    "target": "#chartTarget",
    "symbol": "AAPL",
    "exchange": "NSQ",
    "onPrimarySymbolChange": function(args) {
        console.log(args.symbol);
        console.log(args.exchangeId);
    }
});

onShare

Called any time the 'Share' button is clicked in the top menu (see feature.share). Within the onShare event you will get passed a unique chartID that is generated for the chart you are viewing. It is up to the developer implementing the charts to determine how to handle this chartID. In the code example below we have setup a simple page that when called with a chartID appended to the end will take that chartID and pass it into the chartID chart config parameter and load the chart.

https://www.chartworks.io/Public/charts/loadchart/{your_chartID_here}

We have also created two useful CodePen examples. Our Full Example includes a share option which generates a URL pointing to a second CodePen example that then loads the shared chart. These examples together show one possible end to end way to share a chart then load the shared chart.

Example

new ChartworksBuilder({
    "token": "demo-token",
    "target": "#chartTarget",
    "symbol": "INFO",
    "exchange": "NSQ",
    "feature.share": true,
    "onShare": function(args) {
        var shareURL = "https://www.chartworks.io/Public/charts/loadchart/" + args.chartID;
        this.showDialog("<a href=" + shareURL + " target=\"_blank\">View Your Shared Chart</a>");
    }
});

Methods

addIndicator

addIndicator(indicatorName);

When called adds the passed upper/lower indicator to the chart.

indicatorName

string: required

Description: The name of the upper/lower indicator to be added to the chart.

Accepted Inputs:

  • Upper Indicators

    • "bollinger" for Bollinger Bands
    • "ema" for Exponential Moving Average
    • "highlow" for High/Low Price
    • "linearregression" for Linear Regression
    • "mae" for Moving Average Envelope
    • "pricechannel" for Price Channel
    • "psar" for Parabolic Stop and Reversal
    • "sma" for Simple Moving Average
    • "tsf" for Time Series Forecast
    • "volumebyprice" for Volume by Price
    • "wma" for Weighted Moving Average
  • Lower Indicators

    • "adl" for Accumulation / Distribution
    • "avgTrueRange" for Average True Range
    • "awesomeOscillator" for Awesome Oscillator
    • "percentb" for Bollinger Band %B
    • "bollingerBandWidth" for Bollinger Band Width
    • "chaikins" for Chaikin's Volatility
    • "dividendYield" for Dividend Yield
    • "dmi" for Directional Moving Index (DMI)
    • "dmiAdx" for Directional Moving Index: ADX (DMI: ADX)
    • "dmiAdxr" for Directional Moving Index: ADXR (DMI: ADXR)
    • "macd" for Moving Average Convergence Divergence (MACD)
    • "macdHistogram" for Moving Average Convergence Divergence - Histogram (MACD)
    • "massIndex" for Mass Index
    • "momentum" for Momentum
    • "moneyFlow" for Money Flow
    • "moneyFlowIndex" for Money Flow Index
    • "onBalanceVolume" for On Balance Volume
    • "proc" for Price Rate of Change
    • "rsi" for Relative Strength Index (RSI)
    • "rollingDividend" for Rolling Dividend
    • "fastStochastics" for Fast Stochastics
    • "slowStochastics" for Slow Stochastics
    • "ultimateOscillator" for Ultimate Oscillator
    • "volume" for Volume
    • "vroc" for Volume Rate of Change (VROC)
    • "williamsPctR" for Williams %R

Default: NULL

Example

addIndicator("psar");

or

addIndicator("rsi");

clearCustomEvents

clearCustomEvents();

When called will remove all custom events (see customEvents and loadCustomEvents) from the chart. Anytime the primary symbol changes all custom events are also removed from the chart. See loadCustomEvents for a full custom events example.

downloadImage

downloadImage();

When called initiates the download of the chart image to client.

generateChartID

generateChartID(callback);

When called returns a unique chartID that is generated for the chart you are viewing (the ID generated mimics the onShare event). The ID can be passed into chartID to load the chart. One use case for generateChartID() is to copy a user's chart and then load it for them in an alternative view. For example, opening the existing chart in a pop-up window.

Example

generateChartID(function(args){
    console.log(args.chartID);
});

getCurrentExchange

getCurrentExchange();

When called returns the current exchange as a string (e.g. "NSQ").

getCurrentSymbol

getCurrentSymbol();

When called returns the current symbol as a string (e.g. "AAPL").

getCurrentTimeframe

getCurrentTimeframe();

When called returns the current timeframe as a string (e.g. "1y"). This method does not take into account panning or zooming. For example, if the user selects a "1 Year" timeframe and then zooms out, when getCurrentTimeframe(); is called it will return 1y.

getInvalidTokenCount

getInvalidTokenCount();

When called returns the current count of API calls that had 401 status response. Each 401 request increments the counter by 1, any API success 200 code resets the counter to 0. The primary usage is for handling generating a new token and avoiding an endless loop of submitting bad tokens. See onAPIError for a code example.

loadCustomEvents

loadCustomEvents(JSON_array);

Used to add custom events to the chart. loadCustomEvents accepts a JSON array for custom chart events. JSON details are below. Also see customEvents and clearCustomEvents for additional ways to interact with custom events.

cust_events

JSON Inputs for loadCustomEvents and compareMenuOptions

The below JSON inputs apply to both compareMenuOptions and loadCustomEvents:

label

string: optional

Description: The label for the custom events to be displayed in the Event menu.

Default: NULL

Example

"label": "Our Custom Events"

cust_events

display

boolean: optional

Description: If true then the custom events are shown, if false the custom events are not shown but the label will still appear in the Event menu for the user to select.

Default: true

Example

"display": false

dataset

JSON array: optional

Description: JSON array of all custom events. Details for all of the JSON parameters are below.

Default: NULL

Example

"dataset": [{
    "date": "2015-11-03",
    "iconCharacter": "X",
    "iconCharacterColor": "white",
    "iconBackgroundColor": "#2BA92B",
    "rolloverTitle": "INFO Event 1",
    "rolloverBodyText": "Some awesome event 1 text here"
} , {
    "date": "2015-12-03",
    "iconCharacter": "X",
    "iconCharacterColor": "white",
    "iconBackgroundColor": "#2BA92B",
    "rolloverTitle": "INFO Event 2",
    "rolloverBodyText": "Some awesome event 2 text here"
}]
JSON Inputs for dataset
date

string: required

Description: The date where the event will be displayed. The date string should be in a format recognized by Javascript's Date.parse() method (IETF-compliant RFC 2822 timestamps and also a version of ISO8601).

If the passed date is on a non-trading date (weekends/holidays) or during non-trading hours, the icon will appear on the nearest trading date. If the passed date is in the future, the icon will not be displayed.

If a time is included it will be parsed and applied as a local exchange time based the time zone of the primary symbol's exchange. For example if your primary symbol was BP trading on the LSE (London Stock Exchange) and your customEvent date was 2014-03-07T10:18:00 it would display on the chart @ 10:18am local London Stock Exchange time. If instead your primary symbol was AZN trading on the ASX (Australian Securities Exchange) and your customEvent date was 2014-03-07T10:18:00 it would display on the chart @ 10:18am local Sydney time.

Examples

"date": "March 7, 2014" // parsed as local exchange time
"date": "2014-03-07T10:18:00" // parsed as local exchange time
iconCharacter

string: optional

Description: The character contained within the icon. Icon only has space for a single character.

Default: NULL

Example

"iconCharacter": "X"
iconCharacterColor

string: optional

Description: The font color of the character contained within the icon.

Default: #FFFFFF

Example

"iconCharacterColor": "white"
iconBackgroundColor

string: optional

Description: The background color of the icon.

Default: #999999

Example

"iconBackgroundColor": "green"
rolloverTitle

string: optional

Description: The text of the rollover title.

Default: NULL

Example

"rolloverTitle": "Event Title"
rolloverBodyText

string: optional

Description: Text contained in the body of the rollover. If you wish to include HTML in the body see rolloverBodyHTML below. If both rolloverBodyText and rolloverBodyHTML are passed in the JSON with values then only rolloverBodyText will be displayed in the rollover.

Default: NULL

Example

"rolloverBodyText": "Just some text down here."
rolloverBodyHTML

string: optional

Description: HTML contained in the body of the rollover. If both rolloverBodyText and rolloverBodyHTML are passed in the JSON with values then only rolloverBodyText will be displayed in the rollover.

Default: NULL

Example

"rolloverBodyHTML": "Visit <a href=\"https://www.chartworks.io\" target=\"_blank\" style=\"color:yellow!important\">chartworks.io</a>"

Full loadCustomEvents Example

The below is an example is contained within the onPrimarySymbolChange event:

"onPrimarySymbolChange": function(args) {
    // create events JSON for INFO
    var info_events = [{
        "label": "Our Custom Events",
        "display": true,
        "dataset": [{
            "date": "2015-11-03",
            "iconCharacter": "X",
            "iconCharacterColor": "white",
            "iconBackgroundColor": "#2BA92B",
            "rolloverTitle": "INFO Event 1",
            "rolloverBodyText": "Some awesome event 1 text here"
        } , {
            "date": "2015-12-03",
            "iconCharacter": "X",
            "iconCharacterColor": "white",
            "iconBackgroundColor": "#2BA92B",
            "rolloverTitle": "INFO Event 2",
            "rolloverBodyText": "Some awesome event 2 text here"
        }]
    }];

    // add INFO events to chart if primary symbol is INFO
    if (args.symbol == 'INFO') {
        this.loadCustomEvents(info_events);
    }
}

See custom events for another example.

loadData

loadData();

When called will reload the data based on the current view. For example, if the chart config has a timeframe of 1y and the user changes the timeframe to be 5 years in the UI, if loadData(); is called it will make a new data call for the 5 years of data not changing the user's timeframe.

By default loadData(); will show the loading spinner once called. If you wish to suppress the loading icon from showing you can pass in {silent: true}, so the call would be loadData({silent: true});

Example

new ChartworksBuilder({
    "token": "demo-token",
    "target": "#chartTarget",
    "symbol": "AAPL",
    "exchange": "NSQ",
    "onAPIError": function(apiError) {
        console.log(apiError.status, apiError.statusMsg);

        // handle 401 (unauthorized) error by getting a new token
        if (apiError.status === 401) {
            // your code to generate a new token should go here
            var newToken = "my-new-token";

            // update the config token
            this.setConfigParam("token", newToken);

            // gracefully reload the chart data
            this.loadData();
        }
    }
});

print

print();

When called initiates the print of the chart.

reload

reload();

When called will reload the entire chart based on the chart config parameters. For example, if the chart config has a timeframe of 1y and the user changes the timeframe to be 5 years in the UI, if reload(); is called it will pull in the parameters from the config and completely reload the chart so that the timeframe shown will be 1 year instead of 5 years.

Example

new ChartworksBuilder({
    "token": "demo-token",
    "target": "#chartTarget",
    "symbol": "AAPL",
    "exchange": "NSQ",
    "typeAheadAPI": "https://api.markitondemand.com/apiman-gateway/MOD/chartworks-xref/1.0/xref/predictive?search=%s",
    "onPrimarySymbolChange": function() {
        // add a lower indicator
        this.setConfigParam("panel.lower.indicator", "MACD");

        // reload chart
        this.reload();
    }
});

resize

resize();

When called re-draws the chart based on the new dimensions.

setConfigParam

setConfigParam(configParamName, configParamValue);

Used to update chart config parameters. Used in conjunction with the reload and loadData methods.

Example

This example shows how to handle regenerating a new auth token.

new ChartworksBuilder({
    "token": "demo-token",
    "target": "#chartTarget",
    "symbol": "AAPL",
    "exchange": "NSQ",
    "onAPIError": function(apiError) {
        console.log(apiError.status, apiError.statusMsg);

        // handle 401 (unauthorized) error by getting a new token
        if (apiError.status === 401) {
            // your code to generate a new token should go here
            var newToken = "my-new-token";

            // update the config token
            this.setConfigParam("token", newToken);

            // gracefully reload the chart data
            this.loadData();
        }
    }
});

setCurrentSymbol

setCurrentSymbol(JSON_array);

Used to change the chart's primary symbol.

JSON Inputs for setCurrentSymbol

symbol

string: required

Description: The symbol of the security. See Symbology for more details.

Default: NULL

Example

"symbol": "AAPL"

exchange

string: optional/required

Description: The exchange code for the symbol. This input is required if you are utilizing the Exchange Symbol + Exchange Code as your symbol set; otherwise it is optional. See Symbology for more details.

Default: NULL

Example

"exchange": "NSQ"

setCurrentSymbol Example

setCurrentSymbol({
    "symbol": "AAPL",
    "exchange": "NSQ"
});

setFrequency

setFrequency(interval, period);

interval

int: required

Description: The interval of the frequency. For interday charts anything but 1 is ignored.

Accepted Inputs:

  • 1
  • 3
  • 5
  • 15

Default: NULL

period

string: required

Description: The period of the frequency.

Accepted Inputs:

  • "Minute"
  • "Day"
  • "Week"
  • "Month"

Default: NULL

Example

setFrequency(1, "Day");

setTimeframe

setTimeframe(timeframe);

timeframe

string: required

Description: The timeframe to show on the chart.

Accepted Inputs:

  • "1d" for 1 Day
  • "5d" for 5 Days
  • "1m" for 1 Month
  • "3m" for 3 Months
  • "6m" for 6 Months
  • "ytd" for Year To Date
  • "1y" for 1 Year
  • "3y" for 3 Years
  • "5y" for 5 Years
  • "10y" for 10 Years
  • "15y" for 15 Years
  • "20y" for 20 Years

Default: NULL

Example

setTimeframe("5y");

showDialog

showDialog(modalTitle, modalHtml);

Used to display a modal over the chart. Method accepts two inputs; one for the title and one for the body HTML, both strings.

Example

The below is an example is contained within the onPrimarySymbolChange event:

onPrimarySymbolChange: function() {
    this.showDialog("Alert", "The primary symbol has changed.");
}

cust_events

startPoll

startPoll(seconds);

When called will start polling for new charting data on the set number of seconds (int) passed into startPoll(). Default polling frequency is 60 seconds; minimum allowed polling frequency is 10 seconds. Also see poll.rate and stopPoll.

Example

startPoll(30);

stopPoll

stopPoll();

When called will stop polling for new charting data. Also see poll.rate and startPoll.

Example

stopPoll();

toggleEvent

toggleEvent(eventId, state);

eventId

string: required

Description: The eventID you want to show/hide on the chart

Accepted Inputs:

  • "dividends" for dividend events
  • "splits" for split events
  • "custom" for custom events (see customEvents)

Default: NULL

state

boolean: optional

Description: Can be used to force on (true) or off (false) an event from showing. If omitted, the event will be auto-toggled to its opposite state.

Default: auto-toggled to its opposite state

Example

toggleEvent("dividends");

Chartworks JS & Versioning

JavaScript

To render the HTML5 chart you need to include the Chartworks JS file. You can see this in the Minimum Example as:

<!-- Chartworks JS -->
<script src="https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.4.3/js/chartworks.min.js"></script>

The different Chartworks JS file versions are available on our CDN by modifying the version number in the URL. For version 1.1.0 you'd use:
https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.1.0/js/chartworks.min.js

For version 1.2.0 you'd use:
https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.2.0/js/chartworks.min.js

Versioning

The HTML5 charts will support Major, Minor and Patch releases following the Semantic Versioning methodology. Once a release has been made (say v1.1.0) Chartworks will not update that release with altered code (for example a bug fix). If a bug is found in v1.1.0, a Patch release will be created (v1.1.1) and deployed for clients to consume. The client side code will sit under a versioned URL path (i.e. /1.1.0/) with /js, /css etc directories under the version.

HTML5 Change Log

v1.4.4 (current stable)

Released November 2017

What's new in v1.4.4:

  • Ability to set the height of the lower indicator panel by percent of the overall chart area through panel.lower.size.percent.
  • Chart performance has been improved by dropping the number of API requests needed to generate the chart.

JavaScript Location:

https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.4.4/js/chartworks.min.js

v1.4.3

Released November 2017

What's new in v1.4.3:

JavaScript Location:

https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.4.3/js/chartworks.min.js

v1.4.0

Released June 2017

What's new in v1.4.0:

  • New Awesome Oscillator lower indicator.
  • New Bollinger Band %B lower indicator.
  • Added the ability to show comparison symbols on chart load with config parameter compareSymbols. Nice for Markets Overview pages where you'd like to show all the major indices on a single comparison chart without the user having to manually add them.
  • Added the ability to supply the chart with a custom color palette with style.palette.
  • Added the ability to easily chart currency cross rates by passing in the two currency codes you wish to chart. See Currency Cross Rates for details.
  • New settings menu for toggling extended hours on/off, printing the chart and downloading the chart image. See feature.settings.
  • Added the ability to display extended market hours data on intraday charts (currently only for US exchanges). See the Extended Hours section for more details.
  • Added the ability to print the chart. See feature.settings.print for details.
  • Added the ability to download the chart as an image. See feature.settings.downloadImage for details.
  • Updated the Japanese ("ja-JP") culture code default up/down colors for Candlesticks, OHLC, HLC and lower indicators so that red is up and blue/green is down as Japanese users would expect.
  • Updated some Japanese translations to be more accurate.
  • Added better scroll wheel handling to prevent the page scrolling while zooming in/out the chart.
  • Bug fix with tools not drawing on touch devices.
  • General bug fixes

JavaScript Location:

https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.4.0/js/chartworks.min.js

v1.3.3

Released April 2017

What's new in v1.3.3:

  • Added the ability to display Open, High and Low rollover data in addition to Close data on price styles that don't use Open, High, Low data to draw (e.g. Line, Area, Dot, Bar styles). See feature.dataLegendOHLC and feature.small.dataLegendOHLC for full details.
  • Better error handling on API failures to suppress the loading spinner.
  • General bug fixes

JavaScript Location:

https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.3.3/js/chartworks.min.js

v1.3.2

Released March 2017

What's new in v1.3.2:

JavaScript Location:

https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.3.2/js/chartworks.min.js

v1.3.1

Released November 2016

What's new in v1.3.1:

JavaScript Location:

https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.3.1/js/chartworks.min.js

v1.2.0

Released September 2016

What's new in v1.2.0:

JavaScript Location:

https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.2.0/js/chartworks.min.js

v1.1.0

Released July 2016

What's new in v1.1.0:

  • New indicator shows high/low prices on chart (under 'Indicator' > 'Trend' > 'High / Low Price')
  • New HLC (High Low Close) price style
  • OHLC now supports up/down colors
  • Improved collision handling for events displayed on the chart
  • Timestamp added to intra-day rollovers
  • New style.indicator.price.fillColor config parameter
  • Ability for users to save a complete chart including symbol and drawings/annotations. See feature.saveLoad, feature.saveLoadCharts and feature.saveLoadTemplates for implementation options.
  • Ability to show custom events in the Events menu to toggle on/off. See custom events and loadCustomEvents for more information.
  • Exchange is now always displayed with symbols for clarification.
  • General bug fixes

JavaScript Location:

https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.1.0/js/chartworks.min.js

v1.0.0

Released June 2016

This is the initial release of the Chartworks HTML5 charts.

JavaScript Location:

https://content.markitcdn.com/www.chartworks.io/content/chartworks/dist/1.0.0/js/chartworks.min.js