Building a Custom Portal

Building a Custom Portal is easy to do manually for anyone or developers can build them in code either on the client side in Javascript or on the server side whatever the technlogy used on the server is.

To build a custom portal, you need to build a set of JSON settings objects. Don't worry, they are very easy to make manually if you need to (see this introduction to JSON).

There are several ways to build and send these settings to the portal using two main methods:

  1. Pass a URL from where the settings are to be obtained
  2. Pass a base64 encoded settings object

Passing a URL to Settings

To make this work across domains, the Portal uses JSONP (don't get worried about the extra P if you're building this manually and are not a developer, see the example below) to obtain the information from that URL. Use chartiq_portal_magic as the callback function name. This method can be used for manually generated settings files that you can host or for server side dynamic settings generation.

The URL to your settings file is passed to the widget iFrame URL as a parameter called "customsettingsurl"

<!-- The Portal Frame -->
<iframe id="myframe" src="//YOUR_UNIQUE_URL/custompage.html?customsettingsurl=URL_FOR_THE_CUSTOM_SETTIGNS" style="overflow:hidden;width:100%;" scrolling="no" frameborder="0"></iframe>

We have a sample settings file here. To use this file the code would look like this with our unique link:

<!-- The Portal Frame -->
<iframe id="myframe" src="//globalwidgets.xignite.com/ChartIQ/Widgets2Test/custompage.html?customsettingsurl=https%3A%2F%2Fdemo.chartiq.com%2Fwidgets%2F2.0%2Fsamplesettings%2Fcustomsettings2.json" style="overflow:hidden;width:100%;" scrolling="no" frameborder="0"></iframe>

Note that the link is URL Enoded. You can manually URL encode links here

Passing an Encoded Settings Object

To pass settings directly to the URL if you do not have the ability to host settings files or if you are building settings dynamically on the client side you can create a settings object, then base 64 encode it and pass it to the URL. You can manually build settings objects and base64 encode them and pass them to the URL:

<!-- The Portal Frame -->
<iframe id="myframe" src="//YOUR_UNIQUE_URL/custompage.html?customsettings=BASE64_ENCODED_SETTIGNS" style="overflow:hidden;width:100%;" scrolling="no" frameborder="0"></iframe>

If you are building the settings object manually, these tools are useful:

Taking the settings JSON from the sample settings file above (the JSON is the part from the first '{' to the last '}') and encoding it, here is what this would look like with our unique link:

