Admin Notes. Javascript API. Release 5.1 December 2010

Transcription

1 Admin Notes Javascript API Release 5.1 December 2010

2 Yellowfin Release 5.1 Admin Notes Under international copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written permission of Yellowfin International Pty Ltd, except in the manner described in the software agreement. The information in this document is subject to change without notice. If you find any problems with this documentation, please report them to Yellowfin in writing at Yellowfin does not warrant that this document is error free. Copyright Yellowfin International All rights reserved. Portions Copyright Microsoft Corporation. All rights reserved. Trademarks: Yellowfin and the Yellowfin Logo are registered trademarks of Yellowfin International. All other product and company names mentioned herein are the trademarks of their respective owners. Version: 1.0 Published: December 2010

3 3 Table of Contents Yellowfin Reports Javascript API... 4 Example usage... 5 Limitations... 6 Development Guide... 7 Enabling the API... 7 Using the API... 8 Simple Usage... 8 Advanced Usage Server Information Loading a report Hints and Tips Styling Troubleshooting... 17

4 4 Yellowfin Reports Javascript API Using the Javascript API, Yellowfin reports can be embedded in external webpages. The external webpage can be hosted on a separate web server. The only requirement is that the end user s browser can access the Yellowfin server. The html page can include multiple reports; however each separate report may only be included once on a page. Example: Interactive elements are available, such as drill-through, drill-down, changing filters, series selection, and exporting to formats such as PDF and XLS. The layout of a report includes the Title Bar, and the Report itself. The Title Bar displays the title of the report, as well as buttons to control interactive elements on the report. These include Filters, Sections, Series selection, and Paging options. Each of these buttons displays an overlay to set the applicable options, which are then applied to the report.

5 5 Example usage Within the body of your html, include a link to the Javascript API, identifying the report to load: <script src=" type="text/javascript"></script> Advanced usage, including specifying additional display options and loading reports on command are detailed below, in the Development Guide. Within the Yellowfin interface, you can copy the html used to embed a report from the Distribute menu: The report must be activated to access the Distribute menu. The URL generated for a report is based on the External Instance Base URL setting in Configuration. Make sure this is set to a URL that will be accessible to your end users.

6 6 Limitations Limitations of the external reporting API include: Security. All reports are loaded using a guest user. Reports must have a security level of Unsecure, otherwise an error will be returned and the report will not be loaded. The date slider is not supported Parameters are not supported Reports at Client Orgs are not supported Multiple reports may be added to a single html page, but each report may only be included once on a page Filter dependencies are not supported Navigation and zooming on GIS maps are not supported Selectable date units on charts are not supported

7 7 Development Guide Enabling the API The Javascript API has been introduced with the release of Yellowfin 5.1, and is enabled by default in all new installations of Yellowfin 5.1 and later. If you have upgraded to Yellowfin 5.1 from a previous version, you will need to make a configuration change to enable the API. Find and edit the file web.xml, located in the directory Yellowfin/appserver/webapps/ROOT/WEB-INF/. You will need to add two elements a <servlet> element, and a <servlet-mapping> element. The order of the elements in this file is important all <servlet> elements must be grouped together, and all <servlet-mapping> elements must be grouped together. Find the last <servlet> section, and add the following below it: <servlet> <servlet-name>jsapiservlet</servlet-name> <servlet-class>com.hof.mi.servlet.jsapiservlet</servlet-class> </servlet> Then find the last <servlet-mapping> section, and add the following below it: <servlet-mapping> <servlet-name>jsapiservlet</servlet-name> <url-pattern>/jsapi</url-pattern> </servlet-mapping> Yellowfin must be restarted after saving the changes to this file. When a report is requested via the Javascript API, a session is created for the end-user using the Guest Role. You must set up a guest role to be able to user the API:

8 8 Using the API There are two ways to load a report into your html page. The simple method involves including a single Javascript URL. The more advanced method allows you to customise the report display and load reports on demand from other scripts. Simple Usage Include a script tag in your html page that points to the Javascript API on your Yellowfin server. The report identifier must be included as a parameter on the URL. For example: <script src=" type="text/javascript"></script> The URL to the API is based on the URL used to access the Yellowfin front-end. For example, if users access the Yellowfin front-end through the URL then the Javascript API URL will be The URL will be accessed by the end-user s browser, so it must be accessible from anywhere that end-users will use your page (internal network, external, via VPN, etc).

