Squiz Matrix: Using the Javascript API

I thought that since I am the one that wrote the MySource Matrix Javascript API asset, that I should probably write up a post about it, give it some background, and show some cool examples of its use.

First, the Javascript API is part of the Web Services package. This has been added to 3.22.2 as well as the 3.24.x branch. If you don't have a copy of it, visit the MySource Matrix site to download a new version of Matrix.

This asset come about because I really wanted a way to use javascript to get things like asset attributes, metadata and web paths. I was tired of always having to build asset listings and nest them just for something small. I also wanted the data returned to be in a format that we could easily use in javascript. So, I built the API to return JSON which then gets converted into a javascript object. Below, you will see how to implement the MySource Matrix Javascript API. If you have any questions about this, please post a comment.

Setting the API Key

The first step needed when setting up the Javascript API is to set the API key. This key needs to match the key that you configured on the Details screen of the Javascript API asset. A special function is called that sets the key to a global variable, which can then be used by other API functions.

setApiKey(1057909564);

Using an API function

Almost all of the API functions requires that an asset be specified as the first parameter. Please note that you can use either an asset id OR the web path to the asset. Either of these will work as the first parameter. All of the functions are different and require different pieces of data to be passed in.

Using the returned JSON

When a function from the Javascript API is used, it returns JSON. This can be easily seen when using Firebug, you can watch what the API returns as a response. But, if we want to use that response within our page, we have to utilize the custom callback that is added as the last parameter of each function.

getGeneral(1234, function(data) {
	alert(data.name);                                         
});

The following button will run the getGeneral() function for asset #1234 and return the asset name. If we want to get additional information about the asset, we can do the following:

getGeneral(1234, function(data) {
    alert('Name: '+data.name+'\n'+
        'Short name: '+data.short_name+'\n'+
        'Asset id: '+data.id+'\n'+
        'Type Code: '+data.type_code+'\n'+
        'Status: '+data.status+'\n'+
        'Created user id: '+data.created_userid+'\n'
    );                                        
});

Handling errors

If something goes wrong, the API will return an error. You can set up your callback function to account for this, and show the error if it is returned. We can use a helper function, isset() that is included with the API. This is similar to the isset function in PHP, as it checks to see if a variable in javascript has been set.

getGeneral(50000, function(data) {
    if (isset(data.error)) {
        alert(data.error);                                        
    } else {
        alert(data.name);                                         
    }
});

Conclusion

This is just the first part of my blog series on the MySource Matrix Javascript API and it really only scratches the surface. In my next post, I will show some more intermediate implementations, and how you can use the API to build things like select lists, populate fields and create assets. Stay tuned.