<!-- The Portal Frame -->
<iframe id="myframe" src="//globalwidgets.xignite.com/ChartIQ/Widgets2Test/custompage.html?customsettings=eyJkYXRhU291cmNlIjoieGlnbml0ZSIsInBhcmVudE5hdiI6IlRvcCBNb3ZlcnMgVVMiLCJpdGVtcyI6eyJTZWFyY2gxIjp7Iml0ZW1UeXBlIjoiU2VhcmNoIn0sIk5hdmlnYXRpb24xIjp7Iml0ZW1UeXBlIjoiTmF2aWdhdGlvbiIsIm5hdmlnYXRpb24iOltbIlRvcCBNb3ZlcnMgVVMiLCJvdmVydmlldy5odG1sP2N1c3RvbXNldHRpbmdzdXJsPWh0dHBzOi8vZGVtby5jaGFydGlxLmNvbS93aWRnZXRzLzIuMC9zYW1wbGVzZXR0aW5ncy9jdXN0b21zZXR0aW5nczIuanNvbiJdLFsiVG9wIE1vdmVycyBVSyIsImN1c3RvbXBhZ2UuaHRtbD9jdXN0b21zZXR0aW5nc3VybD1odHRwczovL2RlbW8uY2hhcnRpcS5jb20vd2lkZ2V0cy8yLjAvc2FtcGxlc2V0dGluZ3MvY3VzdG9tc2V0dGluZ3MzLmpzb24iXV19LCJUb3BNb3ZlcnMxIjp7Iml0ZW1UeXBlIjoiVG9wTW92ZXJzIiwibnVtYmVyT2ZJdGVtcyI6N30sIk5ld3MxIjp7Iml0ZW1UeXBlIjoiVGlja2VyTmV3cyIsIm51bWJlck9mSXRlbXMiOjUsImRlcGVuZHNPbiI6IlRvcE1vdmVyczEifSwiQ2hhcnQxIjp7Iml0ZW1UeXBlIjoiU2ltcGxlQ2hhcnQiLCJkZXBlbmRzT24iOiJUb3BNb3ZlcnMxIn0sIkZ1bmRhbWVudGFsQ2hhcnQxIjp7Iml0ZW1UeXBlIjoiRnVuZGFtZW50YWxDaGFydCIsImZ1bmRhbWVudGFscyI6W3siZnVuZGFtZW50YWwiOiJTYWxlc09yUmV2ZW51ZSIsImxhYmVsIjoiUXVhcnRlcmx5IFJldmVudWUiLCJ0ZXJtIjoiUXVhcnRlcmx5In0seyJmdW5kYW1lbnRhbCI6IlNhbGVzT3JSZXZlbnVlIiwibGFiZWwiOiJUVE0gUmV2ZW51ZSIsInRlcm0iOiJUVE0ifV0sInllYXJzIjo1LCJkZXBlbmRzT24iOiJUb3BNb3ZlcnMxIn0sIkZ1bmRhbWVudGFsQ2hhcnQyIjp7Iml0ZW1UeXBlIjoiRnVuZGFtZW50YWxDaGFydCIsImZ1bmRhbWVudGFscyI6W3siZnVuZGFtZW50YWwiOiJFUFMiLCJsYWJlbCI6IlF1YXJ0ZXJseSBFUFMiLCJ0ZXJtIjoiUXVhcnRlcmx5In0seyJmdW5kYW1lbnRhbCI6IkVQUyIsImxhYmVsIjoiVFRNIEVQUyIsInRlcm0iOiJUVE0ifV0sInllYXJzIjo1LCJkZXBlbmRzT24iOiJUb3BNb3ZlcnMxIn0sIkZpbmFuY2lhbHMxIjp7Iml0ZW1UeXBlIjoiRmluYW5jaWFscyIsImRlcGVuZHNPbiI6IlRvcE1vdmVyczEifSwiSW5zaWRlcnMxIjp7Iml0ZW1UeXBlIjoiSW5zaWRlcnMiLCJkZXBlbmRzT24iOiJUb3BNb3ZlcnMxIiwiQ2hhcnQxIjp0cnVlLCJ0YWJsZSI6dHJ1ZX0sIkZ1bmRhbWVudGFsczEiOnsiaXRlbVR5cGUiOiJGdW5kYW1lbnRhbHMiLCJkZXBlbmRzT24iOiJUb3BNb3ZlcnMxIiwiZnVuZGFtZW50YWxzIjp7InN0b2NrIjp7IkJ1c2luZXNzRGVzY3JpcHRpb24iOiJCdXNpbmVzcyBEZXNjcmlwdGlvbiIsIlBFUmF0aW8iOiJQcmljZS9FYXJuaW5ncyBSYXRpbyIsIlByaWNlVG9Cb29rIjoiUHJpY2UvQm9vayBSYXRpbyIsIlByaWNlVG9DYXNoRmxvdyI6IlByaWNlL0Nhc2ggRmxvdyIsIlByaWNlVG9TYWxlc0Zpc2NhbCI6IlByaWNlL1NhbGVzIChUVE0pIiwiUXVpY2tSYXRpbyI6IlF1aWNrIFJhdGlvIiwiQ3VycmVudFJhdGlvIjoiQ3VycmVudCBSYXRpbyAoTVJRKSIsIkxvbmdUZXJtRGVidFRvRXF1aXR5UmF0aW8iOiJMVCBEZWJ0IHRvIEVxdWl0eSIsIkxvbmdUZXJtRGVidFRvVG90YWxDYXBpdGFsIjoiTFQgRGVidCB0byBUb3RhbCBDYXBpdGFsIiwiUmV0dXJuT25Db21tb25FcXVpdHkiOiJSZXR1cm4gT24gRXF1aXR5IiwiUmV0dXJuT25Bc3NldHMiOiJSZXR1cm4gT24gQXNzZXRzIiwiNVllYXJBdmVyYWdlUmV0dXJuT25JbnZlc3RlZENhcGl0YWwiOiI1IFllYXIgQXZlcmFnZSBSZXR1cm4gT24gSW52ZXN0ZWQgQ2FwaXRhbCIsIkFzc2V0VHVybm92ZXIiOiJBc3NldCBUdXJub3ZlciIsIjUyV2Vla1JhbmdlIjp7IlR5cGUiOiJSYW5nZSIsIlRpdGxlVGV4dCI6IjUyIFdlZWsgUmFuZ2UiLCJWYWx1ZTEiOiJGaWZ0eVR3b1dlZWtMb3ciLCJWYWx1ZTIiOiJGaWZ0eVR3b1dlZWtIaWdoIiwiVmFsdWUzIjoiTGFzdCJ9LCJEYXlSYW5nZSI6eyJUeXBlIjoiUmFuZ2UiLCJUaXRsZVRleHQiOiJEYXkgUmFuZ2UiLCJWYWx1ZTEiOiJMb3ciLCJWYWx1ZTIiOiJIaWdoIiwiVmFsdWUzIjoiTGFzdCJ9fSwiZnVuZCI6eyI1MldlZWtSYW5nZSI6eyJUeXBlIjoiUmFuZ2UiLCJUaXRsZVRleHQiOiI1MiBXZWVrIFJhbmdlIiwiVmFsdWUxIjoiRmlmdHlUd29XZWVrTG93IiwiVmFsdWUyIjoiRmlmdHlUd29XZWVrSGlnaCIsIlZhbHVlMyI6Ikxhc3QifSwiRnVuZE9iamVjdGl2ZSI6IkZ1bmQgT2JqZWN0aXZlIiwiTmV0QXNzZXRzIjoiTmV0IEFzc2V0cyIsIlByb3NwZWN0dXNOZXRFeHBlbnNlUmF0aW8iOiJQcm9zcGVjdHVzIE5ldCBFeHBlbnNlIFJhdGlvIiwiVHJhaWxpbmdUd2VsdmVNb250aFlpZWxkIjoiVFRNIFlpZWxkIiwiV2VpZ2h0aW5nVG9wVGVuSG9sZGluZ3MiOiJUb3AgVGVuIEhvbGRpbmdzIFdlaWdodCIsIlR1cm5vdmVyUmF0aW8iOiJUdXJub3ZlclJhdGlvIiwiSW5pdGlhbEludmVzdG1lbnQiOiJJbml0aWFsIEludmVzdG1lbnQiLCJDbG9zZWRUb05ld0ludmVzdG9ycyI6IkNsb3NlZCBUbyBOZXcgSW52ZXN0b3JzIn0sImV0ZiI6eyI1MldlZWtSYW5nZSI6eyJUeXBlIjoiUmFuZ2UiLCJUaXRsZVRleHQiOiI1MiBXZWVrIFJhbmdlIiwiVmFsdWUxIjoiRmlmdHlUd29XZWVrTG93IiwiVmFsdWUyIjoiRmlmdHlUd29XZWVrSGlnaCIsIlZhbHVlMyI6Ikxhc3QifSwiQnVzaW5lc3NEZXNjcmlwdGlvbiI6IkZ1bmQgU3VtbWFyeSIsIk5ldEFzc2V0cyI6Ik5ldCBBc3NldHMiLCJQcm9zcGVjdHVzTmV0RXhwZW5zZVJhdGlvIjoiUHJvc3BlY3R1cyBOZXQgRXhwZW5zZSBSYXRpbyIsIlRyYWlsaW5nVHdlbHZlTW9udGhZaWVsZCI6IlRUTSBZaWVsZCIsIldlaWdodGluZ1RvcFRlbkhvbGRpbmdzIjoiVG9wIFRlbiBIb2xkaW5ncyBXZWlnaHQiLCJUdXJub3ZlclJhdGlvIjoiVHVybm92ZXJSYXRpbyJ9fSwiZGlzcGxheSI6eyJzdG9jayI6W1siQ29tcGFueSIsW1siQnVzaW5lc3NEZXNjcmlwdGlvbiJdXV0sWyJQZXJmb3JtYW5jZSIsW1siNTJXZWVrUmFuZ2UiXSxbIkRheVJhbmdlIl1dXSxbIlZhbHVhdGlvbiIsW1siUEVSYXRpbyIsIlByaWNlVG9Cb29rIl0sWyJQcmljZVRvQ2FzaEZsb3ciLCJQcmljZVRvU2FsZXNGaXNjYWwiXV1dXSwiZnVuZCI6W1siQ29tcGFueSIsW1siRnVuZE9iamVjdGl2ZSJdXV0sWyJQZXJmb3JtYW5jZSIsW1siNTJXZWVrUmFuZ2UiXV1dLFsiRnVuZGFtZW50YWxzIixbWyJUcmFpbGluZ1R3ZWx2ZU1vbnRoWWllbGQiLCJOZXRBc3NldHMiLCJDbG9zZWRUb05ld0ludmVzdG9ycyJdXV0sWyJQb3J0Zm9saW8iLFtbIldlaWdodGluZ1RvcFRlbkhvbGRpbmdzIiwiVHVybm92ZXJSYXRpbyJdXV1dLCJldGYiOltbIkNvbXBhbnkiLFtbIkJ1c2luZXNzRGVzY3JpcHRpb24iXV1dLFsiUGVyZm9ybWFuY2UiLFtbIjUyV2Vla1JhbmdlIl1dXSxbIkZ1bmRhbWVudGFscyIsW1siVHJhaWxpbmdUd2VsdmVNb250aFlpZWxkIiwiTmV0QXNzZXRzIl1dXSxbIlBvcnRmb2xpbyIsW1siV2VpZ2h0aW5nVG9wVGVuSG9sZGluZ3MiXV1dXX19fSwibGF5b3V0IjpbW1siTmF2aWdhdGlvbjEiXV0sW1siVG9wTW92ZXJzMSJdXSxbWyJDaGFydDEiLCJGdW5kYW1lbnRhbHMxIl1dLFtbWyJOZXdzMSJdLFsiRnVuZGFtZW50YWxDaGFydDEiLCJGdW5kYW1lbnRhbENoYXJ0MiJdXV0sW1siSW5zaWRlcnMxIl1dXX0=" style="overflow:hidden;width:100%;" scrolling="no" frameborder="0"></iframe>

