PROVISIO DevBlog

Manipulating the DOM within the SiteKiosk Windows Chrome Browser

Editing the DOM of a website displayed in the Chrome Browser of SiteKiosk Windows (please have a look here for the Internet Explorer browser of SiteKiosk) can be easily achieved by adding the DOM manipulation script to the file C:\Program Files (x86)\SiteKiosk\SiteKioskNG\assets\customScriptExtension.js.

The file is empty be default and will be executed for every webpage displayed in the Chrome Browser of SiteKiosk Windows. You should therefore make sure to add script code to identify the page you want to manipulate.

The DOM manipulation does not require SiteKiosk specific script code. Plain Javascript can be used.

The following example code edits the main search page of Google to include SiteKiosk as the search term and to change the text of the Search button to "Search for SiteKiosk". Note that the code already does a basic check, if the website is a Google website before it executes the rest of the Javascript code.

if (document.URL.indexOf("https://www.google.") !== -1) {
	document.addEventListener('DOMContentLoaded', documentLoadedFunc);
}

function documentLoadedFunc(e) {
	document.getElementsByName('q').item(0).value = "SiteKiosk";
	document.getElementsByName('btnK').item(1).value = "Search for SiteKiosk";
}

Just copy and paste the above example script to the file C:\Program Files (x86)\SiteKiosk\SiteKioskNG\assets\customScriptExtension.js and then start SiteKiosk with a basic configuration file. Open google.com. The result of the example DOM manipulation will look like this:

Note that when using the above example you should make sure to take care of local laws, ownership rights, copyright etc. Also note that the above example only works as long as Google does not change the code of their page.

Starting an External Application from a SiteCaster Project

In case you want to start an external application from your SiteCaster project, you need to switch to the SiteCaster expert mode.

Open the project in the SiteCaster editor. In the URL address field of your browser you must add &expert at the end of the URL and then press Enter to reload the project.

After activation of the expert mode you see the pen button in the menu bar. Now create an image (note that this will work with most other elements as well) on your project page, select the image and press the expert mode pen button. You can resize the inspector on the right via drag and drop to access the following lines easier.

Go to additionalLink and select JSON object in the dropdown menu. Then replace “image” with “script” in the text field.

Next go to linkActive to select Boolean from the dropdown menu and check the checkbox.

Finally go to scriptSource, select String and add the following line for SiteKiosk Windows with the path to the desired application
siteKiosk.system.windows.skLegacy.externalApps.run("PathToYourApplication", false);
to the scriptSource text field, e.g.
siteKiosk.system.windows.skLegacy.externalApps.run("C:\\Program Files\\Notepad++\\notepad++.exe", false);

Please note that from SiteCaster 1.5 the command is much shorter: siteKiosk.system.run("C:\\Program Files\\Notepad++\\notepad++.exe", false);
In both cases the second parameter of the run function is a boolean value that needs to be false if an existing instance of the application should be focused instead of opening a new one and true if an additional instance should be opened.

Should the scriptSource property not be available, scroll down to Add property and add it there by filling out the fields and hitting the plus button, e.g.:

It is strongly recommended to also add your external application in the SiteKiosk configuration under Applications so that SiteKiosk can close the application when the screensaver is activated.

Once the project is published to the client, a click on the element will open the application.

The above is the notation to make it work under SiteKiosk Windows. For SiteKiosk Android it is slightly different. In order to start the application you need to know its guid name, e.g. com.android.calculator2. Either you know this information for the app you would like to start or you can use the SiteKiosk logs to find this information. To do so, just add the desired app in the SiteKiosk configuration under Application -> Android App or Application -> Multiple Applications. Next start SiteKiosk and make sure the app has started at least once. Now close SiteKiosk and open the SiteKiosk log file in the ..\SiteKiosk\Logs folder. Look for an entry with the text System app launched, e.g. System app launched: com.android.calculator2. In our example the guid name we are looking for is com.android.calculator2. This information is required to start that specific app from SiteCaster.

With this information gathered we can compose the line that needs to be added as the scriptSource in SiteCaster to look like this:
siteKiosk.system.apps.getByGuid("com.android.calculator2").launch("", "systemApp");

Please note that you need to add the app in the SiteKiosk Android configuration under Security -> Allow assigned apps, if it is not addd there it will be blocked.

