Matrix JS Overview

About MatrixJS

The goal of MatrixJS is to allow organisations and individuals alike build beautiful User Interfaces into an organisation’s data stores with minimal effort.

MatrixJS is a lightweight JavaScript framework which supports browsing the available datasets in the Fusion Matrix, creating and executing a data query, and rendering the response.

Whie the Fusion Matrix can be used to organise your data and link multiple data stores through a common interface. MatrixJS makes it possible to create the view of your data that suite your needs.

MatrixJS is free to download and use from the Getting Started section.

Project Architecture

When including MatrixJS on your project, the framework automatically creates an instance of the MatrixManager and assigns this to the variable $MTX. The MatrixManager is the entry point into the framework and can be used to obtain any other class, as shown in the diagram below.

Showing a high level design of the MatrixJS API

The MatrixStructureBrowser is used to obtain categorised information about which datasets exist, and what is contained within each dataset (MatrixTopicDefinition)

The MatrixDataBrowser provides access to a complete description of the dataset in terms of the dimensionality of the data, and available code choices for each dimension. In addition, the MatrixDataBrowser facilitates in the creation and execution of a data query.

The MatrixMetadataManager provides the ability to access additional information about structures and data known as ReferenceMetadata.

The MatrixPPQManager provides the means to create, store, and run pre-packaged queries, these are queries that have been pre-built and stored, either globally on the Fusion Matrix server, or locally by the user on their computer.

In addition to the data discovery components are data visualisation components which provide HTML widgets that can be added to a web page. The data visualisation components can be styled through CSS, with the default styles being shown in the Fusion Matrix UI below.

Showing a high level design of the MatrixJS API

The MatrixCodePicker builds a checkbox tree per dimension, allowing the user to select which code values to include in the data query. Between code selections, the MatrixCodePicker interacts with the Fusion Matrix server to grey out invalid selections based on current query state.

The PivotTable builds an HTML table based on a MatrixDataSet that results from a data query. The PivotTable provides the user with the ability to choose how the dimensions are organised in the table, and even move dimensions out to create a cross sectional view of the data.

Project Dependencies

MatrixJS has dependencies on the following javascript frameworks. MatrixJS is distributed with the required dependencies.

JQuery

JQuery is required for both the visual components, and to communicate with the Fusion Matrix web services.

Bootstrap

Bootstrap 2 or 3 can be used. The only dependency on bootstrap is the popover plugin, which is required for the pivot table. The MatrixJS project is distributed with a custom built bootstrap library, with only the popover plugin included.

Font Awesome

Font Awesome provides icons used by both the codepicker and pivot table components.


MatrixJS Demo

Below you’ll find a couple of demo websites using MatrixJS connecting to our demo Fusion Matrix running at http://demo.metadatatechnology.com/FusionMatrix.

The websites took a couple of hours each to write, with all the code contained in a single html file. We have written two demos with a completely different look and feel to demonstrate how MatrixJS can be used as a versatile library.

Both demos can be downloaded. All the source code is in index.html, this is also where the Fusion Matrix connection URL is defined.

It is important to note that if a JavaScript connection is attempting to create a cross domain request, i.e. the connection is to a server on a different domain to the Fusion Matrix application, then some browsers will require the user to click ‘Allow Blocked Content’.

Demo 1

JavaScript: ~300 Lines
HTML: ~40lines
CSS: ~60lines

Showing a high level design of the MatrixJS API

The purpose of this demo is to show the Code Picker, Constraints, and Pivot Table components.

This demo simply makes use of a Javascript library called isotope to arrange all the available topics on the page. There is a top level navigation bar which allows topics to be filtered. When the user clicks browse data, the page changes to show the user the topic dimensions, and a code picker for each dimension.

On making code selections, the constraints interface is called, and the available code choices are updated for each dimension. The constraints interface also informs the client of the number of series which match the current query criteria. Once the number of series falls below a threshold, a data query is submitted to the server, and the response is displayed to the user as a Pivot table.

The default styles of the components have been overridden using local CSS.

The URL of the page updates on each user interaction to record the page state, this means data queries can be bookmarked using the browsers bookmark facility.

Launch Demo Download Demo

Demo 2

JavaScript: ~350 Lines
HTML: ~50lines
CSS: ~100lines

Showing a high level design of the MatrixJS API

This demo shows the power of using MatrixJS alongside other charting libraries. The only data visualisation component MatrixJS provides is a Pivot Table, simply because there does not seem to be any other free charting library which provides such a feature. All other types of charts, maps, graphs can be obtained from organisations which specialise in data vislaisation.

The demo takes advantage of AmCharts’ JavaScript charts and Maps in order to allow the user to browse World Development Indicator datasets.

This demo also shows how custom page state can be stored in the URL bar, to allow pages to be bookmarked and shared.

Launch Demo Download Demo

Download



Downloads Page







MatrixDataBrowser

The MatrixDataBrowser is created for a particular MatrixTopic which contains information about a single dataset.

The MatrixDataBrowser provides access to the underlying MatrixTopic as well as methods for both creating and executing a data query, returning a MatrixDataSet. The MatrixDataBrowser will update the browser URL as codes are selected and deselected, and can set its initial state from the URL of the browser, enabling a user to bookmark the page and recreate the exact state when reloading from the bookmarked URL.

The MatrixDataBrowser facilitates in preventing a user from creating a data query resulting in no data being returned, which can occur when a make code selections in more than one dimension which, when combined, do not match any series in the dataset. It achieves this by providing the queryConstraints method.

Note: The MatrixStructureBrowser should be obtained via the MatrixManager.getMatrixDataBrowser method


addCodeSelection(MatrixCode code)

Adds a MatrixCode to the data query selection, as the MatrixCode contains information about the MatrixDimension it belongs to, this will result in a query for the code in the given dimension.

Method Parameters


addSeriesSelection( String)

Adds a series to the selection based on the series short code. The short code is a concatenated series key where the separator is a ':' for example a series short code may look like the following: A:FR:DE:T10

A short code may also be obtained from MatrixSeries.getShortCode

Method Parameters

  • String: - shortCode

buildQueryURL(JSON exportFormat,Boolean seriesOnly,Boolean includeRevisions,Boolean saveAs)

Builds a web service query URL which can be used to obtain data conforming to the given code & date selections in the MatrixDataBrowser. The URL will also include an export format, and wether to include revisions or not

The user must pass a JSON argument to define the format, the structure is shown in the example.

Method Parameters

  • exportFormat:JSON -
  • seriesOnly:Boolean - if true then will only export the series (no observations)
  • includeRevisions:Boolean - true to include revisions, false to exclude them
  • saveAs:Boolean - (optional) if true then the response will be a file. If false or not specified then the service will return the raw data as a Stream.

Example

Example JSON for export format

{
"format" : "generic|compact|sdmxjson|sdmxedi|csv|excel",
"version" : "1.0|2.0|2.1",    (generic or compact only)
"delimiter" : "comma|tab|semicolon|space",  (csv only)
"time" : "x|y",  (csv only time on x-axis or y-axis)
"decode" : "true|false" (csv/xlsx only)
}

clearAllSelections()

Clears all previous MatrixCode selections and series selections


clearCodeSelections(String dimId)

Clears the MatrixCode selections for the given dimension

Method Parameters

  • dimId:String -

clearSeriesSelections()

Clears all the selected series


exportData(JSON exportFormat,Boolean seriesOnly,Boolean includeRevisions)

Exports the data as a file downloaded via the users browser

The user must pass a JSON argument to define the format, the structure is shown in the example.

Method Parameters

  • exportFormat:JSON -
  • seriesOnly:Boolean - if true then will only export the series (no observations)
  • includeRevisions:Boolean - true to include revisions, false to exclude them

Example

Example JSON for export format