Settings

General Settings

defaultSymbol: default symbol when one is not specified in the URL or in settings

chartRefreshRate: refresh rate for charts

quoteRefreshRate: refresh rate for quotes

newsRefreshRate: refresh rate for news

quoteURL: url where quote results should go to (e.g. from News/Quoteboard). If the URL starts with http or https, the link will open in a new window. Otherwise the link will be followed within the frame. If you are building a full portal, you can use internal links. If you are using a group of widgets as a sidebar, you can use full links that start with http or https to avoid the link being opened in a tiny frame on your site.

searchURL: url where search results should go to

themeCSS: Location of folder with themes for all used widgets (only for major theme changes, see here for more information on styling)

darkLogos: Set to true for dark themes

webFonts: Array of Google Fonts needed by your custom stylesheets. e.g ['Roboto', 'Kanit']

searchExchanges: Array of Exchanges to search.

parentNav: Which item in a Navigation widget should be active

Items and Layout

items: An object contianing all the widgets that are used on the page

layout: The layout of the widgets. Note that the layout is automatically responsive

Please see the Portal Layout section for more information

Building A Settings Object Manually

To build a settings object manually, you can use any text editor of your choice to build a JSON object like below with any of the above settings like shown here:

{
    "defaultSymbol": "GOOG",
    "chartRefreshRate": 5,
    "items": {
        "chart1": {
            "itemType": "BasicChart",
            "symbol": "SPY"
        },
        "chart2": {
            "itemType": "BasicChart",
            "symbol": "DIA"
        }
    },
    "layout": [
        [["chart1", "chart2"]]  
    ] 
}

