iDetailAid Viewer API¶
The iDetailAid Viewer (which wraps all content) exposes a number of useful API methods that can be called from JavaScript written either directly into the slide using the iDetailAid Code Editor or inside HTML Packages
The Viewer exposes a public API via Viewer.api, for example Viewer.api.goBack()
Namespaces
The main viewer exposes its API under the following namespace: uk.co.idetailaid.Viewer.
For convenience, the following aliases are also created if available: ida.Viewer and Viewer.
The rest of this documentation refers to the Viewer alias.
HTML Packages
HTML packages are run inside an <iFrame/> within the Presentation Viewer. The API commands are automatically injected for you under the same namespaces as in the Viewer:
If your HTML package code already defines the aliases ida or Viewer, then you must use the full namespace to access the API.
uk.co.idetailaid.Viewer.api.goBack();
See HTML Packages for more.
Tip
You can get interactive help in the Viewer itself. Preview a slide, open the Inspector and run one of the following commands in the Console
Viewer.help();
Viewer.api.help();
Viewer.api.help('goToSlide');
Presentation Code Editor
The bulk of the Viewer API commands run in the Presentation Code Editor will require the presentation to be loaded before they have an affect.
Ensure you wrap your commands in the presentationLoaded event.
$presentation.on('presentationLoaded', () => {
Viewer.api.setArrows({left:false, right:false});
})
API Methods¶
| Method name | description |
|---|---|
| writeMockAPI | Creates a mock API for the Viewer API to enable development of HTML packages outside of iDetailAid. |
| writeMockManifest | Creates mock presentation data that the mock API can use. |
| goToSlide | Navigate to another slide either in the current presentation, or another presentation. |
| goTo | Navigate to a slide by its grid position in the current presentation. |
| goBack | Navigate back to the previous slide. |
| goUp | Navigate to the slide above in the current column. |
| goDown | Navigate to the slide below in the current column. |
| goLeft | Navigate to the first slide in the column to the left. |
| goRight | Navigate to the first slide in the column to the right. |
| openReference | Open an iDetailAid reference document. |
| openAsset | Open a iDetailAid asset. |
| openUrl | Open a url. |
| setSwipe | Enable / disable swiping for the whole presentation, or a specific slide. See $slide API to disable it for the current slide only. |
| setArrows | Enable / disable arrows for the whole presentation, or a specific slide. See $slide API to disable it for the current slide only. |
| getCurrentSlideDetails | Get information about the current slide. |
| getCurrentPresentation | Get the current presentation. |
| getCurrentPresentationSlides | Get the current presentation slides. |
| getCurrentPresentationCoreFlowSlides | Get the current presentation core flow slides only. |
| getCurrentPresentationManifest | Get the current presentation manifest. |
| bringToFront | Bring a content area to the front. |
| sendToBack | Send a content area to the back |
| resetZIndex | Reset a content area back to its original layering |
| fullscreen | Resizes the content area to fill the screen |
| exitfullscreen | Resizes a content area back to its initial size |
writeMockAPI¶
Viewer.api.writeMockAPI()
Creates a mock API for the Viewer API to enable development of HTML packages outside of iDetailAid.
| Argument | Type | Description |
|---|---|---|
| Boolean | Optional. If true the mock API is not saved to file, but printed to the console. |
Tip
Include this, along with the mock manifest file into your HTML package as follows to get testing data outslde of iDetailAid
<script src="iDetailAid_mock_viewer_manifest.js"></script>
<script src="iDetailAid_mock_viewer_api.js"></script>
writeMockManifest¶
Viewer.api.writeMockManifest()
Creates a mock API for the Viewer API to enable development of HTML packages outside of iDetailAid.
| Argument | Type | Description |
|---|---|---|
| Boolean | Optional. If true the mock API is not saved to file, but printed to the console. |
Tip
Include this, along with the mock api file into your HTML package as follows to get testing data outslde of iDetailAid
<script src="iDetailAid_mock_viewer_manifest.js"></script>
<script src="iDetailAid_mock_viewer_api.js"></script>
You can then edit the mock manifest to structure the data how you want for testing.
goToSlide¶
Viewer.api.goToSlide ( slideId, [presentationId] )
Navigate to another slide either in the current presentation, or another presentation.
| Argument | Type | Description |
|---|---|---|
| slideId | int | The iDetailAid slide ID to navigate to |
| [presentationId] | int | The ID of the iDetailAid presentation if slideId is in another presentation |
goTo¶
Viewer.api.goTo ( column, row )
Navigate to a slide by its grid position in the current presentation
| Argument | Type | Description |
|---|---|---|
| column | int | The column index of the slide |
| row | int | The row index of the slide |
goBack¶
Viewer.api.goBack()
Navigate back to the previous slide.
goUp¶
Viewer.api.goUp()
Navigate to the slide above in the column.
goDown¶
Viewer.api.goDown()
Navigate to the slide below in the current column.
goLeft¶
Viewer.api.goLeft()
Navigate to the first slide in the column to the left.
goRight¶
Viewer.api.goRight()
Navigate to the first slide in the column to the right.
openReference¶
Viewer.api.openReference( referenceId )
Open an iDetailAid reference document
| Argument | Type | Description |
|---|---|---|
| referenceId | int | The iDetailAid Id of the reference. |
openAsset¶
Viewer.api.openAsset( assetId )
Open a iDetailAid asset
| Argument | Type | Description |
|---|---|---|
| assetId | int | The iDetailAid Id of the assetId. |
openUrl¶
Viewer.api.openUrl( url )
Open a url
| Argument | Type | Description |
|---|---|---|
| url | string | A url to open in a browser |
setArrows¶
Viewer.api.setArrows( state )
Viewer.api.setArrows( state, x, y )
Enable or disable arrows on the on the whole presentation, or a specific slide found at position x and y in the presentation.
See Slide API to disable it for the current slide only.
It accepts one argument; state: An object containing one or more of the following keys: 'left', 'right', 'up', 'down'. Each is a boolean: true to enable, false to disable.
The update is a patch, so setting only on direction will modify only that direction.
To disable just the left and right:
Viewer.api.setArrows( {left:false, right:false} )
To disable all:
Viewer.api.setArrows( {left:false, right:false, up:false, down:false} )
To enable just one:
Viewer.api.setArrows( {left:true} )
To enable affect a specific slide:
Viewer.api.setArrows( {left:true}, 10, 4 )
| Argument | Type | Description |
|---|---|---|
| state | object | An object containing one or more of the following keys: 'left', 'right', 'up', 'down'. Each is a boolean: true to enable, false to disable. |
| x | integer | Optional. The x position in the presentation of the slide to affect. |
| y | integer | Optional. The y position in the presentation of the slide to affect. |
setSwipe¶
Viewer.api.setSwipe( state )
Viewer.api.setSwipe( state, x, y )
Enable or disable arrows on the on the whole presentation, or a specific slide found at position x and y in the presentation.
See Slide API to disable it for the current slide only.
It accepts one argument; state: An object containing one or more of the following keys: 'left', 'right', 'up', 'down'. Each is a boolean: true to enable, false to disable.
The update is a patch, so setting only on direction will modify only that direction.
To disable just the left and right:
Viewer.api.setSwipe( {left:false, right:false} )
To disable all:
Viewer.api.setSwipe( {left:false, right:false, up:false, down:false} )
To enable just one:
Viewer.api.setSwipe( {left:true} )
To enable affect a specific slide:
Viewer.api.setSwipe( {left:true}, 10, 4 )
| Argument | Type | Description |
|---|---|---|
| state | object | An object containing one or more of the following keys: 'left', 'right', 'up', 'down'. Each is a boolean: true to enable, false to disable. |
| x | integer | Optional. The x position in the presentation of the slide to affect. |
| y | integer | Optional. The y position in the presentation of the slide to affect. |
getCurrentSlideDetails¶
Viewer.api.getCurrentSlideDetails( callback )
Viewer.api.getCurrentSlideDetails().then( success )
Get information about the current slide being shown - NOT necessarily the slide that is running your code.
Current slide might not be the slide running your code
The iDetailAid Viewer caches slides off screen. Any code that runs in those slides, calling Viewer.api.getCurrentSlideDetails( callback ) will get information about the current slide being shown not the slide the code is in.
This is not an issue when exported to systems like Veeva, as only one slide is ever loaded at once, but in the other platforms, including the iDetailAid preview, you will need to be explicit when getting data for the slide that contains your code.
Do
$slide.on('slideShown', (event)=> {
// When the slide is shown, we get the current slide details in the event object
console.log(' this slide is ', event.detail.slide.title);
})
$slide.on('slideLoaded', async (event)=> {
// When the slide is shown, we get the current slide details in the event object
console.log(' this slide is ', event.detail.slide.title);
Viewer.api.getCurrentSlideDetails( (details) => {
console.log(' the current slide being shown is ', details.slide.title);
})
})
Don't
window.addEventListener('load', ()=> { // Load does not mean this slide is the current slide
Viewer.api.getCurrentSlideDetails( (details) => {
console.log(' this slide is', details.slide.title);
})
})
| Argument | Type | Description |
|---|---|---|
| callback | Function | A callback function invoked with one argument: (slideDetails). These details are also provided in the $(document).on('slideLoaded', event => console.log(e) ) handler. |
returns : Promise
getCurrentPresentation¶
Viewer.api.getCurrentPresentation( callback )
Viewer.api.getCurrentPresentation().then( success )
Get information about the current presentation.
| Argument | Type | Description |
|---|---|---|
| callback | Function | A callback function invoked with one argument: (presentation). This is the presentation object |
returns : Promise
getCurrentPresentationSlides¶
Viewer.api.getCurrentPresentationSlides( asGrid, callback )
Viewer.api.getCurrentPresentationSlides( asGrid ).then( success )
Get an array of the current presentation slides.
| Argument | Type | Description |
|---|---|---|
| asGrid | boolean | An optional argument. Default is false. If true a 2 dimensional array is returned, representing the presentation structure. If false a flat array is returned |
| callback | Function | A callback function invoked with one argument: (slides). The array of slide. |
returns : Promise
getCurrentPresentationCoreFlowSlides¶
Viewer.api.getCurrentPresentationCoreFlowSlides( callback )
Viewer.api.getCurrentPresentationCoreFlowSlides().then( success )
Get an array of the current presentation's core flow slides, the top row in the grid.
| Argument | Type | Description |
|---|---|---|
| callback | Function | A callback function invoked with one argument: (slides). The array of slide. |
returns : Promise
getCurrentPresentationManifest¶
Viewer.api.getCurrentPresentationManifest( callback )
Viewer.api.getCurrentPresentationManifest( ).then( success )
Get an array of the current presentation's core flow slides, the top row in the grid.
| Argument | Type | Description |
|---|---|---|
| callback | Function | A callback function invoked with one argument: (slides). The array of slide. |
returns : Promise
bringToFront¶
Viewer.api.bringToFront ( element )
Bring the content area that contains element to the front
If element is a child of the content area, the parent content area is brought to the front. If element is the content area, then element is brought to the front.
| Argument | Type | Description |
|---|---|---|
| element | DOMElement or JQuery | A DOM element or jQuery selector. |
sendToBack¶
Viewer.api.sendToBack ( element )
Send the content area that contains element to the back
If element is a child of the content area, the parent content area is send to the back. If element is the content area, then element is sent to the back.
| Argument | Type | Description |
|---|---|---|
| element | DOMElement or JQuery | A DOM element or jQuery selector. |
resetZIndex¶
Viewer.api.resetZIndex ( element )
Reset a content area that contains element back to its original layering before bringToFront or sendToBack were used
If element is a child of the content area, the parent content area is reset. If element is the content area, then element is reset.
| Argument | Type | Description |
|---|---|---|
| element | DOMElement or JQuery | A DOM element or jQuery selector. |
fullscreen¶
Viewer.api.fullscreen ( element )
Resizes the content area that contains element to fill the screen
If element is a child of the content area, the parent content area is resized. If element is the content area, then element is resized.
| Argument | Type | Description |
|---|---|---|
| element | DOMElement or JQuery | A DOM element or jQuery selector. |
exitFullscreen¶
Viewer.api.exitFullscreen ( element )
Resizes the content area that contains element back to its initial size
If element is a child of the content area, the parent content area is resized. If element is the content area, then element is resized.
| Argument | Type | Description |
|---|---|---|
| element | DOMElement or JQuery | A DOM element or jQuery selector. |
Deprecated Commands¶
The following ways of interacting with the Viewer have been deprecated. They are currently still supported, but you should change your code to use the new Viewer.api methods as these will be removed in a future release.
Viewer.trigger( commandName, arg1, arg2 )
Viewer.Commands.trigger( commandName, arg1, arg2 )
Tip
To upgrade to the new api simply replace the above format with
Viewer.api.commandName(arg1, arg2)
Navigating between presentations/slides¶
If conditional logic needs to be wrapped around navigation commands (this is not possible using the built in Open Slide action for content areas in iDetailAid) you can use the goToSlide api.
Warning
Hard coded slide and presentation id's will no longer work when content is copied into an affiliate region. The id's will change when being copied, but hard coded id's can not be updated as part of that process.
If you must use the goToSlide api call, then ensure your affiliate agencies change the slide ids once the content has been copied over to their region.
If you are building an HTML5 package, use custom events to wire up the navigation.
Please note: Before following this process, you must have created the presentation in the presentation tab of iDetailAid, and added to it the slide you want the user to navigate to.
First, make a note of the presentation and slide id
- Click the "Presentations" tab
- Select the presentation which includes the slide you want to navigate to
- Make a note of the presentation ID, which can be found in the address bar:
Presentation ID
- In the slide sorter at the bottom of the page, click on the slide that you want to navigate to
- Make a note of the slide ID, which can be found in the address bar
Slide ID
Then, the command can be constructed
Viewer.api.gotoSlide({slideId},[{presentationId}])
Note
presentationId is optional if you are navigating to a slide within the same presentation