PROVISIO DevBlog

Customizing the Portal Startpage

Of all designs/start pages that come equipped with SiteKiosk, the start page called "Portal Startpage" is one of the most popular ones. The major reason for that certainly is, that it covers a very common use case: the user can choose from a list of topics to proceed to a detail page that shows the relevant information. SiteKiosk users can already configure which links are to be shown, in which order and the corresponding icons as well as a suitable color scheme, background image  and several other options in the configuration program. For many cases this is already all that is needed, but sometimes you might need more control over the layout or visual appearance of the page.

All you need to know to get more control is how to open a file in an editor (for example Notepad), edit some text in it and save it.

The example I want to show here is how to set a solid background color instead of the default gradient background image. The file you need to change in order to accomplish this is located here C:\Program Files\SiteKiosk\Skins\Public\Startpages\Portal (depending on your system or the installation path you've chosen, it can be in a slightly different location) and it's called Start.html.

Before you proceed, as always, I recommend to first make a backup of the files you edit. To do that, select the file in the  Windows Explorer, choose "copy" from the context menu, right click on an empty area and choose "paste" (shortcut for that is CTRL + c for copy and CTRL + v paste).

Now open "Start.html" in a text editor, you can for example use Notepad ++ which is more comfortable or Notepad that comes with Windows. Search the line that starts with the following text and delete the complete line:

<img id="id_Background" ...

You can save the file now and run SiteKiosk to check the result. Notice that if you try to save the file directly under Windows Vista or Windows 7, it won't let you, because the file is located in a sub folder of your program files directory where you need more rights to write a file than the you have in the text editor. To work around this, you can copy the file to a different folder, make the changes and copy back to the original folder. Or you can start the text editor with administrator rights by right-clicking the program and choosing Run as Administrator from the context menu. 

In SiteKiosk you should see the portal startpage with a white background. This is the standard color if nothing else it specified, so if you like white, you are already done. If your page is about nature you might prefer green, then a little bit more has to be done.

Search for the line which starts with: <body, this is the tag that contains all content of this page . Inside this line, find style="..." (the style attribute) which defines the appearance of the page-body. Here you can add the color that should be used for the page-background. An example that sets the background color to green would be:

<body onselectstart="return false;" onload="Init();" style="margin: 0px;background-color: green">

Try not to change anything else from this line, just add background-color: green to the style attribute. This is because the code of this page could change in the next version of SiteKiosk.  Which values can you set for the background color? You can specify color names like above, check for example this page for a list of them: http://www.w3schools.com/html/html_colornames.asp. You can also specify color codes in RGB format, starting with a # (explained for example here http://www.w3schools.com/html/html_colors.asp). 

So now you can change the background color of the Portal Startpage. What else can be done? Everything that can be done in HTML/CSS/JavaScript and with the help of the SiteKiosk object model even more (for example accessing payment devices, browser windows, etc.). Check this blog for more examples in the future. 

Customize the SiteCaster Player in SiteKiosk

SiteKiosk (version 8.0 and higher) offers the possibilty to embed a SiteCaster player into an HTML page. You can then use this page as, for instance, a start page in SiteKiosk. If you only want to play your Digital Signage campaigns as scheduled in full screen, you can simply choose SiteCaster to play full screen in the SiteKiosk configuration tool under Start Page & Browser -> Digital Signage and you are ready to go.

If you want more control over the player, for example play certain campaigns in reaction to an event (like a button click), this is also possible, but requires a small portion of JavaScript in your page. I will describe here as an example how you can build a SiteCaster start page to play a certain campaign whenever the user clicks a button on the page.

First let's have a look at the basic HTML structure of a SiteCaster full screen start page. Please create a file named "SiteCasterCustom.html" and save it to the folder {Program Files}/SiteKiosk/Skins/public/Startpages/SiteCaster/ (the path to {Program File} depends on your installation of Windows). In the SiteKiosk configuration tool, set this file as the start page for SiteKiosk then.

<!DOCTYPE html>
<html>
<head>
</head>
<body scroll=no style="overflow:hidden; margin: 0; border: 0;">
	<object id="player" classid="clsid:719D9061-22DA-4D25-9BB9-116404372496" style="width: 100%;
		height: 100%; background: transparent;">
	</object>
</body>
</html>

This is just a standard HTML page with one object tag in the body (which has some styling to get rid of margins and border). This object tag embeds the SiteCasterPlayer into the page, so this is essential. In order to make some room for our button, we set the height of the object tag to "700px", so on a 720p screen (1280x720) we have 20 pixels left for the button. When we've added the button, the page looks like this:

<!DOCTYPE html>
<html>
<head>
</head>
<body scroll=no style="overflow:hidden; margin: 0; border: 0;">
	<object id="player" classid="clsid:719D9061-22DA-4D25-9BB9-116404372496" style="width: 100%;
		height: 700px; background: transparent;">
	</object>
	<button id=playButton>Play it!</button>
</body>
</html>

This is our markup for this example, now we add a script to achieve the event handling. First we need to load a script that exposes the SiteCaster player functionality in a convenient way. This script in turn requires one other script that should be included before with a script tag.

<!DOCTYPE html>
<html>
...
	<button id="playButton">Play it!</button>
	<script src="../../External/require.js"></script>
	<script>
		require.config({
			baseUrl: "../.."
		});
		require(['Scripts/SiteCaster'],
				function (context, siteCaster) {

					var player = siteCaster.Player();

					player.broadcastLoaded(function () {
						
					});
				});
	</script>
</body>
</html>

At first glance this might seem a bit overly complex, but it is actually quite simple. The SiteCaster script (which has the file name SiteCaster.js) is using an API called RequireJS (http://requirejs.org) to load dependent scripts, so require.js has to be loaded first (this is the first script tag). After that the RequireJS functionality can be used.

RequireJS first needs a base URL to properly resolve the script paths, so we set it by using the require.config function. This base URL must point to the directory where the two folders "Scripts" and "External" reside. Going from the folder where the standard SiteCaster start page is located, this is two levels up (../..). 

Next we can call the require function itself to load our dependent scripts (in this case it is only SiteCaster.js). It excepts as a first argument an array of script paths that should be loaded. Going from the set base URL, the path to SiteCaster.js is "Scripts/SiteCaster". The file extension ".js" must be omitted, otherwise RequireJS will interpret the name differently.

The second argument is a function that will be called when all dependent script have been loaded. The first parameter to this function is a context object which we don't need here. The second is the siteCaster object that we will use.

Now that we have the SiteCaster object, we can ask it to give us a Player object. Since there can be more than one player on the same page, the ID of a specific object tag can be provided as an argument, but in this case we have only one and we let the SiteCaster script find it automatically. One last thing is missing before we can begin to use the player functionality: we have to make sure the player has loaded the active broadcast. So we set a function that is called when this happens with broadcastLoaded.

Inside this last function we now have full control over the SiteCaster player. In this example we want to play a different campaign, whenever the user clicks a button, so we set the onClick function of the button to a new function. Inside this onClick handler function, we need to find a certain campaign of the current broadcast and call play with it. So we call getCampaignItems() to get all campaign items of the currently playing broadcast. We assume here that the broadcast contains a campaign item with the name "ClickCampaign", which we want to play now. 

 

require.config({
			baseUrl: "../.."
		});
		require(['Scripts/SiteCaster'],
				function (context, siteCaster) {

					var player = siteCaster.Player();

					player.broadcastLoaded(function () {
						playButton.onclick = function () {
							var campaignItems = player.getCampaignItems();
							var i = 0;
							for (; i < campaignItems.length; ++i) {
								if (campaignItems[i].Name == "ClickCampaign") {
									player.play(campaignItems[i]);
								}
							}
						}
					});
				});

As you can see, we just loop through all campaign items until we find the one with the correct name and play it. The item will play once and after that the normal schedule will take over again. If you want to play the Campaign multiple times in a row, you have to play it again, when it ends. The code for that would like like this (only the onclick handler):

playButton.onclick = function () {
	var campaignItems = player.getCampaignItems(),
		i = 0,
		playCount = 0,
		clickCampaignItem;

	for (; i < campaignItems.length; ++i) {
		if (campaignItems[i].Name == "ClickCampaign") {
			clickCampaignItem = campaignItems[i];

			player.campaignEnd(function (id) {
				if (id === clickCampaignItem.Id && playCount < 4) {
					player.play(clickCampaignItem);
					playCount += 1;
				}
				else
					player.setAutoSchedule(true);
			});

			player.setAutoSchedule(false);
			player.play(clickCampaignItem);
		}
	}
};

Note that we call player.setAutoSchedule(false) to switch off the scheduled playing of the broadcast. This way we get complete control and scheduled (not disabled) campaigns won't kick in in between. After our click campaign has played four times we call player.setAutoSchedule(true) and campaigns are played according to the set schedule again (the ones that are not disabled). 

The complete HTML file containing the example script is attached to this entry, so if you have SiteKiosk 8 installed and want to try it out, just save it into the folder  {Program Files}\SiteKiosk\Skins\Public\Startpages\SiteCaster and set this as a start page in the SiteKiosk configuration tool. Make sure you create at least two campaigns in your broadcast and disable one of them (the one you want to play when the button is clicked) under "Schedule" in the SiteCaster tab in SiteRemote.

 

SiteCasterCustom.html (1.36 kb)