This article is a follow-up to the first API tutorial, it showcases a series of bite-sized examples to highlight important features of the AskiaVista API.
All examples are open source and can be downloaded/forked from the associated GitHub repository.
In this very first example, we'll be displaying a simple cross-tabulation by using the method getPages from the AskiaVista API.
The bare minimum needed to achieve this is featured in the source code:
- Including the jQuery library is a pre-requisite
- Including the askiavista.js is a pre-requisite
- Using askiaVista.config
- This is required so that your web page knows how to locate your Vista server, thanks to the baseUrl parameter
- In this example, I have chosen to use an authenticityToken to register to the API. Tokens can be created via the Vista Web Interface. This token can be passed directly in the source code (like in this example), or via the URL in an askiaAuth parameter.
- Using askiaVista.getPages
- This function is used to make a simple cross-tabulation. We use the Analysis syntax rows and columns to identify which variables should appear in the rows and columns of the resulting crosstab.
- containerID is a reference to the ID of the HTML element in which the table will be shown.
Using an extra library to authenticate : jquery.blockUI.js
Whenever the user needs to login (first access to the page, or after a session has expired for example), the library will be used to prompt a login screen to the user. This is mapped to the Vista logins. If the user inputs a correct login, but that the login is not allowed to view the result, the user will not see the result.
In this example, the authenticityToken was removed, replaced by a reference to the blockUI (in the Resources tab). You can use DEMOEN/DEMOEN as credentials to log in to this example.
The best way to authenticate is to do it yourself, right? Well you will need to use the showLoginForm parameter in askiaVista.config then. This function will trigger just like the "BlockUI", ie. whenever authentication is required.
In this example, I'm showing an extra HTML div called loginbox, which has a "login" button mapped to AskiaVista's own askiaVista.login() method.
Here is a quick demo of the askiaVista.logout() feature. Once you are authenticated, you can request tables as much as you want. On the other hand, using askiaVista.logout() will make the requester re-login before they can do a new askiaVista.getPages() query.
In this example, we're grouping a series of 4 askiaVista.getPages in a single call, using askiaVista.doTransaction. This has the effect of sending 1 large request to the server, instead of 4 smaller ones, thus improving load management on the server side.
This is a short demonstration of a couple of "getters". Using askiaVista.getQuestions allows you to retrieve a set of questions that belong to a specific survey, or profile. The success parameter defines which action you wish to conduct with the result.
In this example, I'm only displaying the captions of the retrieved questions in an HTML div for visual purposes.
These getters return data objects in a JSON format, therefore, parsing them with JSON.parse is a common way of dealing with the result.
The second function : askiaVista.getResponses is fetching all available responses of a given question. They do not show in the "Result" tab of this example because I chose to "console log" them to get a better overview of the full result. Below, a screenshot of the console to show the JSON Response object of a gender question.
This example showcases a few parameters to refine a cross-tab.
- Response selection can be achieved by using the responses parameter, followed by the list of responses to show. When this parameter is not present, all responses are displayed by default.
- Grouping can be achieved simply by using a JSON object instead of the response code.
- Settings have various levels : rows settings, columns settings and results settings. They also are defined via JSON object parameters.
In this example, we're showcasing the Replay plugin, which allows to re-execute a table and changing parameters at the same time. This is especially convenient for dynamic filtering purposes. Using askiaVista.replay() requires the tables to have an ID, which will be passed to the replay() method as a first parameter. The second parameter is the list of options to change in the replayed table. In this case I'm only changing the subPopulation option.
In this example, we're combining the feature of the Replay plugin with another commonly use plugin : Dropdown. Dropdown will create a select box with a pre-coded list of answers. It can be used in one of the getter functions (askiaVista.getQuestions for example) as a dropDown parameter. Doing so will push all questions of my specific profile into a dropdown menu.