{
"format" : "generic|compact|sdmxjson|sdmxedi|csv|excel",
"version" : "1.0|2.0|2.1",    (generic or compact only)
"delimiter" : "comma|tab|semicolon|space",  (csv only)
"time" : "x|y",  (csv only time on x-axis or y-axis)
"decode" : "true|false" (csv/xlsx only)
}

exportMetadata(Boolean isDatasetMetadata)

Exports all the ReferenceMetadata for the current dataset, or structures related to the selected topic

Method Parameters

  • isDatasetMetadata:Boolean - if true this will export all the metadata for the dataset, otherwise it will export all of the metadata against the structures

exportStructure()

Exports all the Structural Metadata for the given MatrixTopic


getCodeSelections(String dimId)

Returns an Array of code selection for the given dimension, or an empty array if non exist

Method Parameters

  • dimId:String -

getCountSelections(String dimId)

Returns a count of all selections for all dimensions

Method Parameters

  • dimId:String -

getDateFrom()

Returns the selected start date, or null if there is not one selected

Returns: Date


getDateTo()

Returns the selected end date, or null if there is not one selected

Returns: Date


getLastN()

Returns the last N observations selected in the data query, or null if this is not set

Returns: s Integer


getSeriesSelections()

Returns the array of series selections, where each array element is a String series short code

Returns: Array


getTopic()

Returns the MatrixTopic that this data browser is constructing a data query for

Returns: MatrixTopic


getValidKeysCount()

Returns the number of valid keys based on the last call to queryConstraints

Returns: Integer


getValidObsCount()

Returns the potential number of valid observations based on the last call to queryConstraints

Returns: Integer


hasCodeSelections(String dimId)

Returns true if the dimension has at least one code selection against it

Method Parameters

  • dimId:String -

hasDateFrom()

Returns true if a date from has been selected in the query

Returns: s Boolean


hasDateTo()

Returns true if a date to has been selected in the query

Returns: s Boolean


hasLastN()

Returns true if the selection has

Returns: Boolean


hasSeriesSelections(String dimId)

Returns true if there are any series selections

Method Parameters

  • dimId:String -

queryConstraints()

Queries the Fusion Matrix for Valid Codes based on the current data query state, notifies the constrainedCodeNotifyFunction each time the state of a code is changed from valid to invalid or vice-verca.

Updates the internal state with the number of series keys that would be returned from a data query based on the current selection state, and also updates the number of potential observations, if the data cube is fully populated.

Invokes the constraints callback function on completion. The constraint callback function is passed in on construction of the MatrixDataBrowser.

In addition, if the MatrixTopic.addCodeConstraintStateChangeListener has a constraint change listener added, it will be invoked for each Matrix that has it's isConstrained state changed


queryData(Boolean includeRevisions, callbackFunction)

Query the Fusion Matrix for the dataset which conforms to the current query selections

Method Parameters

  • includeRevisions:Boolean - if true then the response will contain any revised values for observations
  • callbackFunction: - (optional) this will override the default callback registered on creation of this MatrixDataBrowser. The callback function is expected to take 1 argument, which is the MatrixDataSet which results from this query

refreshTopic()

Re-queries for the Topic from the server, this should be used if the topic has been changed on the server to referesh the cache.


removeCodeSelection(MatrixCode code)

Removes the MatrixCode from selection

Method Parameters


removeSeriesSelection( shortCode)

Removes the series from selection based on the series short code. The short code is a concatenated series key where the separator is a ':' for example a series short code may look like the following: A:FR:DE:T10

A short code may also be obtained from MatrixSeries.getShortCode

Method Parameters

  • shortCode: -

setDateFrom(Date dateFrom)

Sets the first observation date (inclusive) for the data query

Method Parameters

  • dateFrom:Date - (or ISO8601 String)

setDateTo(Date dateTo)

Sets the last observation date (inclusive) for the data query

Method Parameters

  • dateTo:Date - (or ISO8601 String)

setLastN(Integer lastN)

Sets the last 'N' observations to be bought back from the data query, if this is set, then the date range will be removed from the query

Method Parameters

  • lastN:Integer -

setStateFromURL()

Clears the current state and resets it based on the

MatrixStructureBrowser

The MatrixStructureBrowser contains information about which datasets (MatrixTopic) are available in the FusionMatrix.

The MatrixStructureBrowser does not provide direct access to the MatrixTopic instead it provides access to MatrixTopicDefinition which provide high level details about a MatrixTopic such as the owning agency, name, description, series count, available dimensions, Pre-defined queries (MatrixPPQ) and more.

MatrixTopic may be categorised by one or more MatrixCategory which enables discovery of a dataset via a hierarchical category scheme.

Note: The MatrixStructureBrowser should be obtained via the MatrixManager.getMatrixStructureBrowser method

Constructor Parameters

  • matrixURL:String - the URL of the FusionMatrix e.g. http://demo.metadatatechnology.com/FusionMatrix
  • callback:Function - a function to call on succesfull creation

compareTopicsByName(MatrixTopic a,MatrixTopic b)

A compare function that can be used to sort an array of MatrixTopic by name

Method Parameters

  • a:MatrixTopic -
  • b:MatrixTopic -

Returns: Integer


getAgencies()

Returns an array of agencies that have available datasets in the FusionMatrix

Returns: JSONArray

Example

JSON is formatted as follows:
[
{
Id: "AgencyId",
Name: "Agency Name"
},
{...}
]

getAgencyById()

Returns an agency with the given Id, where the agency has the following structure:

Returns: JSONObject

Example

JSON is formatted as follows:
{
Id: "AgencyId",
Name: "Agency Name"
}

getCategories()

Returns an array of all the MatrixCategory

Returns: Array<MatrixCategory>


getCategoriesForTopic(String topicId)

Returns an array of MatrixCategory SdmxUrn for the given topic id

Method Parameters

  • topicId:String -

Returns: Array<SdmxUrn>


getCategoryByUrn(String urn)

Returns a MatrixCategory with the given URN or null if no such category exists

Method Parameters

  • urn:String - Category URN

Returns: MatrixCategory


getConcepts()

Returns a String array of all the available dimension names for all available MatrixTopic

Returns: Array


getTopicById( id)

Returns the MatrixTopicDefinition with the given id or null if the id does not match any MatrixTopicDefinition

Method Parameters

Returns: MatrixTopicDefinition


getTopics()

Returns an array of all the MatrixTopicDefinition objects that exist

Returns: Array<MatrixTopicDefinition>


getTopicsByAgencyId(String agencyId)

Returns an array of all the MatrixTopicDefinition objects that are maintained by the given agency

Method Parameters

  • agencyId:String - the id of the agency to return the topics for

Returns: Array<MatrixTopicDefinition>


getTopicsForConcept(String dimname)

Returns an array of MatrixTopicDefinition ids for the given dimension name

Method Parameters

  • dimname:String - Dimension Name

Returns: Array



MatrixManager

The MatrixManager is the primary object required in the MatrixJS framework, and is responsible for obtaining all other JavaScript classes built from information obtained from the linked Fusion Matrix web services.

Note: It is not possible to create an instance of this class. MatrixJS Automatically created a MatrixManager and assigns it to the variable $MTX.

Example