Once you build your object, make sure you do the following:

  1. Validate the JSON
  2. Minify the JSON
  3. Base 64 encode the JSON

If you are building this to store in a file enclose the settings object in a callback function like shown here. This is the P part of JSONP.

chariq_portal_magic({
    "defaultSymbol": "GOOG",
    "chartRefreshRate": 5,
    "items": {
        "chart1": {
            "itemType": "BasicChart",
            "symbol": "SPY"
        },
        "chart2": {
            "itemType": "BasicChart",
            "symbol": "DIA"
        }
    },
    "layout": [
        [["chart1", "chart2"]]  
    ] 
})

In this case the object goes into the file as it is without any Base 64 encoding.

Building A Settings Object In Javascript

If you are dynamically building the settings in Javascript, you can use a library (such as hi-base64 to base64 encode the object and then set the URL of the iFrame as shown below

var settings = {
    "defaultSymbol": "GOOG",
    "chartRefreshRate": 5,
    "items": {
        "chart1": {
            "itemType": "BasicChart",
            "symbol": "SPY"
        },
        "chart2": {
            "itemType": "BasicChart",
            "symbol": "DIA"
        }
    },
    "layout": [
        [["chart1", "chart2"]]  
    ] 
}

var settingsText = JSON.stringify(settings); // Convert object to a string
var frame=document.getElementById('myFrame');
frame.src='//YOUR_UNIQUE_URL/custompage.html?customsettings=' + base64.encode(settingsText)

Here is this code in action:

Here is a JSFiddle with the code:

Symbol Passing Considerations

You can simply pass a symbol to the Portal (or Widgets) using the sym URL Parameter as shown in Getting Started - Linking to a Specific Symbol. You can also set the defaultSymbol setting as shown above. And you can set the symbol property of specific widgets. An individual widget looks for a symbol in this order:

  1. symbol property of the widget
  2. sym URL Parameter
  3. defaultSymbol in the settings