Overview
If you want to have more control over the loading of content, call reports or dashboards on demand, or set display options dynamically (based on user input), you can call the API directly from your own script.The Javascript API must be included before any API calls can be made:
<script src="http://localhost/JsAPI" type="text/javascript"></script>
A specific version of the API may be requested using the version
parameter:
<script src="http://localhost/JsAPI?version=2.1" type="text/javascript"></script>
If the browser is unable to load the API, any calls to load reports or dashboards will fail. If you wish to detect whether the API has loaded successfully, you should check the variable window.yellowfin
is available:
<script src="http://localhost/JsAPI" type="text/javascript"></script> <script type="text/javascript"> if (!window.yellowfin) { alert('Error loading API'); } </script>
Server Information
After loading the API, some server information is made available:Example
<script src="http://localhost/JsAPI" type="text/javascript"></script> <script type="text/javascript"> if (window.yellowfin) { alert('Yellowfin API loaded. Version: ' + yellowfin.apiVersion); } </script>
Loading a Report
A report is loaded by calling theyellowfin.loadReport
function:yellowfin.loadReport(options);
Options are passed to the function as a Javascript object. These include a report identifier for the report you are loading, the elementId of the HTML element in which to load the report (or the element itself), and other options that alter the way the report is displayed. The available options are:
Examples
This example loads a report into an element specified by its universal id, setting some initial display options:
var options = {}; options.reportUUID = 'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63'; options.elementId = 'myReport'; options.showFilters = 'false'; options.showSeries = 'false'; options.display = 'chart'; options.fitTableWidth = 'false'; yellowfin.loadReport(options);
This example does the same thing with an anonymous options object:
yellowfin.loadReport({ reportUUID: 'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63', elementId: 'myReport', showFilters: 'false', showSeries: 'false', display: 'chart', fitTableWidth: 'false' });
This example passes the element directly rather than just its id:
yellowfin.loadReport({ reportUUID: 'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63', element: document.getElementById('myReport') });
Loading Report Filters
Filters used by a report can be loaded by calling theyellowfin.reports.loadReportFilters
function. To use this function, load the reports sub-API into your page along with the main API:<script src="http://localhost/JsAPI" type="text/javascript"></script> <script src="http://localhost/JsAPI?api=reports" type="text/javascript"></script>
Then call the loadReportFilters
function:
yellowfin.reports.loadReportFilters(reportId, callback, arg);
The first argument is the unique identifier for the report, which may either be a reportUUID
or a reportId
. We recommend using the reportUUID
where possible. The second argument is a callback function that will be called by the API when the filters for the report have been loaded. The first argument to the callback function will be the list of filters in the report. The second argument to the callback function will be the third argument supplied to the loadReportFilters
function (if specified).
The filters object returned as the first argument to the callback function is an array containing any filters used in the report. Each element in the array is an object containing information about that filter. These filter objects contain the properties:
Examples
This example loads the report filters and displayed them to the user:
function filterCallback(filters) { for (var i = 0; i < filters.length; i++) { alert('Filter ' + filters[i].description + ' (' + filters[i].filterUUID + '), display style: ' + filters[i].display); } } yellowfin.reports.loadReportFilters( 'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63', filterCallback);
This function can be used to load the available filters, and then pass them back to the loadReport
function to set up initial filter values for the report when it is loaded into the page. For example:
function filterCallback(filters) { var filterValues = {}; for (var i = 0; i < filters.length; i++) { if (filters[i].description == 'Country') { filterValues[filters[i].filterUUID] = 'Australia'; } else if (filters[i].description == 'Start Date') { filterValues[filters[i].filterUUID] = '2011-01-01'; } else if (filters[i].description == 'Invoiced Amount') { filterValues[filters[i].filterUUID] = 6400; } } // set up other options to load the report var options = {}; options.reportUUID = 'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63'; options.elementId = 'myReport'; // add the filter values options.filters = filterValues; // load the report yellowfin.loadReport(options); } yellowfin.reports.loadReportFilters( 'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63', filterCallback);
Filter values passed to the loadReport
function should be specified as simple values as above. If the filter is a list style, multiple values can be set using an array:
filterValues[filterUUID] = ['Australia', 'China', 'Italy'];
If the filter is a between style, the start and end values should be set using an array:
filterValues[filterUUID] = [500, 600];
The options.filters
element passed to the loadReport
function should contain values keyed either by filterUUID
or filterId
. We recommend using filterUUID
where possible.
Loading a Dashboard
A dashboard is loaded by calling theyellowfin.loadDash
function:yellowfin.loadDash(options);
Options are passed to the function as a Javascript object. These include an identifier for the dashboard you are loading, the elementId of the HTML element in which to load the dashboard (or the element itself), and other options that alter the way the dashboard is displayed. The available options are:
Examples
This example loads a dashboard into an element specified by its id, setting some initial display options.
var options = {}; options.dashUUID = '3b0b6c9a-9dfb-41f0-b85a-eb17bb8aeeb9'; options.elementId = 'myDash'; options.showFilters = 'false'; options.showExport = 'false'; yellowfin.loadDash(options);
This example does the same thing with an anonymous options object:
yellowfin.loadDash({ dashUUID: '3b0b6c9a-9dfb-41f0-b85a-eb17bb8aeeb9', elementId: 'myDash', showFilters: 'false', showExport: 'false' });
This example passes the element directly, rather than just its id:
yellowfin.loadDash({ dashUUID: '3b0b6c9a-9dfb-41f0-b85a-eb17bb8aeeb9', element: document.getElementById('myDash') });
Loading Dashboard Filters
Filters used by a dashboard can be loaded by calling theyellowfin.dash.loadDashFilters
function. To use this function, load the dashboard sub-API into your page along with the main API:<script src="http://localhost/JsAPI" type="text/javascript"></script> <script src="http://localhost/JsAPI?api=dash" type="text/javascript"></script>
Then call the loadDashFilters
function:
yellowfin.dash.loadDashFilters(dashUUID, callback, arg);
The first argument is the unique identifier for the dashboard. The second is a callback function that will be called by the API when the filters for the dashboard have been loaded. The first argument to the callback function will be the list of filters in the dashboard. The second argument to the callback function will be the third argument supplied to the loadReportFilters
function (if specified).
The filters object returned as the first argument to the callback function is an array containing any analytical filters used in the dashboard, as well as filter group separators. Each element in the array is an object containing information about that filter or filter group. These objects contain the properties:
Examples
This example loads the dashboard filters and displays them to the user:
function filterCallback(filters) { for (var i = 0; i < filters.length; i++) { alert('Filter ' + filters[i].description + ' (' + filters[i].key + '), display style: ' + filters[i].display); } } yellowfin.reports.loadReportFilters(1234, filterCallback);
This function can be used to load the available filters, and then pass them back to the loadDash
function to set up initial filter values for the dashboard when it is loaded into the page:
function filterCallback(filters) { var filterValues = {}; for (var i = 0; i < filters.length; i++) { if (filters[i].description == 'Country') { filterValues[filters[i].key] = 'Australia'; } else if (filters[i].description == 'Start Date') { filterValues[filters[i].key] = '2011-01-01'; } else if (filters[i].description == 'Invoiced Amount') { filterValues[filters[i].key] = 6400; } } // set up other options to load the dashboard var options = {}; options.dashUUID = '3b0b6c9a-9dfb-41f0-b85a-eb17bb8aeeb9'; options.elementId = 'myDash'; // add the filter values options.filters = filterValues; // load the dashboard yellowfin.loadDash(options); } yellowfin.dash.loadDashFilters('3b0b6c9a-9dfb-41f0-b85a-eb17bb8aeeb9', filterCallback);
Filter values passed to the loadDash
function should be specified as simple values as above. If the filter is a list style, multiple values can be set using an array:
filterValues[key] = ['Australia', 'China', 'Italy'];
If the filter is a between style, the start and end values should be set using an array:
filterValues[key] = ['500', '600'];
The options.filters
element passed to the loadDash
function should contain values keyed by the keys
returned from the loadDashFilters
function.