Until 2021, this page was known as 'Base API'. The better reflect the contents of this page and the ongoing improvements to our JS API, we decided that 'Advanced API' was a more appropriate name for this page. After a transition period, we'll update the page name to reflect just the new name.
This API will only be available on pages that have the included the “JsAPI/v3” JS file into their page. See example:
<script src="https://pathToYourYellowfinServer/JsAPI/v3"></script> |
This API will not be available in Dashboard Code Mode. |
The Advanced API contains a number of functions to assist with loading the Yellowfin APIs in your own web page. There are functions to load the report and dashboard loader APIs which will allow you to load Dashboard and Reports.
There is also a function to assist with session management.
Promise
Initialises the Base API. This is called when the API is included into a page. Returns a promise to indicate when this has finished loading, any usage of the API should wait until this promise has resolved.
Include the Yellowfin Report API on the page and then load a report after the init() promise has resolved:
<script src="https://pathToYourYellowfinServer/JsAPI/v3"></script> |
Nothing
Ends the current user session.
Promise
Waits for the init() promise to load and then loads a report with the passed options. Once the report has been loaded it will be appended to the passed element and the report will begin to run.
When the promise is resolved a Report object will be passed to the .then() functions. The promise will be resolved just before the report starts running.
There are a number of options that will be accepted as part of the options object:
Type: String
ReportUUID of the report we wish to load. This is the PublishUUID on the ReportHeader table.
Type: DOM Element, Selector String
Element that you wish to render the report into. Can either be a DOM element or a selector that will be used to select the element from the page.
If no width or height is passed the report will expand to the dimensions of the element.
Type: Number
Width to render the report in pixels.
Type: Number
Height to render the report in pixels.
Type: Array[Object]
Array of Objects that will be used to apply the initial filter values.
See the FiltersAPI to understand the filter values.
The objects should contain the following information:
[{ //Set a between filter |
Type: String
Identifier for this instance of the report. If this property is not defined, a random id will be generated. This means that if you include the same report multiple times without defining an instance name, it will always be a separate instance of that report.
If you do set this, it allows you to load multiple views of the same instance of the report.
//Load the report into two different elements |
Type: Boolean
Determines whether or not to show the reports toolbar.
//Load the report with showToolbar not defined |
Or set the showToolbar property to false:
//Load the report with showToolbar set to false |
Type: Boolean
Determines whether or not to show the report title in the report’s toolbar. Default: true.
If the showTitle option is set to false:
//Load the report with showTitle option set to false |
Type: Boolean
Determines whether or not to show the info option in the report’s toolbar. Default: true
If this option is set to false:
//Load the report with showInfo option set to false |
Type: Boolean
Determines whether or not to show the filters option in the reports toolbar. Default is true.
If this option is set to false:
//Load the report with showFilter option set to false |
Type: Boolean
Determine whether or not the export option will be displayed in the report toolbar. Export options allow a report to be exported to an external file format such as csv, xls, pdf, txt and doc.
With the showExport parameter set to false, the export icon in the toolbar will be removed:
//Load the report with showExport option set to false |
Type: Boolean
Determines whether or not to show the share option in the reports toolbar. Default is true.
//Load the report with showShare option set to false |
Type: Boolean
Determines whether or not to show the reports chart/table options in the reports toolbar. Default is true.
If this option is set to false:
//Load the report with this option set to false |
Load the report and then print its name:
yellowfin.loadReport({ //Some code to execute when the report has loaded console.log(report.name + ‘ has finished loading’); |
The interactions object enables you to define which interactions should be available on a particular visualization of a report. This lets you tell the Yellowfin renderer which functionality you want the user to be able to use within that visualization.
If there are multiple elements representing the same report and you wish to disable an interaction, you must disable it on all the elements you are displaying. For example, if you disabled drill down on the first element and then did not on the second, the user would still be able to drill down on the second element.
By default, any interaction that is not explicitly set to false is treated as enabled and will display if the report allows it.
Allows drill down functionality to be disabled.
Allows drill anywhere functionality to be disabled.
Allows drill through functionality to be disabled.
Allows unit selection functionality to be disabled.
Allows brushing functionality to be disabled.
Allows the timeSlider functionality to be disabled.
Allows drill breadcrumb functionality to be disabled
Allows seriesSelection functionality to be disabled
Allows annotations to be disabled.
To disable all user interactivity on the report when using loadReport:
yellowfin.loadReport({ reportId: ‘a report id’, interactions: { drillDown: false, drillAnywhere: false, drillThrough: false, unitSelection: false, brushing: false, timeSlider: false, drillBreadcrumbs: false, seriesSelection: false, annotations: false }, element: document.querySelector(‘#reportElement’) }). |
Promise
Waits for the init() promise to load and then loads a dashboard with the passed options. Once the dashboard has been loaded it will be appended to the passed element and the content on the dashboard will begin to run.
There are a number of parameters that can be included in the dashboardOptions object:
Type: String
The PublishUUID of the dashboard that you wish to load.
Type: DOM Element, Selector String
Element that you wish to render the dashboard into. Can either be a DOM element or a selector that will be used to select the first instance of that selector from the page.
If no width or height is passed the dashboard will fill the dimensions of the element.
Type: Array[Object]
Array of Objects that will be used to apply the dashboards initial filter values.
See the FiltersAPI to understand the filter values
The objects should contain the following information:
[{ //Set a between filter |
Type: Boolean
Determines whether or not to show the dashboard’s toolbar. Default is true.
//Load the dashboard with showToolbar not defined |
The following is a dashboard with the toolbar showing:
But if the showToolbar property is set to false:
//Load the dashboard with showToolbar set to false |
Type: Boolean
Determines whether or not to show the info option in the dashboard’s toolbar. Default: true.
If set to false:
//Load the dashboard with showInfo option set to false |
Type: Boolean
Determines whether or not to display the share option in the dashboard’s toolbar. Default is true.
If set to false:
//Load the dashboard with showShare option set to false |
Type: Boolean
Determines whether or not to show the filters option in the dashboard’s toolbar. Default is true.
If set to false:
//Load the dashboard with showFilter option set to false |
Type: Boolean
Determines whether or not a canvas tab should be scaled. Default is true.
If this is set to false, then the canvas tab will appear at the exact size it was created. This setting has no effect on sub-tabs which don’t contain canvas tabs.
//Load the dashboard with scaleCanvasTabs option set to false |
Determines whether or not to show the global content containers when rendering the dashboard.
//Load the dashboard with showGlobalContentContainer option set to false |
From Yellowfin 9.4, you can embed a story with the publish UUID of the story (see the JS API to embed Yellowfin content wiki page for more info).
Using the Advanced API toolset expands the options available to you when embedding a story, so that you can adjust the look and feel of the story to suit your needs. You may wish to hide contributors or limit the width of the embedded story, and the Advanced API lets you do this.
A new object will be added to the yellowfin object, this will be stories
<script src="http://yellowfinServer/JsAPI/v3"></script> <div id="myStoryDiv"></div> <script> yellowfin.loadStoryAPI().then(() => { yellowfin.stories.loadStory({ storyUUID: 'a-story-uuid', //This should be the story's publish uuid element: document.querySelector('#myStoryDiv') //The div to render the story into }); } </script> |
Currently, yellowfin.stories can only contain one function as shown above — loadStory
— which will load the story. However, the loadStory
function can take a number of options. The function and its options are outlined below.
Returns: Promise
Promise parameters: _story_API
This function loads the story associated with the passed options.storyUUID
, and returns a promise that is resolved once complete.
The resolved promise will pass a storyAPI
object.
The possible values that can be added to the options object are below.
Embed link option: ?StoryUUID=uuid (This is the PublishUUID for the story to be embedded.)
This option is required: if it is not passed, the loadStory call will fail.
There is no embed link option for this.
This is the element that we wish to render the story to.
Embed link parameter: &showToolbar=true
Default value: true
This option determines whether the JS API toolbar is shown for the embedded story.
Embed link parameter: &showInfo=true
Default value: true
This option determines whether the embedded story's info dropdown is visible.
Embed link parameter: &showExport=true
Default value: true
This option determines whether the embedded story's PDF export options are visible to the story viewer.
Embed link parameter: &showBannerImage=true
Default value: true
This option determines whether the embedded story's banner image is shown.
Embed link parameter: &showHeader=true
Default value: true
This option determines if the embedded story's header is shown.
A story's header includes the fields for author and date, and the counters for likes and reads. To display any of these, first include this showHeader
option, and set it to true.
Embed link parameter: &showAuthor=true
Default value: true
This option determines whether the embedded story's author is shown. Even if it's set to true, it will only be displayed if the showHeader
option is also present and set to true.
Embed link parameter: &showDateContainer=true
Default value: true
This option determines whether the embedded story's publication date is shown. Even if it's set to true, it will only be displayed if the showHeader
option is also present and set to true.
Embed link parameter: &showLikeButton=true
Default value: true
This option determines whether the story's 'Like' button is shown. Even if it's set to true, it will only be displayed if the showHeader
option is also present and set to true.
Embed link parameter: &showReadBy=true
Default value: true
This option determines whether the list of people who have read the embedded story is shown. Even if it's set to true, it will only be displayed if the showHeader
option is also present and set to true.
Embed link parameter: &showStoryTitle=true
Default value: true
This option determines whether the embedded story's title is displayed.
Embed link parameter: &showFooter=true
Default value: true
This option determines whether the embedded story's footer is displayed.
The story footer includes contributors. To display the list of contributors, first include this showFooter
option, and set it to true.
Embed link parameter: &showContributors=true
Default value: true
This option determines whether the list of story contributors is shown when embedded. Even if it's set to true, it will only be displayed if the showFooter
option is also present and set to true.
Embed link parameter: &width=...
Default value: element width
This option sets the total width of the embedded story.
Embed link parameter: &storyWidth=...
Default value: 3/4 of width
This option sets the full width of the embedded story's body. The width of most of the story's contents will be 200px less, unless it is set to display at full width (eg, an image in wide mode).
Embed link parameter: &bannerImageHeight=...
Default value: 300px
This option sets the custom height that should be applied to the banner image container.
Embed link parameter: &bannerImageWidth=...
Default value: Value of width
This option sets the custom width that should be applied to the banner image.
Loads the StoryAPI so that we can load stories, returns a promise that is resolved when the API loads.
**This is just a pass through option for yellowfin.stories.loadReport the options that are passed to it should be the same, it just ensures that the stories object is loaded before attempting to load a story.
Example:
src="<%=YF URL%>/JsAPI/v3?StoryUUID=<%=Story Publish UUID%>&showHeader=false&bannerImageWidth=500"></script> |
Example Advanced API :
HTML:
<script src="<%=YF URL%>/JsAPI/v3"></script> <div id="storyContainer"></div> |
JavaScript:
window.yellowfin.loadStoryAPI().then(() => { window.yellowfin.stories.loadStory( { storyUUID: '<%=Story Publish UUID%>', element: 'div#storyContainer' } ).then((storyAPI) => { console.log(storyAPI); window.storyAPI = storyAPI; } ); }); |