9 9 To ensure the server supports the version of the API your page is written for, you can use the version parameter. If the server supports multiple versions of the API, this parameter determines which version the server will use. If the server does not support the requested version, an error message will be displayed. The version currently supported is 1.0. <script src=" type="text/javascript"></script> If the version parameter is not included, the server will use the current version ( 1.0 ). The report may be identified by the reportid parameter, or by the wsname parameter. Additional parameters may also be added to the URL, which will alter the way the report is displayed. The available parameters are: reportid wsname version elementid showtitle showinfo showfilters showsections showseries showpagelinks Either reportid or wsname must be present. The numeric reportid identifying the report to load. Either reportid or wsname must be present. The Web Service name identifying the report to load. The API version to use. If the server does not support the requested version, an error message will be displayed. If this is not included, the server will use its current API version. The id of the html element in which to load the report. If this is not included, a container element will be created at the point that the script tag is included. Set to 'false' to omit the title bar at the top of the report. All interactive buttons included in the title bar will also be omitted. Set to 'false' to omit the Info button in the title bar. Set to 'false' to omit the Filters button in the title bar. Any user-prompt filters will not be displayed. Set to 'false' to omit the Sections button in the title bar (for reports with tabbed or multi-page sections). Set to 'false' to omit the Series button in the title bar (for reports with the series selection option). Set to 'false' to omit the previous page/next page button in the title bar

10 10 showexport height width display fittablewidth canchangedisplay (for reports with multiple pages). Set to 'false' to omit the export button in the title bar. Set this to a numeric value to override the report height. Set this to a numeric value to override the report width. Default: 'chart' Set to 'table' to display the report initially as a table. Set to 'chart' to display the report initially as a chart. This is ignored for reports that do not have both table and chart available. Set to 'true' to attempt to scale the report to the width of the enclosing element. Set to 'false' to omit the buttons that allow the user to switch between chart and table display. This example includes a report identified by its Web Service name, and sets the dimensions of the report: <script src=" type="text/javascript"></script> This example uses an existing element to display the report in: <div id="myreportdiv" style="background: blue; width: 500px; height: 350px"> </div> <script src=" type="text/javascript"></script> This example uses an existing element to display the report in, overrides the report dimensions, and changes some of the initial display options: <div id="myreportdiv" style="background: blue; width: 500px; height: 350px"> </div> <script src=" ight=300&showfilters=false&display=table" type="text/javascript"></script>