$MTX.connect("http://demo.metadatatechnology.com/FusionMatrix", function() {
//Connected
var structureBrowser = $MTX.getMatrixStructureBrowser(function() {
for(var i=0; i < structureBrowser.getCategories().length; i++) {
//Do Something
}
});
);

connect(String matrixURL,Function callbackFunction,Funsion loadingListener)

Connect to Fusion Matrix at the given URL.

Method Parameters

  • matrixURL:String - (optional) the URL of the FusionMatrix e.g. http://demo.metadatatechnology.com/FusionMatrix.
  • callbackFunction:Function - the function to call on successful construction. The function should be a no argument function, and is called once the FusionMatrix has successfully responded with the expected information. The MatrixManager should not be used before the callback function has been invoked
  • loadingListener:Funsion - (optional) The Fusion is expected to take a boolean parameter, true to indciate that MatrixJS is sending a message to the server and awiting a response, false to indicate that the server has responded and there is no response pending

Example

$MTX.connect("http://demo.metadatatechnology.com/FusionMatrix", function() {
//Connected
});

getItemByUid(String uid)

Returns the item with the UID or null if no such item exists

Method Parameters

  • uid:String -

Returns: AnyMatrixStructure


getMatrixDataBrowser(String topicId,Function constraintsCallbackFunction,Function dataQueryCallbackFunction,Function creationCompleteCallbackFunction)

Creates a new instance of the MatrixDataBrowser which is passed to the the callback function on completion

Method Parameters

  • topicId:String - the Id of the MatrixTopic to browse and create a data query for. This value can also be obtained from the MatrixTopicDefinition If this value is null, then the value is read from the tp argument obtained from the URLManager
  • constraintsCallbackFunction:Function - this is called when the MatrixDataBrowser.queryConstraints is invoked and has finished updating the MatrixCode state based on if it remains valid based on the current data query. This is expected to be a no-argument function
  • dataQueryCallbackFunction:Function - this is called when the MatrixDataBrowser.queryData function is invoked and has obtained a data response from the Fusion Matrix. This function is expected to take one argument, the MatrixDataSet
  • creationCompleteCallbackFunction:Function - this is expected to take one argument, the MatrixDataBrowser

Returns: MatrixDataBrowser Note: This will not be ready to use until the creationCompleteCallbackFunction is called


getMatrixStructureBrowser(Function callbackFunction)

Creates a new instance of the MatrixStructureBrowser which is passed to the the callback function on completion

Method Parameters


getMatrixUrl()

Returns the URL of the linked Fusion Matrix

Returns: String


getMetadataManager()

Returns the MatrixMetadataManager which can be used to obtain additional ReferenceMetadata linked to both structures, and data

Returns: MatrixMetadataManager


getPrePackagedQueryManager(String cookieKey)

Returns the MatrixPPQManager which is used to obtain information about pre-packaged queries as stored on both the user's computer as a cookie, and as defined in the Fusion Matrix by the Matrix administrator

Method Parameters

  • cookieKey:String - If supplied this will be the key to the local cookie storage (i.e the Matrix will store/retrieve local queries to this key). If not supplied then a default key will be used.

Returns: MatrixPPQManager


getSelectedLanguage()

Returns the default language to return structure/data/metadata in. This will default to the browser language setting

Returns: String


getSupportedLanguages()

Returns an array of supported languages for the Matrix Structural Metadata

Returns: Array


getUrlManager()

Returns the URLManager which is used to manage the Fusion Matrix state.

Returns: URLManager


getUtils()

Returns MatrixUtil which contains utility functions used by MatrixJS

Returns: s MatrixUtil


getViewMetadataIcon()

Returns a HTML element to indicate that there is metadata to view, or an empty string if no metadata exists.


setSelectedLanguage( lang)

Sets the default language to return structure/data/metadata in. This can be used to override the browser's language setting. callbackFunction optional, if provided this will be called once the language is set. This would allow the client to reload the page

Method Parameters

  • lang: - String

MatrixMetadataManager

Manages the retrieval of ReferenceMetadata from the connected Fusion Matrix. The retrieved metadata is cached locally, so that multiple calls for the same metadata item are retrieved from the local cache

Note: The MatrixMetadataManager should be obtained via the MatrixManager.getMetadataManager method


clearCache()

Clears the local metadata cache


getMetadata(ReferenceMetadataLink refMetadataLink,Function callbackFunction)

Queries for and returns the ReferenceMetadata to the callback function

Method Parameters


getMetadataById(String id,Function callbackFunction)

Queries for and returns the ReferenceMetadata to the callback function forceReload boolean (optional) if true, will bypass the local cache to force a reload from the server

Method Parameters


getMetadataForUid(String UID,Function callbackFunction)

Returns all the Metadata Sets for the Structure with the given Unique Identifier (UID). Structures that have a UID include:

Method Parameters

  • UID:String - the UID of the Structure
  • callbackFunction:Function - this will be called with a resulting array of ReferenceMetadata or null if no metadata exists for the item

MatrixPPQManager

The MatrixPPQManager manages the storages retrieval of Pre-Packaged Queries (MatrixPPQ) which are either defined in the Fusion Matrix itself, or ones which have been stored by the user on their local computer (as a browser cookie). The MatrixPPQManager also manages the storage and deletion of MatrixPPQ from the users local computer.

Note: The MatrixPPQManager should be obtained via the MatrixManager.getPrePackagedQueryManager method

constructor


findById( id)

Returns the MatrixPPQ with the given id, or null if none exist

Method Parameters

  • id: - (String)

Returns: MatrixPPQ


getAllGlobalQueries()

Returns an array of all the globall stored MatrixPPQ

Returns: Array<MatrixPPQ>


getAllLocalQueries()

Returns an array of all the local stored MatrixPPQ

Returns: Array<MatrixPPQ>


getAllQueries()

Returns an array of all both global and locally stored MatrixPPQ

Returns: Array<MatrixPPQ>


getGlobalQueries(String flowUrn)

Returns an array of MatrixPPQ stored on the Fusion Matrix server for the given dataflow urn, or null if none exist

Method Parameters

  • flowUrn:String - if null, then the manager will look on the URLManager for the tp parameter

Returns: Array<MatrixPPQ>


getLocalQueries(String flowUrn)

Returns an array of MatrixPPQ stored locally for the given dataflow urn, or null if none exist

Method Parameters

  • flowUrn:String - if null, then the manager will look on the URLManager for the tp parameter

Returns: Array<MatrixPPQ>


hasQueries(String flowUrn)

Returns true if there are pre-packaged queries for the given dataflow urn

Method Parameters

  • flowUrn:String - if null, then the manager will look on the URLManager for the tp parameter

Returns: Boolean


isLocalStoreSupported()

Returns true if local storage is supported by the current web browser, false if not


saveQueryLocally(String name,String description, topic)

Saves a Pre-Packaged query locally as a browser cookie. This can be retrieved at any future date as long as the user does not delete the cookie. This stored query will be made available as a MatrixPPQ with the given name and description. The URL of the MatrixPPQ will be the contents of the $MTX parameter which comes after the # section in the URL.

The stored selected is derived from the tp parameter in the $MTX section of the URL.

The The Saved Query URL

Method Parameters

  • name:String - (mandatory)
  • description:String - (optional)
  • topic: - the topic to store the query for

URLManager

The URLManager is used to store state about the users current view of the FusionMatrix.

This class is used by MatrixJS modules such as the MatrixDataBrowser and PivotTable to store information such as the current data query, the current layout of the pivot table.

The URLManager uses the fragment-identifier (#) part of the URL in order to append a $MTX[...] parameter, where ... contains key value pairs separated by semicolons (;).

The URLManager can be obtained from the MatrixManager

Example

//Get data query
var dataQuery = $MTX.getUrlManager().getParamValue("dq");

//Set custom state about Pie chart
$MTX.getUrlManager().setParamValue("pie", "0:0:0")

getMatrixParams()

Returns the full value stored in the MTX=[...] part of the URL


getParamValue( param)

Returns the parameter value, or null if there is none

Method Parameters

  • param: - the parameter to return the value for

Returns: String


setMatrixParams(String value)

Sets the contents of the $MTX part of the URL to whatever is passed in as the value

Method Parameters

  • value:String -

setParamValue(String param,String value)

Updates the parameter value with the given value

Method Parameters

  • param:String -
  • value:String -




DataSetRevision

A DataSetRevision defines a valid from date and the dataset action


getRevisionDate()

Date this dataset was submitted

Returns: String


isDelete()

Returns true if the dataset submission was a delete message

Returns: Boolean

MatrixDataSet

A MatrixDataSet is a Wrapper around a SDMX-JSON DataSet to provide functions for retrieving series and observations

NOTE: A MatrixDataSet should be obtained via the MatrixDataBrowser.queryData method

Constructor Parameters

  • json: -

createSeries( dimensionAtObservation)

Returns MatrixSeriesGroup which is a container used to group MatrixObservation which iterate over the dimensionAtObservation. A MatrixSeriesGroup contains one or more MatrixSeries.

Method Parameters

  • dimensionAtObservation: - the id of the dimension to iterate a each of MatrixObservation over

Returns: MatrixSeriesGroup

Example

To create @MatrixSeriesGroup with @MatrixSeries that iterate @MatrixObservation over time:

var seriesGroup = matrixDataSet.craeteSeries("TIME_PERIOD");

filterObs(JSONObject obsQuery)

Returns a flat Array of all the MatrixObservation which match the query parameters. The query must be a JSONObject which contains one or more dimension id to dimension code id pairs. A single dimension can not contain more then one code id filter in the query.

Method Parameters

  • obsQuery:JSONObject - - A JSON Object of dimension values for example

Returns: Array<MatrixObservation>

Example

matrixDataSet.filterObs({ "FREQ":"A", "REF_AREA":"UK" })

getDataEndDate()

Returns the latest observation date for this dataset

Returns: Date


getDataStartDate()

Returns the earliest observation date for this dataset

Returns: Date


getDatasetTitle()

Returns the title of the dataset, this is the name of the corresponding MatrixTopic

Returns: String


getDimension(String dimId)

Returns the MatrixDataSetComponent with the given id, or null if no MatrixDataSetComponent exist with the given id

Method Parameters

  • dimId:String -

Returns: MatrixDataSetComponent


getDimensionId(Integer dimIdx)

Returns the MatrixDataSetComponent id for the given array index as it appears in the getDimensionIds method (zero indexed).

Method Parameters

  • dimIdx:Integer -

Returns: String


getDimensionIds()

Return the MatrixDataSetComponent ids in a String array in the same order that the dimensions appear in the getDimensions method

Returns: Array


getDimensionIndex(String dimId)

Return the dimension index in the getDimenisons array from the given id

Method Parameters

  • dimId:String - the dimension id, e.g FREQ

Returns: s Integer zero indexed, -1 is returned if it does not exist


getDimensionSize(String dimId)

Returns number of available MatrixDataSetCode for the MatrixDataSetComponent with the given id. The number of MatrixDataSetCode is in the context of the on the data contained in the dataset.

Method Parameters

  • dimId:String -

Returns: Integer the number of available MatrixDataSetCode for the MatrixDataSetComponent


getDimensionSizes()

Returns the number of distinct codes for each MatrixDataSetComponent, in the same order that the dimensions are provided in the getDimenisonIds method

Returns: Array


getDimensions()

Returns an array of MatrixDataSetComponent contained in this dataset

Returns: Array<MatrixDataSetComponent>


getMetadata()

Returns an array of ReferenceMetadataLink objects for which additional ReferenceMetadata can be obtained about this dataset via the MetadataManager class

Returns: s Array<ReferenceMetadataLink>


getObs()

Returns an array of all the MatrixObservation in this dataset

Returns: s Array<MatrixObservation>


getObsAttributes()

Returns the observation attributes for this dataset. The returned array contains a definition for each attribute contained in this dataset, for example a returned attribute may be OBS_STATUS with Human lable 'Observation Status'. This attribute then defines all the coded values present in this dataset, for example 'A=Normal', 'M=Missing'.

Returns: Array<MatrixDataSetComponent>

Example


var currentObseration = dataset.getObsByShortCode("A:UK:FR:T001");
var allAttributes = dataset.getObsAttributes();
for(var i=0; i < allAttributes.length(); i++) {
var attr = allAttributes[i];
var attrLable = attr.getName();                       //Returns name, for example 'Observation Status'
var reportedValue = currentObseration.getAttributeById(attr.getId());     //Returnst the Attribute reported for the Observation
var reportedValueLable = reportedValue.getName()l;    //Returns name, for example 'Estimate'
}

getObsByShortCode(String shortCode)

Returns a MatrixObservation with the given MatrixObservation.getShortCode

NOTE: In the case that there are multiple occurrences of this observation due to revisions, the latest MatrixObservation is returned, and it will include all revised MatrixObservation

Method Parameters

  • shortCode:String - Observation Short Code

Returns: MatrixObservation


getObsByUid(String uid)

Returns a MatrixObservation with the given UID

Method Parameters

  • uid:String - Observation UID

Returns: MatrixObservation


getRequestURI()

Returns the data query URI that was used to retrieve this dataset, for example: "/data/WB,WDI_ECON_POL_DEBT,1.0/.BN_KLT_DINV_CD."

Returns: String


getUid()

Returns a unique identifier for this dataset. The unique identifier will uniquely identify this dataset in the system, and will be represented as a String which conforms to the HTML specification for Id Type.

Returns: String


hasData()

Returns true if there are observations in this dataset, or false if the dataset is empty (no data).

Returns: Boolean


hasMetadata()

Returns true if there are ReferenceMetadataLink attached to this dataset

Returns: Boolean


hasObs()

Returns true if the dataset has one or more observations

Returns: s Boolean

MatrixDataSetCode

A MatrixDataSetCode defines a single dimension value for a given MatrixObservation.

The MatrixObservation contains a MatrixDataSetCode for each Dimension and thus in combination they constitute the unique key for the MatrixObservation.

A MatrixDataSetCode directly relates to a MatrixCode, the only difference being that a MatrixDataSetCode is used in the context of a MatrixDataSet and is not hierarchical, a MatrixCode is used in the context of a MatrixTopic can be used in a hierarchy, and has selection state

Constructor Parameters

  • json: -

getEndPeriod()

If this code is defining a date, this method will return the start of the period in the format YYYY-MM-DDTHH:mm:ss

Returns: String

Example

2002-12-31T23:59:59

getId()

Returns the identifier for this code, this will match the id of the corresponding MatrixCode for example 'AR'

Returns: String


getName()

Returns the human readable name for this code, for example 'Argentina'

Returns: String


getParentComponent()

Returns the MatrixDataSetComponent that owns this code

Returns: MatrixDataSetComponent


getStartPeriod()

If this code is defining a date, this method will return the start of the period in the format YYYY-MM-DDTHH:mm:ss

Returns: String

Example

2010-01-01T00:00:00

isDate()

Returns true if this code is defining a date, in which case the getStartPeriod and getEndPeriod methods will return a value

Returns: Boolean

MatrixDataSetComponent

Describes a Dimension in the context of a specific MatrixDataSet constructor

Constructor Parameters

  • json: -

getCodeById(String codeId)

Returns the MatrixDataSetCode by id or null if none exist with the given id

Method Parameters

  • codeId:String - the id of the code which should be returned

Returns: MatrixDataSetCode


getCodes()

Returns the an array of MatrixDataSetCode which contain data for this dimension in the corresponding MatrixDataSet

Returns: Array<MatrixDataSetCode>


getId()

Returns the id for this dimension, this will match the id of the corresponding MatrixDimension id, for example 'FREQ'

Returns: String


getName()

Returns the human readable name for this dimension, for example 'Frequency'

Returns: String


getSize()

Returns the number of unique MatrixDataSetCode for this dimenison as contained in the corresponding MatrixDataSet

Returns: String

MatrixObservation

Represents a single Observation belonging to a MatrixDataSet.

If there were previous versions of this observation also known as Vinatages/Revisions then this Observation will also link to the previous versions

constructor

Constructor Parameters

  • obsKey:String - e.g. "0:0:0:0:0"
  • obsValue:Array - e.g ["105.73" null, 0, null, null, 0, null]
  • matrixDataSet:Integer -
  • datasetIdx: -
  • annotations: -

getAttributeValueById()

Returns the attribute as a MatrixDataSetCode with the given attribute id.

Returns: MatrixDataSetCode

Example

var attr = matrixObs.getAttributeValueById('OBS_STATUS');
var codeId = attr.getId();       //Returns a code value for OBS_STATUS e.g A
var codeName = attr.getName();   //Returns the code name e.g Normal

getAttributes()

Returns the attribute values for this observation, as an array of MatrixDataSetCode

Returns: Array<MatrixDataSetCode>


getDimensionValueByDimId(String dimId)

Returns the observation dimension value as a MatrixDataSetCode for the given dimension id. Returns null if no such observation value exists

Method Parameters

Returns: MatrixDataSetCode

Example

var dimCode = matrixObs.getDimensionValueByDimId('FREQ');
var codeId = dimCode.getId();       //Returns a code value for FREQ e.g A
var codeName = dimCode.getName();   //Returns the code name e.g Annual

getDimensionValueByDimIdx(String dimId)

Returns the observation dimension value as a MatrixDataSetCode for the given dimension index. The dimension index refers to the position of the MatrixDataSetComponent as defined by the MatrixDataSet.getDimensions method.

Method Parameters

  • dimId:String -

Returns: MatrixDataSetCode

Example

var dimCode = matrixObs.getDimensionValueByDimIdx(0);
var dimId = dimCode.getId();       //Returns a code value for FREQ e.g A
var dimValue = dimCode.getName();  //Returns the code name e.g Annual

getMatrixDataSet()

Returns the MatrixDataSet that owns this observation. This will contain information such as the dimensions and attributes contained in the dataset.

Returns: MatrixDataSet


getMetadata()

Returns an array of ReferenceMetadataLink objects

Returns: s Array

See: @see ReferenceMetadataLink.js


getObsValue()

Returns the observation value

Returns: String


getRevisions()

Returns all the revisions for this observation. If there are no revisions, or if this observation is itself a revision then this will return null

Returns: Array


getShortCode()

Returns a short code for this MatrixObservation. The short code is a colon separated string of coded dimension values in the order that the dimensions are specified in the Data Structure Definition (DSD).

NOTE: The short code for any revisions to this observation will also be the same, whereas the getUid will always return a unique identifier

Returns: String

Example

A:UK:FR:INFL:2008

getUid()

Returns a unique identifier for this MatrixObservation. The unique identifier will uniquely identify this observation in the MatrixDataSet.

The UID for an observation is a concatenation of the getShortCode and the dataset index, as the MatrixDataSet may contain revised observations.

Returns: String this will conform to the HTML specification for Id Type and can therefore be used as an element id.


getValidFrom()

Returns the valid from date for this observation. This does not refer to the observation date, but instead the date that the observation was published.

Returns: Date


hasMetadata()

Returns true if there are ReferenceMetadataLinks attached to this object

Returns: s Boolean

See: @see ReferenceMetadataLink.js


hasRevisions()

Returns true if the observation has revisions, i.e there were previous observations reported which were subsequently updated by this observation

Returns: Boolean


isDelete()

Returns true if this is an observation that was deleted. This will only occur if the data query request included revisions

Returns: Boolean

MatrixSeries

A MatrixSeries groups together MatrixObservation which have the same MatrixDimension values, with the exception of the dimension that is being iterated over. For example if the dimension that is being iterated over is TIME_PERIOD then all the MAtrixObservations in this MatrixSeries will differ only by the observation time.

A MatrixSeries should be obtained via the MatrixDataSet.createSeries method.


getDimensionValue(String dimId)

Returns the MatrixDataSetCode which contains the reported value for the given dimension id. If the dimId is the same as the getDimensionAtObs value, then this wil return null, as this dimenison value is not fixed for the entire series.

Method Parameters

  • dimId:String -

Returns: MatrixDataSetCode


getMatrixDataSet()

Returns the MatrixDataSet which was used to build this series grouping.

Returns: MatrixDataSet


getObservation( dimIdVal)

Returns the MatrixObservation where the reported value for the dimenison at observation matches the obsId

Method Parameters

  • dimIdVal: - the reported value of the dimension at observation to return the observation for

Returns: MatrixObservation or null if there is no match

Example

var obs = matrixSeries.getObservationByReportedDimId("2002); //returns the MatrixObservation for 2002 from a time series MatrixSeries

getObservations()

Returns an Array of MatrixObservation for this series

Returns: Array<MatrixObservation>


getSeriesAttributeById()

Returns the reported series level attribute as a MatrixDataSetCode with the given attributeId, or returns null if there is no attribute with the given id

Returns: MatrixDataSetCode


getSeriesAttributes()

Returns the reported attributes which are the same for each MatrixObservation that belongs to this MatrixSeries. The returned attributes are returned as an array of MatrixDataSetCode - which contain both the code id, and name, and links back to the parent component.

Returns: Array<MatrixDataSetCode>


getSeriesGroup()

Returns the MatrixSeriesGroup to which this series belongs

Returns: MatrixSeriesGroup


getShortCode()

/** Returns the series key as a String with colon separators between the dimension values, for example

 A:UK:FR:IVGH 

Returns: String


sortObs()

Sort observations according to the function, can use sortFunctionAsc or sortFunctionDesc or custom sort function

MatrixSeriesGroup

A MatrixSeriesGroup is a container for MatrixSeries and contains information about the grouping, such as the observation at dimenison, the unique observation concept values, as well as links back to the MatrixDataSet


getDimensionAtObs()

Returns id of the dimension at the observation level. This is the dimenison the the observations are iterating over. For example the return value would be TIME_PERIOD if the observations were iterating over time.

Returns: String


getMatrixDataSet()

Returns the MatrixDataSet which was used to build this series grouping.

Returns: MatrixDataSet


getSeries()

Returns the MatrixSeries that are members of this group

Returns: Array<MatrixSeries>


getSortFunctionAsc()

Returns a sort function to sort the observations in ascending order based on the observation concept value (e.g 2002, 2003, 2004)

Returns: Function this can be passed to the sortObs method


getUniqueConcepts()

Returns an Array of unique concept Ids for this group, in ascending order. For example if the Dimension at observation is TIME_PERIOD this method may return something like 2002, 2003, 2004, 2005 if the Dimension at observation is REF_AREA the return array may look like DE, FR,UK, US

Returns: Array


sortFunctionDesc()

Returns a sort function to sort the observations in descending order based on the observation concept value (e.g 2004, 2003, 2002)

Returns: Function this can be passed to the sortObs method


sortObs( sortFunction)

Sort observations for each series according to the sort function

Method Parameters

Example

matrixSeriesGroup.sortObs(matrixSeriesGroup.getSortFunctionAsc());


ReferenceMetadata

ReferenceMetadata contains additional information about a particular structure or data point, including

Note: ReferenceMetadata should be obtained via the MatrixMetadataManager

Constructor Parameters

  • json:JsonObject - as obtained from the MatrixWS

getAttributes()

Returns an array of ReferenceMetadataAttribute which contain the metadata text for this report.

Returns: s Array<ReferenceMetadataAttribute>


getId()

Returns the unique identifier for this ReferenceMetadata

Returns: String


getName( lang)

Returns the name of this ReferenceMetadata

Method Parameters

  • lang: - - optional. If not provided then it will use the default language as defined by the MatrixManager. If no text is available in the default language, then the first text occurrence will be returned

Returns: String


getSupportedLanguages()

Returns the supported languages for this Reference Metadata. This will return an array of Strings.

Returns: s Array


getTarget()

Returns the ReferenceMetadataTarget which references the structure that this ReferenceMetadata is attached to.

Returns: ReferenceMetadataTarget

ReferenceMetadataAttribute

A ReferenceMetadataAttribute contains the Metadata Text, which can be HTML markup constructor

Constructor Parameters

  • json: -

getAttributes()

Returns an array of child ReferenceMetadataAttribute

Returns: Array


getCodeId()

If the text from this metadata attribute comes from a Codelist, this returns the Code Id of the code

Returns: Boolean


getId()

Returns the id of the metadata attribute

Returns: String


getLevel()

Returns the depth of this item in the hierarchy, starting from 1

Returns: Integer


getName()

Returns the name of the attribute

Returns: String


getSupportedLanguages()

Returns the supported languages on this Reference Metadata Attribute. This will return an array of Strings, or null if isMultilingual is false.

Returns: s Array


getText( lang)

Returns the text for this attribute, which may contain HTML markup. If this is a presentational attribute, then this will return null, but there will be child ReferenceMetadataAttribute

Method Parameters

  • lang: - - optional, and only relevant if isMultilingual returns true. If not provided then it will use the default language as defined by the MatrixManager. If no text is available in the default language, then the first text occurrence will be returned

Returns: String


hasChildren()

Returns true if this ReferenceMetadataAttribute has child ReferenceMetadataAttribute

Returns: Boolean


isCoded()

Returns true if the text for this Reference Metadata Attribute is coded

Returns: Boolean


isMultilingual()

Returns true if the text for this Reference Metadata Attribute is bound to a specific language, and in addition there may be different representations in different languages.

Returns: Boolean


isPresentational()

Returns true if there is no text for this ReferenceMetadataAttribute but there are child ReferenceMetadataAttribute which do contain text. If this is the case, then this ReferenceMetadataAttribute is present for presentational reasons only, e.g this ReferenceMetadataAttribute may have a name of 'Address' and child ReferenceMetadataAttribute may contain 'Street Name', 'County', 'Post/Zip Code' etc.

Returns: Boolean

ReferenceMetadataTarget

A ReferenceMetadataTarget describes which structure the ReferenceMetadata links to. This is achieved by targeting a specific structure using the SdmxUrn to identify the structure.

It is possible to link ReferenceMetadata to most structure types, including observations. It is also possible to link ReferenceMetadata to structures in the context of a dataset, or with no context. For example ReferenceMetadata can link to a Code such as 'France' for all MatrixTopic (no context). It is also possible to link ReferenceMetadata to a Code in the context of the MatrixTopic If the latter is the case, then the target URN is to the MatrixTopic and the getDataKey method of this object will link to the MatrixCode in the context of the MatrixDimension


getDataKey()

The DataKey is used to link the metadata to either a code or concept in the context of a MatrixTopic or it can be used to link to a specific MatrixObservation

Returns a JSON Array of Key value pairs, where the key is the MatrixDimension Id and the value is the MatrixCode Id.

Returns: JSON Object

Example


Partial Key
{
FREQ : "A"
}


Full Key
{
FREQ : "A",
REF_AREA : "UK",
SERIES : "ABC",
TIME_PERIOD : "2008"
}

getTargetUrn()

Returns the SdmxUrn which references the structure that this reference metadata attaches to. Note that if this metadata attaches to a specific part of a dataset, for example a code in the context of a dimension, or an observation, then the target urn will be the URN of the MatrixTopic.

Returns: SdmxUrn


hasDataKey()

Returns true if the this reference metadata is attached to a full or partial series key. This is the case if the metadata attaches to a specific MatrixObservation (full key) or a MatrixCode or MatrixDimension in the context of a MatrixTopic (partial key).

If this returns true, then getDataKey will have a non-null response

Returns: Boolean



MatrixCategory

A MatrixCategory is a hierarchical structure which represents a SDMX Category in a Category Scheme, and may additionally contain one or more MatrixTopicDefinition which contains information about an available dataset (in SDMX this is a Dataflow)

A MatrixCategory also contain information about the total number of available series, by combining the number of series for each linked MatrixTopicDefinition, and includes the total count from any child MatrixCategory

Note: This Object should not be constructed directly, it should be obtained via the MatrixStructureBrowser object

Constructor Parameters

  • json:JsonObject - from MatrixWs
  • parent:MatrixCategory -
  • position:Integer - position in hierarchy starting with 1

getChildren()

Returns an array of child MatrixCategory if there are any, otherwise this will return an empty array

Returns: Array<MatrixCategory>


getDescription()

Returns the description for this MatrixCategory, or null if there is no description

Returns: String


getLevel()

Returns the depth in the hierarchy, starting from 1

Returns: s Integer


getName()

Returns the name for this MatrixCategory

Returns: String


getParent()

Returns the parent MatrixCategory if there is one, null if not

Returns: MatrixCategory


getSdmxUrn()

Returns the SdmxUrn for this MatrixCategory

Returns: SdmxUrn


getSeriesCount()

Returns a count of series that are available for this MatrixCategory, and all child MatrixCategories

Returns: Integer


getStructureType()

Returns a String representation of this structure type

Returns: String in this case Category


getTopics( includeChildCategories)

Returns an array of MatrixTopicDefinition for this MatrixCategory, and if includeChildCategories is true then the array will include MatrixTopicDefinition for the child MatrixCategory as well

Method Parameters

Returns: Array<MatrixTopicDefinition>


getUid()

Returns a unique identifier for this structure. The unique identifier will uniquely identify this structure in the system.

Returns: String this will conform to the HTML specification for Id Type and can therefore be used as an element id.


hasChildren()

Returns true if this has any child MatrixCategories

Returns: Boolean


hasParent()

Returns true if this MatrixCategory has a parent MatrixCategory

Returns: Boolean

MatrixCode

A MatrixCode is similar to an Sdmx Code in that it contains an id/name pair, however the MatrixCode can be hierarchical, where the hierarchy may contain codes from multiple SDMX Codelists.

A MatrixCode is also linked to the MatrixDimension that owns it, and it therefore contains information about whether it's role in the MatrixDimension is just as a display only node in the hierarchy. This is the case when there is no data available for the MatrixCode, but it contains child MatrixCodes which do have data. An example is a code 'Europe' which contains a child MatrixCode for each European country. A User Interface could display the label Europe with child checkbox selects for each country.

A MatrixCode is also stateful in the context of the currently data query the user has constructed, each time a MatrixCode is added or removed to the data query, through the MatrixDataBrowser.addCodeSelection and MatrixDataBrowser.removeCodeSelection methods the data query is updated. When the MatrixDataBrowser.queryConstraints is called, each MatrixCode has its state updated as to whether it remains a valid code selection based on the current query. An invalid MatrixCode is one which would result in no data being returned if it was added to the current data query - this information is obtained via the isConstrained method

A MatrixCode also contains information about linked ReferenceMetadata via the hasMetadata method and getMetadata method. The additional ReferenceMetadata may be linked to the code generally (e.g. all occurrences of 'France') or it may be a more specific link, e.g. all occurrences of France in the context of the Reporting Country dimension for the Population Topic

Note: This Object should not be constructed directly, it is created on obtaining a MatrixDataBrowser, and can be obtained via theMatrixDimension to which it belongs

constructor

Constructor Parameters

  • json: -
  • parent: -
  • position: -

getChildren()

Returns an array of child MatrixCodes or an empty array if there are none

Returns: Array<MatrixCode>


getId()

Returns the Code Id

Returns: String


getLevel()

Returns the depth of this item in the hierarchy, starting from 1

Returns: Integer


getMetadata()

Returns an array of ReferenceMetadataLink, or an empty array if there are none

Returns: {Array<ReferenceMetadataLink}


getName()

Returns the name fo this MatrixCode

Returns: String


getParent()

Returns the parent MatrixCode or null if there is no parent

Returns: MatrixCode


getParentDimension()

Returns the MatrixDimension that this MatrixCode belongs to

Returns: MatrixDimension


getStructureType()

Returns a String representation of this structure type

Returns: String in this case "Code"


getUid()

Returns a unique identifier for this structure. The unique identifier will uniquely identify this structure in the system

Returns: String this will conform to the HTML specification for Id Type and can therefore be used as an element id.


hasChildren()

Returns true if this MatrixCode has children

Returns: Boolean


hasMetadata()

Returns true if there are one or more ReferenceMetadataLink attached to this MatrixCode

Returns: Boolean


hasParent()

Returns true if this MatrixCode has a parent MatrixCode

Returns: Boolean


isConstrained()

Returns true if this MatrixCode is constrained. A constrained code is one which will return no data if selected based on the current selection state of other codes in all the dimensions. This value can change as code selection state changes. This information is provided to prevent a user creating a query which will result in no data being returned

Returns: Boolean


isDisplayOnly()

Returns true if this MatrixCode is display only, if it is display only then it will be a MatrixCode which has no data available for it and should therefore not be used in a data query. It will however have child MatrixCode(s) which do have data, so it can be used to build a hierarchy in the UI

Returns: Boolean


isSelected()

Returns true if this MatrixCode has been selected in the current data query

Returns: Boolean

MatrixDimension

A MatrixDimension is one of the dimensions that makes up a MatrixTopic, and represents a dimension as described by the SDMX Data Structure Definition.

A MatrixDimension contains one or more MatrixCode which either there is data for on the server, or the MatrixCode has child MatrixCode which contain data.

Note: This Object should not be constructed directly, it is created on obtaining a MatrixDataBrowser, and can be obtained via the MatrixTopic to which it belongs

constructor

Constructor Parameters

  • matrixManager: -
  • json: -
  • jsonCodes: -

deregister()

De-registers this item from the MatrixManager and MatrixMetadataManager


getAvailableCodes()

Returns the MatrixCode which are not constrained for this MatrixDimension.

Returns: Integer


getCodeById(String codeId)

Returns the MatrixCode with the given id, this will not return display only codes. Returns null if no such code exists

Method Parameters

  • codeId:String - this is the code id, not the internal id

Returns: MatrixCode


getCodeCount()

Returns the number of MatrixCode for this MatrixDimension. This count only returns a count of codes that have data available for them, and therefore does not include display only codes

Returns: Integer


getCodes()

Returns an array of MatrixCode objects for this MatrixDimension

Returns: Array<MatrixCode>


getFlatCodes()

Returns an flat array of MatrixCode for this MatrixDimension, this collapses the MatrixCode hierarchy and does not include display only codes

Returns: Array<MatrixCode>


getId()

Returns the id of this MatrixDimension, the id will be unique in respect to the MatrixTopic that owns this dimension

Returns: String


getMetadata()

Returns an array of ReferenceMetadataLink objects

Returns: Array<ReferenceMetadataLink>


getName()

Returns the name of this MatrixDimension

Returns: String


getSelectedCodes( includeConstrained)

Returns the selected MatrixCode for this MatrixDimension.

Method Parameters

  • includeConstrained: - if true this will also include codes which have become unavailable due to constraints

Returns: Integer


getStructureType()

Returns a String representation of this structure type

Returns: s String in this case "Dimension"


getTopic()

Returns MatrixTopic that owns this dimension

Returns: MatrixTopic


getUid()

Returns a unique identifier for this structure. The unique identifier will uniquely identify this structure in the system.

Returns: String this will conform to the HTML specification for Id Type and can therefore be used as an element id.


hasMetadata()

Returns true if there are ReferenceMetadataLink attached to this object

Returns: Boolean

MatrixPPQ

Defines a pre-packaged query which has either been stored on the Fusion Matrix Server (as a Global query) or as a browser cookie on the user's local machine (as a Local query).

The MatrixPPQ defines a name, and description. The URL is not an absolute URL, instead it contains the contents of the $MTX section of the URL (which appears after the # section in the URL). The $MTX section encodes the following information:

Parameter Description Example
tp

The selected Topic Id. (mandatory)

This is read by the MatrixManager.getMatrixDataBrowser when no topicId is passed to the method

tp=ESTAT:HC01(2.0)
dq

The Data Query conforming to the SDMX RESTful syntax. (mandatory)

This value is read on construction of the MatrixDataBrowser to set the initial state

dq=BE+BG.F..TOTAL....TOTAL.A?lastNObservations=12
pv

The Pivot Table State (optional)

If a Pivot Table is used to display the data, then it stores its state in this section of the URL. The state includes which dimensions are on the header, which are on the rows, and which values are stored in the cross section. The PivotTable will automatically rebuild its state on construction based on this part of the URL.

pv=5,4~2~9:2011,8:A,7:TOTAL,6:TOTAL,3:TOTAL,1:F,0:BG

When the MatrixPPQManager is used to store or publish a Pre-Packaged query, it will store the $MTX part of the URL, so for example the page:

http://demo.metadatatechnology.com/FusionMatrix/data.html#$MTX[tp=ESTAT:HC01(2.0);dq=BE+BG.F..TOTAL....TOTAL.A?lastNObservations=12;pv=5,4~2~9:2011,8:A,7:TOTAL,6:TOTAL,3:TOTAL,1:F,0:BG]

Is stored as: tp=ESTAT:HC01(2.0);dq=BE+BG.F..TOTAL....TOTAL.A?lastNObservations=12;pv=5,4~2~9:2011,8:A,7:TOTAL,6:TOTAL,3:TOTAL,1:F,0:BG

When a MatrixPPQ is loaded, it loads this URL into the $MTX part of the URL for processing. However, it is up to the implementation of the JavaScript on the page to build the required components based on this URL. The basic rule of thumb is:

  1. If there is a tp, then use the MatrixManager.getDataBrowser method which will automatically load the correct topic
  2. If there is a dq, then the data browser state this will be prefilled when the correct selections
  3. If there is a pv, then the PivotTable will automatically set its state on construction
  4. Any other values in this part of the URL will have come from custom components outside of the MatrixJS framework
The URLManager acquired from MatrixManager.getUrlManager can be used to determine if any of the above values exist.


getDataSet( callbackFunction)

Executes this Pre-Packaged Query and returns the resulting MatrixDataSet to the callback function. Note, only the data query information is used to generate the MatrixDataSet any display specific infomration on this pre-packaged query will not be used.

Method Parameters

  • callbackFunction: - this function is expected to take one parameter, the MatrixDataSet

getDescription()

Returns the description of this Pre-Packaged Query

Returns: String


getFlowURN()

Returns the Dataflow URN for this Pre-Packaged Query

Returns: String


getId()

Returns the unique id for this Pre-Packaged Query

Returns: String


getName()

Returns the name of this Pre-Packaged Query

Returns: String


getUrl()

Returns the URL to execute the Pre-Packaged Query

Returns: String


loadURL()

Loads the $MTX options into the page pram redirect|String (optional) if supplied then the browser will be redirected to the following page, and have the postfixed $MTX options

Returns: String

MatrixTopic

Defines a data Topic for which data can be queried. In SDMX this relates directly to the Dataflow. The purpose of the MatrixTopic is to enable User Interface construction which provides the user with the means to make a data query selection. The MatrixDataBrowser should be used in conjuntion with the MatrixTopic to add/remove codes for selection, and query data.

The MatrixTopic differs from contains information about the data structure in terms of its dimensionality by providing access to the MatrixDimension, and the data available for this MatrixTopic (series count, data start and end dates, each MatrixDimension only contains codes if there is data available for them).

A MatrixTopic may additionally have Pre-Packaged Queries defined (MatrixPPQ). The MatrixTopic, and its sub-structures may also have additional reference metadata links (ReferenceMetadataLink)

Note: This Object should not be constructed directly, it should be obtained via the MatrixDataBrowser object


addCodeConstraintStateChangeListener(Function listener)

Adds a listener to the state change of a code. The listener will be called as the code is set to constrained, or unconstrained

Method Parameters

  • listener:Function - this is expected to be a function which takes a single argument, the MatrixCode for whose state has changed

addCodeSelectionStateChangeListener(Function listener)

Adds a listener to the state change of a code. The listener will be called as the code is selected, or unselected

Method Parameters

  • listener:Function - this is expected to be a function which takes a single argument, the MatrixCode for whose state has changed

deregister()

De-registers this item from the MatrixManager and MatrixMetadataManager


getAgency()

Returns the agency for this topic

Returns: null


getDataEnd()

Returns the end date for this MatrixTopic

Returns: Date


getDataStart()

Returns the data start date for this MatrixTopic

Returns: Date


getDimensionById()

Returns the MatrixDimension with the given id, or null if none exist with the id

Returns: MatrixDimension


getDimensions()

Returns an array of MatrixDimension objects for this MatrixTopic the order of MatrixDimension will reflect the same order as defined by the underlying SDMX Data Structure Definition (DSD)

Returns: Array<MatrixDimension>


getMetadata()

Returns an array of ReferenceMetadataLink objects

Returns: Array<ReferenceMetadataLink>


getName()

Returns the name of this MatrixTopic (this is the name of the SDMX Dataflow that this MatrixTopic represents)

Returns: String


getPrePackagedQueries()

Returns an array of Pre-Packaged Queries or an empty array if none exists

Returns: Array<MatrixPPQ>


getSdmxUrn()

Returns the SDMX URN of the Underlying SDMX Dataflow that this MatrixTopic represents

Returns: SdmxUrn


getStructureType()

Returns a String representation of this structure type

Returns: String "Topic"


getUid()

Returns a unique identifier for this structure. The unique identifier will uniquely identify this structure in the system.

Returns: String this will conform to the HTML specification for Id Type and can therefore be used as an element id.


hasMetadata()

Returns true if there are ReferenceMetadataLink attached to this object

Returns: Boolean

MatrixTopicDefinition

Describes high level information about a MatrixTopic. This MatrixTopicDefinition can be used to retireve the full MatrixTopic via the MatrixManager object.

Note: This Object should not be constructed directly, it is owned by a MatrixCategory and can also be obtained directly from the MatrixStructureBrowser


getDataEnd()

Returns the data end date for the MatrixTopic

Returns: Date


getDataStart()

Returns the data start date for the MatrixTopic

Returns: Date


getDescription()

Returns the description of the MatrixTopic that this MatrixTopicDefinition references, or null if there is no description

Returns: String


getDimensions()

Returns a String array of dimension names for this topic in the sequence that the dimensions are defined

Returns: Array


getDsdDescription()

Returns the description of the underlying SDMX Data Structure Definition to which the MatrixTopic underlying SDMX Dataflow references Returns null if there is no description

Returns: String


getDsdName()

Returns the name of the underlying SDMX Data Structure Definition (DSD) to which the MatrixTopic underlying SDMX Dataflow references

Returns: String


getDsdURN()

Returns the SdmxUrn of the underlying SDMX Data Structure Definition (DSD) to which the MatrixTopic underlying SDMX Dataflow references

Returns: SdmxUrn


getId()

Returns the id of the MatrixTopic that this MatrixTopicDefinition references, or null if there is no description

Returns: String


getName()

Returns the name of the MatrixTopic that this MatrixTopicDefinition references

Returns: String


getPrePackagedQueries()

Returns an array of Pre-Packaged Queries (MatrixPPQ) that are associated with the MatrixTopic that this definition references. Returns an empty array if no Pre-Packaged Queries are defined

Returns: Array<MatrixPPQ>


getSdmxUrn()

Returns the SdmxUrn of the MatrixTopic that this MatrixTopicDefinition references (which matches the underlying is the Dataflow URN)

Returns: SdmxUrn


getSeriesCount()

Returns the number of series that are available for the MatrixTopic

Returns: Integer

ReferenceMetadataLink

Links to additional ReferenceMetadata with the unique id.

ReferenceMetadata should be retrieved via the MatrixMetadataManager class


Returns the Id of the ReferenceMetadata.

Returns: String


Returns the title of the ReferenceMetadata

Returns: String

SdmxUrn

Parses a URN into it's parts

Example

urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=ACY:DF_MYFLOW(1.0)
=agency id:ACY
=id:DF_MYFLOW
=version:1.0

urn:sdmx:org.sdmx.infomodel.categoryscheme.Category=ESTAT:ESTAT_DATAFLOWS_SCHEME(1.0).Census.1.11
=agency id:ESTAT
=id:ESTAT_DATAFLOWS_SCHEME
=version:1.0
=identifiable id=Census.1.11

getAgencyId()

Returns the Agency Id that this URN contains

Returns: {String}


getId()

Returns the Maintainable Id that this URN contains

Returns: {String}


getIdentifiableId()

Returns the Identifiable Id that this URN contains

Returns: {String}


getStructureType()

Returns the structure type that this URN is referencing

Returns: {String}


getUrn()

Returns the full URN as a String

Returns: {String}


getVersion()

Returns the Maintainable version that this URN contains

Returns: {String}



MatrixUtil

Utility Functions


addItemToSelectList( listId, value, label)

Method Parameters

  • listId: -
  • value: -
  • label: -

arrayContains(Array arr,Object obj)

Returns true if the provided array contains the supplied objet

Method Parameters

  • arr:Array -
  • obj:Object -

removeAllOptions( listId)

Method Parameters

  • listId: -




MatrixCodePicker

Creates an HTML checkbox tree code picker for each MatrixDimension contained by the MatrixTopic that the supplied MatrixDataBrowser is browsing data for.

Each HTML checkbox tree is appended to a div whose id must be formatted as follows:

'MATRIX_CHBX_{DIM ID}' for example MATRIX_CHBX_REF_AREA

Add a listeners for checkbox selection and deselection and will add/remove code selections to the MatrixDataBrowser as the user selects and deselects codes. The MatrixDataBrowser.queryConstraints method will be invoked each time code selections are changed and checkboxes will be enabled or disabled accordingly based on which codes are valid or invalid.

Constructor Parameters

  • matrixDataBrowser: - - Used to register code selections / deselections and to obtain and update available selections based on current selection state
  • codeSelectCallbackFunction: - - Called after a code has been selected / deselected
  • metadataCallbackFunction: - - Adds a listener onto metadata 'info' icons and will obtain metadata when the icon is clicked, calling the callback function with an array of ReferenceMetadata
  • isEditEnabled: - if true then add/edit metadata icons will be present where required

Example




Europe
United Kingdom France
Africa
South Africa Egypt


PivotTable

Creates a pivot table based on the contents of the MatrixDataSet, the pivot table is appended to the HTML element with the id supplied on construction.

Click listeners are added to observation cells, and metadata points

Constructor Parameters

  • matrixDataSet: - - the dataset to create the table for
  • elId: - - the HTML element to append the HTML Pivot table to
  • metadataManager: - - used to obtain metadata when the user clicks on a metadata info icon
  • selectObsCallbackFunction: - - (optional) this function is called with the MatrixObservation when the user clicks an observation cell in the table
  • metadataCallbackFunction: - - (optional) this function is called with an Array of ReferenceMetadata when the user clicks on a Metadata Info Icon

Example

Series Foreign direct investment, net (BoP, current US$) Foreign direct investment, net inflows (% of GDP)
Time period
2005 -7018840838.65452 -3.53555041198946
2006 -5806153739.85575 4.19503311948951

setHeight(Integer px)

Sets the height of the pivot table in pixels

Method Parameters

  • px:Integer -

setWidth(Integer px)

Sets the width of the pivot table in pixels

Method Parameters

  • px:Integer -

updateTable(MatrixDataSet matrixDataSet)

Rebuilds this exiting pivot table with the contents of the new MatrixDataSet. The MatrixDataSet must be for the same MatrixTopic that was used on initial construction of this PivotTable.

Method Parameters