How to Rearrange the Layout of the SiteKiosk Chrome Browser

Here is a quick way to completely move around the main parts of the SiteKiosk Chrome browser. This for example can be used to show the tool bar not at the top but at the bottom.

Open the file C:\Users\Public\SiteKiosk\data\content\local\files\projects\d97aa96b962543fcb39625a3f8e8d8fb\000000000000000000000000\content.json with an editor, e.g. Notepad. And look for the lines

"templates": {
	"main": {

A few lines below you will see the start of the elements segment, that by default lists the element with the name topContainer first.

"elements": [
	{
		"type": "content-container-linear",
		"name": "topContainer",
		...
		"_editor_propertiesToEditRestrictedUser": {}
	},
	{
	...

There are 6 elements that can be separated by their names. In an unedited content.json file the order is topContainer (this element represents the tool bar), tabBarContainer (this element represents the tab bar), loadProgress (this element represents the progress bar), tabPageArea (this element represents the area where web pages are rendered), surfTimeContainer (this element is for internal use only) and popupWindow (this element represents the popups used for the zoom and language selections of the tool bar).

The 4 elements topContainer, tabBarContainer, loadProgress and tabPageArea are those that can be rearranged to change the overall look of the browser. The other two elements can be left untouched.

All element definitions are in the same order in the JSON document as they appear on the screen if you start SiteKiosk. To reposition an element you simply have to move its complete definition from opening bracket ({) to closing bracket (}) to the new place you would like the element to have on the screen.

If the elements are rearranged in the order tabPageArea, loadProgress, tabBarContainer, topContainer and the content.json file is saved, you will see this user interface when you start SiteKiosk:

Note that depending on how you reposition the elements and the SiteKiosk configuration you are using, there may be minor side effects, e.g. overlapping parts. Also note that the task bar of the SiteKiosk Chrome browser is not part of the content.json file, it can be found in this folder instead C:\Program Files (x86)\SiteKiosk\Skins\Chrome_NG_Skin.

Different Methods for Showing PDF Files with SiteCaster

The default method for showing PDF files with SiteCaster is the "linked document (pop-up)" method. This is available as a basic property of standard elements, e.g. an image. Once you click the element a closable pop-up opens, that shows the PDF. Note that on Android devices a PDF file will be opened full screen and not as a pop-up.

For example you could create a new image element for a content layer.

Then you would edit the linked document (pop-up) property and assign a PDF file.

Another method is to use the webpage element to display a PDF file. The PDF file can be located on the Internet or locally on the machine.

If the file is stored locally and you are using the file:// protocol, it is recommended to put the file into the html subfolder of your SiteKiosk installation folder, e.g. C:\Program Files (x86)\SiteKiosk\Html. Otherwise make sure that the location is accessible by changing the SiteKiosk surfing area settings.

When using the webpage element you can set the size properties to show the PDF full screen (again, note that the linked element option will already have this effect on Android devices). You can also use the parameters specified by Adobe to control the display of the PDF element. Just attach them to the URL as described in the Adobe document.

If you are using the webpage element, please keep in mind, that the PDF files will not be included when the content is distributed to the clients. The files must exist at the specified location for the client to be able to show them. For local files one option is to use the file synchronization of SiteRemote. The disadvantage to that is that you have to use both SiteCaster and file synchronization. The other option for local files is to use a little 4-step trick that enables you to only use SiteCaster to distribute the PDF files, even though you are using the webpage element.

1. Create an element with a linked PDF document as usual (see above).

2. Use the preview of the SiteCaster CMS editor, to note which internal file name is used in SiteCaster for the pdf. With Firefox use the download button at the top bar to get the download dialog with the file name, with Chrome just do a right mouse click on the PDF Display and then choose "Save as…".



3. Go back to the SiteCaster CMS Editor and set the element with the linked document to "Do not display (only visible in editor)" in the "Display conditions" settings of that element. This will essentially hide the original PDF file.


4. Now create a webpage element and add the following URL with the internal file name of the PDF identified in step 2:
http://localhost:8889/files/[internalfilename].pdf (e.g. http://localhost:8889/files/5c38667034427b1417f3229f_5c38667034427b1417f322a0.pdf)

That's it, now the PDF is distributed as SiteCaster content to the client and you can use the webpage element features like making the file full screen and using parameters to control how the PDF file is displayed.

How to Encrypt SiteRemote Server to SQL Server Connections

If you want to encrypt the connection between your SiteRemote Server and the Microsoft SQL Server hosting the database for SiteRemote, especially when using a remote Microsoft SQL Server, you can just enable forced encryption in the settings of your Microsoft SQL Server. This enables basic encryption between the two servers. To learn how you can enable encryption for your Microsoft SQL Server please refer to the documentation of the SQL Server provided by Microsoft.

The above enables encryption but does not protect from man-in-the-middle attacks on the connection. If you need this additional layer of security, configure your Microsoft SQL Server to use a certificate and make sure the machine running the SiteRemote Server trusts the certificate. Please refer to the SQL Server documentation provided by Microsoft for the SQL Server version you are using to configure this setup. Once this is done, you need to change the connection string used by SiteRemote to connect to the SQL Server. Note that this change can only be done after SiteRemote has been installed.

Open the file ..\PROVISIO\SiteRemote\Config\SiteRemoteServer.config from your SiteRemote installation folder with an editor and look for lines similar to this example:

<ConnectionStrings>
	<Add Name="default" Encrypted="true">
		<ConnectionString>Data Source=sql.server;Initial Catalog=SiteRemoteBackEndServer;User ID=sa;Password=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</ConnectionString>
	</Add>
</ConnectionStrings>

You need to add encrypt=true and trustServerCertificate=false (true would not validate the certificate) to the connection string. The above example would look like this with the additional settings added:

<ConnectionStrings>
	<Add Name="default" Encrypted="true">
		<ConnectionString>Data Source=sql.server;encrypt=true;trustServerCertificate=false;Initial Catalog=SiteRemoteBackEndServer;User ID=sa;Password=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</ConnectionString>
	</Add>
</ConnectionStrings>

Limiting the Color Mode for VNC Connections

Please note that the following text is an updated version of this older post. The update applies to SiteRemote 5.1 and above (including version 6.1, which is the current version at the time of writing this post).

SiteRemote uses the auto mode to set the colors for the VNC session. This usually provides the best experience. You may like or need to limit the color mode to 256 colors only when establishing the connection, mainly because of poor connection speed.

To switch from auto mode to 256 colors you need to edit a file on the PC you are establishing the connection from. On this PC you have installed the UVNC client for SiteRemote, it is usually located in the path C:\Program Files (x86)\PROVISIO\VncViewer\. There you can find the file options.vnc. Please open the file with an editor like Notepad. You will see that there is not much in it:

[connection]
index=

These lines need to be added to the file:

[options]
autoDetect=0
QuickOption=0

The complete file should now look like this:

[connection]
index=
[options]
autoDetect=0
QuickOption=0

Save the file under its original name. Next you need to right-click the file, choose Options -> Security and give the default Windows Users group read and write access to the file.

When you now start your next VNC session it will default to just 256 colors, therefore speeding up the view on a slow Internet connection.

Note that independent from this change you can always edit the options of a running VNC connection by clicking the Options button in the upper toolbar of the VNC window. This allows you to make one-time changes to the current connection.

How to Reposition Buttons in the SiteKiosk Windows Chrome Browser Toolbar

There are many customization options for the SiteKiosk Windows Chrome Browser Toolbar. Both by simply using the configuration tool of SiteKiosk to enable or disable buttons or to change the colors as well as by editing files to give the toolbar a new look. There are several blog posts that deal with this topic, e.g. here and here. This time we are going to learn how to reposition buttons in the toolbar.

As an example, we will move the logout button from the left side of the language selection button the the right side. To do that, we need to open and edit a JSON (JavaScript Object Notation) file that is used by the Chrome Browser of SiteKiosk Windows. The file content.json is located in the folder C:\Users\Public\SiteKiosk\data\content\local\files\projects\d97aa96b962543fcb39625a3f8e8d8fb\000000000000000000000000. Open it with an editor like Notepad++. It is suggested that you make a backup copy of the file before editing it.

The buttons are defined in a number of attribute-value pairs that look like this for the logout button:

{
	"type": "content-button",
	"title": "{{$root.stringTable.strings.buttons.logout.$}}",
	"name": "logoutButton",
	"height": "60px",
	"width": "60px",
	"marginLeft": "0px",
	"marginRight": "0px",
	"_editor_canBeSelected": true,
	"_editor_canBeEdited": true,
	"_editor_canBeDeleted": true,
	"_editor_canAdd": true,
	"layout": {
	},
	"icon": {
		"src": "files/images/logout.svg",
		"color": "[[$root.colors.toolbarButton.icon]]",
		"hoverColor": "[[$root.colors.toolbarButton.iconHover]]",
		"pressedColor": "[[$root.colors.toolbarButton.iconPressed]]"
	},
	"backgroundImage": {
		"src": "files/images/button_background.svg",
		"color": "[[$root.colors.toolbarButton.background]]",
		"hoverColor": "[[$root.colors.toolbarButton.backgroundHover]]",
		"pressedColor": "[[$root.colors.toolbarButton.backgroundPressed]]"
	},
	"action": {
		"target": "{{%main}}",
		"value": "logout"
	},
	"_editor_propertiesToEdit": {
		"applyToAllContentGroups": true,
		"flex": true,
		"margin": true,
		"text": true
	},
	"_editor_propertiesToEditRestrictedUser": {}
},

And like this for the language selection button:

{
	"type": "content-button",
	"title": "{{$root.stringTable.strings.buttons.languages.$}}",
	"name": "languagesButton",
	"height": "60px",
	"width": "60px",
	"marginLeft": "0px",
	"marginRight": "0px",
	"_editor_canBeSelected": true,
	"_editor_canBeEdited": true,
	"_editor_canBeDeleted": true,
	"_editor_canAdd": true,
	"layout": {
	},
	"icon": {
		"src": "files/images/flags.png",
		"height": 32,
		"width": 32
	},
	"outlineImage": {
		"src": "files/images/circle.svg",
		"color": "[[$root.colors.toolbarButton.icon]]",
		"hoverColor": "[[$root.colors.toolbarButton.iconHover]]",
		"pressedColor": "[[$root.colors.toolbarButton.iconPressed]]"
	},
	"backgroundImage": {
		"src": "files/images/button_background.svg",
		"color": "[[$root.colors.toolbarButton.background]]",
		"hoverColor": "[[$root.colors.toolbarButton.backgroundHover]]",
		"pressedColor": "[[$root.colors.toolbarButton.backgroundPressed]]"
	},
	"action": {
		"target": "{{%main}}",
		"value": "showLanguages"
	},
	"_editor_propertiesToEdit": {
		"applyToAllContentGroups": true,
		"flex": true,
		"margin": true,
		"text": true
	},
	"_editor_propertiesToEditRestrictedUser": {}
},

As you can see, the different buttons can be easily identified by the name attribute. All button definitions are in the same order in the JSON document as they appear on the screen if you start SiteKiosk. To reposition a button you simply have to move its definition to the new place you would like the button to have on the screen. In the case of the logout and the language selection button you would simply have to move the complete logout definition shown above behind the definition of the language selection button, also shown above.

This change results in the logout button being shown behind the language selection button, as pictured here:

Please note that you can easily change the general appearance of the SiteKiosk Windows Chrome Browser through the SiteKiosk configuration. Just go to Start Page & Browser -> Chrome Browser -> Customize -> Browser Toolbar. Here you can show/hide the different buttons and also change the overall display size of the toolbar. You can also add custom buttons, if you need more than 2 of those, please have a look here.

Using the Expert Mode of the SiteCaster Editor

The SiteCaster Editor comes with an expert mode, that allows you to edit settings beyond their default value range. This gives you the opportunity to customize your projects to match very specific requirements. Feel free to experiment with this mode, but be aware that changing values beyond their default range is outside of the scope of our free support.

To enter the expert mode open a project to view the project page. Now click the address bar of your browser and append &expert to the URL. Make sure you place it at the very end of the URL and then press enter to open the expert mode.

Next select the element you want to customize. In our example we want to adjust the font size and the font family of the Time/Date element. To do that, click on the new advanced edit button you will see in the toolbar after entering the expert mode.

After clicking the button you will see a list of all properties of the selected element in the inspector. In the list you will find the dateFontFamily and dateFontSize properties. Use the drop-down of the dateFontFamily property to select String and type in the font family of your liking into the text field. For the dateFontSize property select Number from the dropdown and then type in the pixel value you want to choose. Click on the Save button after you are done to apply the changed values.

To give you an idea of the advanced possibilities you get from choosing the expert mode here is a view of the default options you have for the Time/Date element.

 As you can see the default element will cover the needs of most users but when using the expert mode you can change the properties to whatever you like.

Starting an App from a Web Page in SiteKiosk Android

The SiteKiosk Android Object Model can be used to start any Android app available on a device from a web page. This can be used for example to create a fully individualized start page for SiteKiosk Android or to start an application after providing a password. Note that a SiteKiosk Android Object Model documentation is not publicly available yet but a preliminary version can be obtained by contacting PROVISIO support.

In order to start the application you need to know its guid name, e.g. com.android.calculator2. Either you know this information for the app you would like to start or you can use the SiteKiosk logs to find this information. To do so, just add the desired app in the SiteKiosk configuration under Application -> Android App or Application -> Multiple Applications. Next start SiteKiosk and make sure the app has started at least once. Now close SiteKiosk and open the SiteKiosk log file in the ..\SiteKiosk\Logs folder. Look for an entry with the text System app launched, e.g. System app launched: com.android.calculator2. In our example the guid name we are looking for is com.android.calculator2. This information is required to start that specific app from the code of the web page.

The example HTML code to start the app looks like this:

<!DOCTYPE html>
<html>
<head>
<script>
	//method to initialize the SK Object Model as of SKA 2.5 or higher
	(new Function(_siteKiosk.getSiteKioskObjectModelCode()))();
</script>
<script>
    function startApp() {
        //make sure the SiteKiosk Android Object Method is ready
		siteKiosk.ready(function() {
			//start the Android app by its Guid name
			siteKiosk.system.apps.getByGuid("com.android.calculator2").launch("", "systemApp");
		});
    }
</script>
</head>
<body>
	<button onclick="startApp()">Start App</button>
</body>
</html>

The method _siteKiosk.getSiteKioskObjectModelCode initializes the SiteKiosk Android Object Model. The siteKiosk.ready method makes sure that the SiteKiosk Object Model is ready for use. If that is the case, siteKiosk.system.apps.getByGuid accesses the app and the launch method is used to start it (the default parameters for launch, "" and "systemApp", should be left as is).

Of course you need to change the guid name from the above example (com.android.calculator2) to the guid name of your app for the getByGuid method.

Save the complete code as an html file and place it either locally on the Android device or on a web server. For the purpose of testing you can set the file as the start page of the SiteKiosk Android Browser Application.

You also need to give the html file script permission, so it is allowed to use the SiteKiosk Object Model. Do this under Application -> Browser (or Fullscreen Browser) -> Script permission.

Finally you need to add the app you want to start under Security -> Allow assigned apps.

Changing the Date and Time Format in Chrome Browser of SiteKiosk Windows

When using English as the language setting for the Chrome Browser of SiteKiosk Windows the time is shown in AM/PM format and the date is shown as Month/Day/Year. To change that a quick file edit can be done.

Open the file ..\SiteKiosk\Skins\Chrome_NG_Skin\TrayWnd.html with an editor, e.g. Notepad. Look for these lines:

} else {
	// US
	curDateStr = "" + (curDate.getHours() > 12 ? utils.ensureTrailing0(curDate.getHours() - 12) : utils.ensureTrailing0(curDate.getHours()));
	curDateStr += ":" + utils.ensureTrailing0(curDate.getMinutes(), true);
	curDateStr += (curDate.getHours() >= 12 ? " PM" : " AM");
	curDateStr += "<br />"+utils.ensureTrailing0(curDate.getMonth()+1)+"/"+utils.ensureTrailing0(curDate.getDate())+"/"+utils.ensureTrailing0(curDate.getFullYear());
}

Change the code to:

} else {
	curDateStr = utils.ensureTrailing0(curDate.getHours()) + ":" + utils.ensureTrailing0(curDate.getMinutes(), true);
	curDateStr += "<br />"+utils.ensureTrailing0(curDate.getDate())+"/"+utils.ensureTrailing0(curDate.getMonth()+1)+"/"+utils.ensureTrailing0(curDate.getFullYear());
}

The first line displays the time, the second is the date. Both are assigned to the same variable by way of string concatenation. The string basically contains html code to display the time and date section. Feel free to make changes as you wish.

The above example will change the time and date display to this: