Like what you see? Have a play with our trial version.

Error rendering macro 'rw-search'

null

Versions Compared

Old Version 9

changes.mady.by.user user-3484a

Saved on

compared with

New Version 10

changes.mady.by.user Wendy R

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

&showShare=true

&showShare=false



...


Embedding

...

The advanced API provides developers access to a number of objects and functions that allow fine-grained control over the look and feel of the embedded content.

Here are some examples of what can be achieved by using the API in this way:

  • Creating custom UI objects that can filter both Application and Yellowfin content, or that may have styling requirements that are not supported out of the box in Yellowfin.
  • Creating a dynamic list of reports for each user based on their application profile, allowing them to select those reports and dynamically loading them in your application.
  • Accessing the underlying data set associated with a report in order to execute custom processing such as selecting a value to display or passing data to a third-party API.
  • Creating a custom navigation experience; for example buttons that jump to certain sub-tabs or reports or customized filter breadcrumbs.

Loading the API

Include the following somewhere in your HTML page:

...

Using localhost:8080 as an example, it would look like this:

...

stories

From Yellowfin 9.4, you can embed a story with the publish UUID of the story. The embed URL would look like this:

<script src="http://pathToYourYellowfinServer/JsAPI/v3?StoryUUID=A-Story-UUID">>

This creates an element for the story to render into. 

Note that although the code includes 'StoryUUID', this is actually the publish UUID. Using a story's StoryUUID is possible, but it points to a unique instance of the story, so if the story is edited, the embedded story would not be updated. 

A number of options, such as story width and the display of the toolbar and other elements, can be added to the embed link. Please see the section below for further details.



...


Embedding Using the Advanced API

The advanced API provides developers access to a number of objects and functions that allow fine-grained control over the look and feel of the embedded content.

Here are some examples of what can be achieved by using the API in this way:

  • Creating custom UI objects that can filter both Application and Yellowfin content, or that may have styling requirements that are not supported out of the box in Yellowfin.
  • Creating a dynamic list of reports for each user based on their application profile, allowing them to select those reports and dynamically loading them in your application.
  • Accessing the underlying data set associated with a report in order to execute custom processing such as selecting a value to display or passing data to a third-party API.
  • Creating a custom navigation experience; for example buttons that jump to certain sub-tabs or reports or customized filter breadcrumbs.


Loading the API

Include the following somewhere in your HTML page:

<script src=’pathToYourYellowfinServer/JsAPI/v3’></script>


Using localhost:8080 as an example, it would look like this:

<script src=’localhost:8080/JsAPI/v3’/></script>


This will include the base Yellowfin JavaScript API, which adds a ‘yellowfin’ object to the window scope of your browser. This has a number of useful functions, including the option to load other APIs (Filter, Report and Dashboard).

It will immediately call the JavasScript APIs init() function which will start loading the API functions which depend on the Yellowfin server. The init() function returns a promise which will resolve once this loading has been completed. All events using the API should be run when the init promise has resolved.

<script src='localhost:8080/JsAPI/v3'/></script>
<script>
         window.yellowfin.init().then(() => {
               //The API has loaded

         })
</script>





...


Embedding stories with the Advanced API

From Yellowfin 9.4, you can embed a story with the publish UUID of the story, as described earlier on this page.

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.

Advanced API

A new object will be added to the yellowfin object, this will be stories

Code Block
languagejs
<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>

yellowfin.stories

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.

loadStory(options);

Details

Returns: Promise

Promise parameters: _story_API

Description

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.

storyUUID 

Details

Embed link option: ?StoryUUID=uuid (This is the PublishUUID for the story to be embedded.)

Description

This option is required: if it is not passed, the loadStory call will fail.


element

There is no embed link option for this

The element that we wish to render the story too

showToolbar

Details

Embed link parameter: &showToolbar=true 

Default value: true

Description

This option determines whether the JS API toolbar is shown for the embedded story.

showInfo

Details

Embed link parameter: &showInfo=true 

Default value: true

Description

This option determines whether the embedded story's info dropdown is visible. 

showExport

Details

Embed link parameter: &showExport=true

Default value: true

Description

This option determines whether the embedded story's PDF export options are visible to the story viewer. 


showBannerImage

Details

Embed link parameter: &showBannerImage=true

Default value: true

Description

This option determines whether the embedded story's banner image is shown. 


showHeader

Details

Embed link parameter: &showHeader=true

Default value: true

Description

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.

showAuthor

Details

Embed link parameter: &showAuthor=true

Default value: true

Description

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.

showDateContainer

Details

Embed link parameter: &showDateContainer=true

Default value: true

Description

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.

showLikeButton

Details

Embed link parameter: &showLikeButton=true

Default value: true

Description

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.

showReadBy

Details

Embed link parameter: &showReadBy=true

Default value: true

Description

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.

showStoryTitle

Details

Embed link parameter:  &showStoryTitle=true

Default value: true

Description

This option determines whether the embedded story's title is displayed.

showFooter

Details

Embed link parameter:  &showFooter=true

Default value: true

Description

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.

showContributors

Details

Embed link parameter: &showContributors=true

Default value: true

Description

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.

width

Details

Embed link parameter: &width=...

Default value: element width

Description

This option sets the total width of the embedded story.

storyWidth

Details

Embed link parameter: &storyWidth=...

Default value: 3/4 of width

Description

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).

bannerImageHeight

Details

Embed link parameter: &bannerImageHeight=...

Default value: 300px

Description

This option sets the custom height that should be applied to the banner image container.

bannerImageWidth

Details

Embed link parameter: &bannerImageWidth=...

Default value: Value of width

This option sets the custom width that should be applied to the banner image.

loadStoryAPI()

Loads the StoryAPI so that we can load stories, returns a promise that is resolved when the API loads.

loadStory(options)

**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 is object is loaded before attempting to load a story. 

Functions available in the StoryAPI

  • likeStory()
  • unlikeStory() 
  • toggleLike(shouldLike:boolean => Default inverse of current value)
  • getCurrentLikeStatus(successFunction: function to call one the current status is received) => Get status from the server
  • storyContributors()
  • storyReaders()


Example:


Code Block
src="<%=YF URL%>/JsAPI/v3?StoryUUID=<%=Story Publish UUID%>&showHeader=false&bannerImageWidth=500"></script>


Example Advanced API :

HTML:

Code Block
languagexml
<script src="<%=YF URL%>/JsAPI/v3"></script>

<div id="storyContainer"></div>

JavaScript:


Code Block
languagejs
window.yellowfin.loadStoryAPI().then(() => {
    window.yellowfin.stories.loadStory(
{         storyUUID: '<%=Story Publish UUID%>',          element: 'div#storyContainer'     }
).then((storyAPI) =>
{         console.log(storyAPI);         window.storyAPI = storyAPI;     }
);
});

This will include the base Yellowfin JavaScript API, which adds a ‘yellowfin’ object to the window scope of your browser. This has a number of useful functions, including the option to load other APIs (Filter, Report and Dashboard).

It will immediately call the JavasScript APIs init() function which will start loading the API functions which depend on the Yellowfin server. The init() function returns a promise which will resolve once this loading has been completed. All events using the API should be run when the init promise has resolved.

...