11 11 Advanced Usage If you want to have more control over the loading of reports, call reports on demand or set display options dynamically (eg. 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=" type="text/javascript"></script> As mentioned above, a specific version of the API may be requested using the version parameter: <script src=" type="text/javascript"></script> If the browser is unable to load the API, any calls to load reports will fail. If you wish to detect whether the API has loaded successfully, you should check if the variable window.yellowfin is available: <script src=" 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: yellowfin.apiversion yellowfin.baseurl yellowfin.serverinfo.releaseversion yellowfin.serverinfo.buildversion yellowfin.serverinfo.javaversion yellowfin.serverinfo.operatingsystem yellowfin.serverinfo.operatingsystemarch The version of the API supported by the server. The current version is "1.0" The base URL used to connect to the API on the server The release version of Yellowfin running on the server (eg. "5.1") The build version of Yellowfin running on the server (eg. " ") The java version installed on the server The Operating System running on the server The Operating System architecture on

12 12 the server yellowfin.serverinfo.operatingsystemversion The Operating System version on the yellowfin.serverinfo.schemaversion server The schema version of the Yellowfin configuration database Example: <script src=" 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 the yellowfin.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: reportid wsname elementid element showtitle showinfo showfilters Either reportid or wsname must be present. The numeric reportid identifying the report to load. Either reportid or wsname must be present. The Web Service name identifying the report to load. Either elementid or element must be present. The id of the html element in which to load the report. Either elementid or element must be present. The html element in which to load the report. Set to 'false' to omit the title bar at the top of the report. All interactive buttons included in the title bar will also be omitted. Set to 'false' to omit the Info button in the title bar. Set to 'false' to omit the Filters button in the title bar. Any user-prompt

13 13 showsections showseries showpagelinks showexport height width display filters will not be displayed. Set to 'false' to omit the Sections button in the title bar (for reports with tabbed or multi-page sections). Set to 'false' to omit the Series button in the title bar (for reports with the series selection option). Set to 'false' to omit the previous page/next page button in the title bar (for reports with multiple pages). Set to 'false' to omit the Export button in the title bar. Default: automatically detected from the dimensions of the enclosing element Set this to a numeric value to override the report height. Default: automatically detected from the dimensions of the enclosing element Set this to a numeric value to override the reportwidth. Default: 'chart' Set to 'table' to display the report initially as a table. Set to 'chart' to display the report initially as a chart. fittablewidth This is ignored for reports that do not have both table and chart available. Set to 'true' to attempt to scale the report to the width of the enclosing element. canchangedisplay Set to 'false' to omit the buttons that allow the user to switch between chart and table display. This example loads a report into an element specified by its id, setting some initial display options: var options = {}; options.reportid = 1234; options.elementid = 'myreport'; options.showfilters = 'false'; options.showseries = 'false'; options.display = 'chart'; options.fittablewidth = 'false'; yellowfin.loadreport(options);

14 14 This example does the same thing with an anonymous options object: yellowfin.loadreport({ reportid: 1234, elementid: 'myreport', showfilters: 'false', showseries: 'false', display: 'chart', fittablewidth: 'false' }); This example passes the element directly rather than just its id: yellowfin.loadreport({ reportid: 1234, element: document.getelementbyid('myreport') }); Hints and Tips The enclosing element should be a block-level element, such as a div. The enclosing element should have no padding or border If you want a border or padding around your report, you should enclose the element in another element that has the padding or border. Example: <div style="padding: 10px; border: 1px solid black;"> <div id="myreport"> </div> </div> <script type="text/javascript"> yellowfin.loadreport({reportid: 1234, elementid: 'myreport' }); </script> If you are using the simple method, and do not pass an elementid to the API, the enclosing element is created automatically. You can enclose the script tag in another element with padding or border styles applied. For example: <div style="padding: 10px; border: 1px solid black;"> <script type="text/javascript" src=" </div> The enclosing element should have a fixed height/width. For chart only reports, the chart will be rendered to fit within the enclosing element. In case a report does not fit within the element, scrollbars will be included, so the rest of your page layout is not affected. If you do not include a fixed height and width on your element, the browser will choose how to layout the report. This may mean that the report will increase or

15 15 decrease in size when different options are clicked by the user. This may be preferable in some cases. Make sure the Javascript API URL is accessible for any end-users. Avoid using localhost or private IP addresses. Your HTML should be well-structured where possible. For example, you may have problems with the API if you do not have a <body> tag. Styling Report styles will follow those defined when creating the report. Styles used are inserted into the html document automatically when a report is loaded. You may wish to customise the styles of some of the additional elements, such as the title bar, info box or filter input area. To do this, you can override the following styles in your html document: div.yfreporttitleinner Report Title bar container Example styles applied: background, border div.yfreporttitle Report Title container Example styles applied: background, font td.yfreporttitle Report Title table cell Example styles applied: background, font td.yfreporttitlelinks Report Title bar buttons Example styles applied: background div.drillup Contains link to the parent report after a drill-through has been performed. Example styles applied: background, border, font td.yfreportdrillup Contains links to navigate the hierarchy on drill-down reports. Example styles applied: background, border, font

16 16 table.yfreportinfoinner Report Information popup container Example styles applied: background, border td.yfreportinfocell Report Info table cell Example styles applied: font table.yfreportexportinner Report export popup container Example styles applied: background, border div.yfreportfiltersinner Report Filters popup container Example styles applied: background, border td.yfreportfiltercell Report Filters table cell Example styles applied: font.yfreportfilterinput1 Report Filter form entry field (long) Example styles applied: font, width.yfreportfilterinput2 Report Filter form entry field (medium) Example styles applied: font, width.yfreportfilterinput3 Report Filter form entry field (short) Example styles applied: font, width div.yfreportsectionsinner Report Sections popup container Example styles applied: background, border td.yfreportsectionscell Report Sections table cell Example styles applied: font div.yfreportpagelinksinner Report Pages popup container Example styles applied: background, border

17 17 td.yfreportpagelinkscell Report Pages table cell Example styles applied: font table.yfreporterror Report error message table Example styles applied: background, border, font td.yfreporterror Report error message table cell Example styles applied: background, font div.yfreportseriesinner Report series selection popup container Example styles applied: background, border, font td.yfreportseriescell Report series selection table cell Example styles applied: font Troubleshooting As mentioned previously, you can check the window.yellowfin variable to determine if the reports API has been loaded successfully. For example, when using the simple method: <script src=" type="text/javascript"></script> <script typt="text/javascript"> if (!window.yellowfin) { alert('error loading API'); } </script> When using the advanced method, you can use this to determine whether or not to attempt to load a report: <script src=" type="text/javascript"></script> <script typt="text/javascript"> if (window.yellowfin) { yellowfin.loadreport({reportid: 1234, elementid: 'myreport' }); } else { alert('error loading API'); } </script> Errors encountered when using the API are generally presented through Javascript alerts. These include a description of the error. Common errors include:

18 18 API version requested is not supported The server does not support the API version requested. No Guest Role was found No role was found with the Guest flag checked. A guest role is required to use the Javascript API. ReportId not specified The yellowfin.loadreport function is called without a report identifier (reportid or wsname). Report not found The report specified by the reportid or wsname could not be found. Report not loaded An operation has been attempted on a report that has not yet been loaded. Report is in draft mode The report specified is in draft mode. Only active reports can be accessed through the Javascript API. User does not have access to this report The report cannot be accessed through the Javascript API. Reports must have no security restrictions applied to be accessible through the Javascript API. This includes restrictions placed on the report s category and view. Invalid command specified Invalid request An invalid request has been made to the API. Error loading report Error running report Error running report command A server-side error occurred while running an API command. Check the Yellowfin server logs for more information.