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
  • 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

This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.  
To run sample code, set the app's homepage to  http://www.kioskproapp.com/external-screen

Download 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
  • bgColor = background color or image to be shown on the external display prior to a document being opened or if a document does not fill the screen. Can be set as:
    • R,G,B = background color set as R,G,B: [0..255] (i.e '255,0,0' = red).
    • image file = file path to the desired video file. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function). If remote, this should be the full URL.
  • callback = callback name as a string.
Callback format 
callback(success);
Callback return values
  • success = integer variable which indicates background was successfully updated. Possible values are:
    • 0 = the method failed.
    • otherwise = success.

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
  • R,G,B = background color set as R,G,B: [0..255] (i.e '255,0,0' = red).
  • image file = file path to the desired video file. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function). If remote, this should be the full URL.

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
  • filePath = file path to the desired file. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function). If remote, this should be the full URL.
  • callback = callback name as a string.
Callback format 
callback(jobWasAccepted);
Callback return values
  • jobWasAccepted = integer variable which indicates that the external display is linked and returned no errors. Possible values are:
    • 0 = indicates an external display is not linked.
    • 1 = indicates external display is linked and returned no errors. Please note, even if this returns 1, it is not guaranteed that the external display showed content properly (if, for instance, path to the content was set incorrectly or content does not exist).

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
  • pageNumber = integer variable indicating the number of the page which should be shown. Should belong to the set [1..N] where N = max page number (which can be queried using kp_ExternalScreen_requestNumberOfPdfPages.
  • callback = callback name as a string.
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
  • sourceDocumentPath = the filepath the user entered.
  • usedDocumentPath = the filepath Kiosk Pro uses. For example, if a user sets a path to a local PDF that doesn't exist Kiosk Pro will transform it to a remote URL by adding 'http://'.

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
  • sourceDocumentPath = the filepath the user entered.
  • usedDocumentPath = the filepath Kiosk Pro uses. For example, if a user sets a path to a local PDF that doesn't exist Kiosk Pro will transform it to a remote URL by adding 'http://'.
  • error = returned as an associate array: {‘domain’:value, ‘code’:value, ‘description’:value, 'failureReason':value, 'recoverySuggestion':value, 'debugDescription':value}
  • domain = where the error occurred.
  • code = an identifier for the error.
  • description = a brief description of the error.
  • failureReason [optional, may return as empty] = a reason for the error.
  • recoverySuggestion [optional, may return as empty] = a suggested solution.
  • debugDescription [optional, may return as empty] = a detailed description of the error.

Still stuck? How can we help? How can we help?