Display API: HTML & Document Display
The External Screen API will display several document formats, including .html pages and .pdf.
If storing files directly on the device when using API calls, files on the device are referenced relative to Kiosk Pro's Documents folder.
Before calling any of the functions below, you must use the API to trigger a full-screen connection to the external display.
Functions
Callbacks
Requirements
- Access JavaScript API
- 'By Import' - recommended, works both online & offline, requires inclusion of kiosk_functions.js prior to any of the following calls.
- 'By Injection' - only works offline, may not be available 'onload' event.
- Screensaver
- External Monitor Mode = Interactive or Standard Mirroring
- Connection to an External Display
- iOS device must be connected to an external monitor, screen or projector via AirPlay or through Apple's Digital AV Adapter (which creates a wired connection betweeen an HDMI port on the external display and your device's 30-pin or Lightning port).
Sample Code
kp_ExternalScreen_setBrowserBgColor
This function sets fade duration and the background color or image shown during video fade in and fade out. This background color or image is also shown if the video file is not proportioned to fit the screen dimensions.
Format | kp_ExternalScreen_setBrowserBgColor(bgColor, callback); |
Parameters |
|
Callback format | callback(success); |
Callback return values |
|
Status
You can also verify that background was successfully set by calling kp_ExternalScreen_getBrowserBgColor.
kp_ExternalScreen_getBrowserBgColor
This function triggers a callback returning current fade duration and the background color or image shown during video fade in and fade out.
Format | kp_ExternalScreen_getBrowserBgColor(callback); |
Parameters | callback = callback name as a string. |
Callback format | callback(bgColor); |
Callback return values |
|
kp_ExternalScreen_openDocument
This function opens the document specified by the 'filePath' parameter on the external display.
If referencing a locally stored file, the file path is relative to the Kiosk Pro documents folder. If referencing a remotely stored file, use the full URL. If the app cannot find the file at the specified path, then the method will fail.
Format | kp_ExternalScreen_openDocument(filePath, сallback); |
Parameters |
|
Callback format | callback(jobWasAccepted); |
Callback return values |
|
Discussion
Although in theory, as a document, you could use an HTML file with an embedded video player, we strongly recommended against this as it can lead to inconsistent results. Instead, we recommend using kp_ExternalScreen_playVideo to trigger video playback on the external display.
kp_ExternalScreen_doJScript
This function triggers another JavaScript call on the .html page currently displayed on the external screen, which can be used to update content or trigger an action.
Format | kp_ExternalScreen_doJScript(script); |
Parameters | script = JavaScript function to be called on the page being displayed. |
Example
This example in the sample code above (referenced under 'JavaScript Call Demo') uses the 'onload' event to connect to the external screen and display an .html page, requiring that you access the JavaScript API 'By Import' and include 'kiosk_functions.js' prior to these calls. It then displays buttons triggering the following functions to change the background color of the page shown on the external display:
function changeBackgroundPink() { window.kp_ExternalScreen_doJScript('document.body.style.background ="#F6F";'); } function changeBackgroundAqua() { window.kp_ExternalScreen_doJScript('document.body.style.background ="#6FF";'); }
kp_ExternalScreen_requestNumberOfPdfPages
This function returns the number of pages in the PDF document currently being displayed on the external screen.
Format | kp_ExternalScreen_requestNumberOfPdfPages(callback); |
Parameters | callback = callback name as a string. |
Callback format | callback(numberOfPages); |
Callback return values | numberOfPages = integer variable indicating the total number of pages in current PDF document. For other types of documents, this method always returns 0. |
kp_ExternalScreen_requestNumberOfCurrentPdfPage
This function which returns the current page number of the PDF document currently being displayed on the external screen.
Format | kp_ExternalScreen_requestNumberOfCurrentPdfPage(callback); |
Parameters | callback = callback name as a string. |
Callback format | callback(pageNumber); |
Callback return values | pageNumber = integer variable indicating the page number of page being displayed in the current PDF document. For other types of documents, this method always returns 0. |
kp_ExternalScreen_showPdfPage
This function which displays the specified page of the PDF document currently being displayed on the external screen. For other types of documents, this method does nothing.
Format | kp_ExternalScreen_showPdfPage(pageNumber, callback); |
Parameters |
|
Callback format | callback(success); |
Callback return values | success = integer variable, if 0 - then specified page was not shown, otherwise - shown. |
kp_ExternalScreen_didOpenFileSuccessfully
This callback is triggered when a request to open a document on the external screen is called and the document opens successfully.
Format | kp_ExternalScreen_didOpenFileSuccessfully(sourceDocumentPath, usedDocumentPath); |
Return Values |
|
kp_ExternalScreen_didOpenFileWithError
This callback is triggered when a request to open a document on the external screen is called and the document fails to load.
Format | kp_ExternalScreen_didOpenFileWithError(sourceDocumentPath, usedDocumentPath, error); |
Return Values |
|