KioWare Design Guide (Programming)

Although KioWare is designed to handle any web content, there are certain design considerations that will optimize the utility and performance of your kiosk application.

Attract Screens

Although most useful for kiosk applications, even a corporate intranet application may want to use attract screens to ensure session control.

A typical kiosk application will have a number of pages that periodically display on the screen when the kiosk is not in use.  Their purpose is to catch a potential user's attention and direct them to the kiosk.  As soon as they initiate user input (touchscreen, mouse or keyboard) then either the Start Page URL (homepage of your application) will display or the Attract Screen URL will become live.  The latter is useful for advertising applications where each attract screen ad doubles as the entry point into the application for more information.

Rather than having to worry about writing code to handle the timers necessary to know when to switch between screens, when the kiosk has been inactive long enough to switch into attract screen mode, and finally to determine which screen to display next, KioWare handles these tasks automatically.  Attract Screens are defined using the Configuration Tool - see KioWare User Guide.

Even if you don't plan to use attract screens, you should still define an inactivity timer.  This way, your application will reset to your home page and can be used to force a new user session.

Title Tags

Although your application is written using HTML and the display of the content is via Microsoft Internet Explorer, the browser is configured so that it doesn't appear to the user to be a browser.  Status bars, toolbars and title bars are not displayed, and scrollbars are optional.  Since the title bar is not displayed, we have leveraged this feature to extend the functionality of our usage logging.  Not only do we log the URL of each page loaded, but we also log the title.  The title can be used to make the analysis of the usage logs more meaningful.  In addition, the title tag can be embedded with optional class information to enable aggregation and separation of log entries.  Note: this feature is only available if you have enabled usage logging - see KioWare User Guide.  The syntax of this title tag becomes:

When the titles are processed by KioWare Server, the class information is stripped out of the title and stored separately.  This enables log data to be queried and aggregated by each individual class or by all classes.  For example, you could see how many people looked at the Seattle Information page in English, how many in Spanish, how many in Japanese, and how many overall.

Another way to use the title tags is to embed user information into the log file.  For example, an HR application may want to know who was looking at which pages.  This is easily accomplished using class information.  For example, let's assume the employee has already logged on and their employee ID is stored in a session variable called ‘EmpID'.  The following ASP will create HTML that will log the employee's ID visit on the 401k distribution page:

Scroll Bars

A typical web application must be designed for the entire universe of hardware and software of its target audience.  Certainly, it can be optimized for a certain display resolution or browser version; however, effort must still be expended to ensure the site displays properly on a cross-section of PCs.  A kiosk application is the exact opposite because you control the PC that hosts the application; therefore, you can define hardware requirements such as the screen resolution and software configuration such as the size of scrollbars (Windows Desktop Display Properties).  Typically in a kiosk application, scroll bars are to be avoided for ease-of-use reasons.  This is especially true for horizontal scroll bars, but also true for vertical scrollbars in a touchscreen only application.  However, when necessary it is important that they be large enough for touchscreen applications.  Note: an alternative to a scrollbar are the scroll up and scroll down buttons in KioWare's toolbar.

Vertical and horizontal scrollbars can be turned on or off using the Configuration Tool - see KioWare User Guide; however, it is important to realize that even if scrollbars are turned off, the browser still reserves screen space to display them.  Essentially, turning scrollbars off merely hides them, but they still take up screen real estate, and you need to take this into account when designing your pages.  If you control the content, you can turn off scrollbars by using the Scroll=no parameter in the HTML Body tag.  Doing this will prevent screen display space being taken by an invisible scrollbar.

Keyboard Filtering

If your kiosk will contain a keyboard, you need to determine which special keys (functions keys, print screen, ctrl, alt, etc) are on the keyboard, which keys are necessary for your application and then use the Configuration Tool (see KioWare User Guide) to lock out the remaining keystrokes.  If the ctrl, alt and delete keys are on your keyboard you will, at a minimum, want to lock out ctrl-alt-delete.  Otherwise, a user could exit to the desktop at will.

Virtual Keyboard

For applications that require keyboard input but there is no physical keyboard, KioWare can provide a virtual HTML popup keyboard.  KioWare ships with several general purpose virtual keyboards that can be modified as is necessary.  The KioWare installed virtual keyboards are located in [InstallDir]/KioWare/virt_kbd/.

Or, a completely different HTML popup virtual keyboard can be used.  There are only a few design rules to follow if creating a custom virtual keyboard.

There are two styles of virtual keyboard:

• Phrase Input - A virtual keyboard that stores the keys pressed in a textbox on the virtual keyboard and uses an Enter button to close the virtual keyboard and transfer the data back to the application
• Key Input - A virtual keyboard that immediately transfers the key pressed to the application and after all keys have been pressed uses a Close button to close the virtual keyboard and transfer control back to the application

• Current value of INPUT/TEXTAREA element is passed to the virtual keyboard via a querystring variable named: Value.  Ex, ?value=123456789
• The virtual keyboard must write its results to a INPUT/TEXTAREA element named “Keyboard”.
• When the virtual keyboard wants to close, it must set an INPUT element (typically hidden) named “CloseMe” to value “yes”.  This element is checked by KioWare after every mouse click on the virtual keyboard.
• If the INPUT element in the application is a PASSWORD type, the virtual keyboard will be passed a querystring variable named ‘pw' set to a value of 1, so that the virtual keyboard code can read the variable and also display a password textbox.  Ex, ?value=123456789&pw=1

• Virtual keyboard must have a hidden element named "EchoMe" or "UpdateMe" set to a value of "yes" to enable this Key input mode.
• The virtual keyboard will write the character pressed to the HTML texbox or textarea in the application that has focus.
• When the virtual keyboard wants to close, it must set an INPUT element (typically hidden) named “CloseMe” to value “yes”.  This element is checked by KioWare after every mouse click on the virtual keyboard.
• KioWare also has the ability to send javascript:onkeypress events to the textbox when a button is pressed in the VK.  To enable this feature, create another input tag with an id of KeyPressEvent and set it's value to "yes".
• To see examples of these features, use the named keyboard files in the virt_kbd directory as examples.  They have most features turned on by default.

Refer to KioWare Guide for more details on how to configure KioWare to use a virtual keyboard.

TouchScreen Issues

Kiosk applications that do not incorporate a keyboard and trackball and rely solely on a touchscreen for user interaction have special design considerations.  The difference in selection resolution between a trackball pointer and the average fingertip is significant.  Although text size is browser and programmatically configurable, standard browser controls such as combo boxes, radio buttons and checkboxes are only configurable using HTML style sheets, and the default sizes tend toward being too small for the average fingertip.  Changing screen resolution is the only other way of modifying the size of browser controls.  Scrollbar size can be modified by changing the Windows Desktop Display Properties.  Adhering to the following guidelines will help to create an application that minimizes the frustration of your users:

• Design at the lowest resolution possible to maximize browser control size
• Modify the default size of controls to increase their size
• Minimize use of Combo Boxes (<select> tags)
• Leave plenty of white space between radio buttons and checkboxes
• Make buttons as large as possible
• Minimize data entry by providing radio button or checkbox selections

Popup Windows

Pop-up windows are generally identified with unwanted advertising that instantly appears along with the page you requested; and as such have little use in a kiosk application; however, there are more legitimate uses for pop-ups.  For example, the use of a pop-up window to display more information about a particular item on a page; however, even so care must be taken.  The standard pop-up window can only be closed by clicking the X in the upper right corner of the window, and in a pure touchscreen application, this can be cumbersome for all but the most slender fingered of users.  In this case, include a large HTML button that can easily be touched by a finger that executes javascript to close the window.

Another potential problem with pop-ups that is unique to kiosk applications involve abandonment.  If a user opens up a pop-up, and then leaves the kiosk, the pop-up is cluttering the screen and may discourage another user from using the kiosk.  KioWare will automatically close all pop-up windows when the user session ends (either via inactivity timer or security device).

As a general rule, it is best not to use pop-up windows; however, in those instances where their use is warranted to use them only in tightly constrained and limited circumstances.

Phone Calls

Many times, especially in HR or Health and Human Services applications, it is beneficial to give the kiosk user the ability to place a phone call for additional information.  This capability is easily handled within KioWare without any special programming.  Naturally, the PC needs to have an analog modem installed (preferably not a WinModem), as well as an analog phone connection and a handset installed on the kiosk enclosure.

KioWare has two methods for placing phone calls: Title Tag, and Embedded Tag

Survey Data

There are many times that a kiosk application will request information about the user.  Certainly, in the case of a HR application, the user will be entering information about themselves and their benefit selections, but even in a purely informational application there is an interest in learning more about the user – perhaps their demographics.  As the developer of a web application, you have many choices available to you to acquire and store user information.  KioWare also provides a method.

In the KioWare program directory, there is a Microsoft Access 2000 database called UserInfo.mdb that contains a table called tbl_Srvy.  This table can be used to store any data that you wish to collect, and when usage stats are uploaded to the KioWare Server any new records in this table are uploaded too.

Tbl_Srvy contains the following three fields: [srvy_id], [timestamp] and [uploaded].  These fields cannot be modified; however, you are free to add as many additional fields as you wish.  The additional fields are automatically uploaded to the central server; however, if you wish to use the Kiosk Statistics component of KioWare Server to view the data then you will need to configure data labels to match the fields you added.  Refer to KioWare Server User Guide for further instructions.

Input Devices

KioWare provides an easy method of getting data that has been acquired via a barcode reader, proximity reader or magnetic stripe reader that precludes the need to develop code to talk directly to the device.

HTTP Data Methods

KioWare can pass barcode and MSR data either via HTTP Get or Post methods (refer to Navigate Page Data Via on the External Devices tab in the Configuration Tool).  The Get method passes the data as a querystring and is not generally recommended since the data will be visible to server logs, etc.  The Post method passes the data as form data and in combination with encryption is a very secure means of passing the data.

User Sessions

Often times in applications that are not purely informational, the user will be required to logon (ex, employee benefits selection application), and the application designer needs to make sure the user session expires in a timely fashion.  If the session timeout value for the web server is set longer than the timeout value for the attract screens to display (Inactivity Time in the Configuration Tool), then it is very important for the web application to log out the user when the attract screens display.  This is easily accomplished by using Session End Settings in the Attract Screen Tab of the Configuration Tool.  It may also be beneficial to use a security device such as security mat or proximity switch to initiate and end a user session.

The Session End Settings can also run a custom script and also trigger the automatic deletion of cookies, cache and print spooler queue.

Depending on the confidentiality of the information, it may make sense to require the user to logon to each screen of information displayed or every time data is saved.

Error Handling

KioWare can intercept web server errors and redirect to a defined error handling URL (refer to the Error Handling Tab of the Configuration Tool).  In addition, KioWare can pass into the error handling script the URL of the script causing the error and the server error code.  This information is passed using a querystring of the form:

With the information contained in the querystring, an error handling routine can be created that elegantly recovers from the error, provides a consistent user interface to the user, and perhaps logs the error for follow-up.

Page Blocking Information

To get a string containing the URL of the last blocked page, use:

Scripting

The following KioWare functions that can be accessed through scripting within your application.

function IsKioWare()
{
	try
	{
		if(window.external.getKioProperty('SVNRev'))
			return true;
	}
	catch(err){}
	return false;
}

KioWare .Net Addins Programming

Also see: .Net Addins in Config Tool

KioWare has the ability to load custom written, .Net libraries at runtime.  Addins are a very powerful feature because anything that can be done using the .Net programming language (which is almost anything) can be accomplished.

KioCallObject

The window.external JavaScript function that can be used to call a .Net addin function.

Kioware.Callbacks

Functions that can be called from the .Net addin to perform certain defined tasks in KioWare.

Kioware.Events

These functions do the opposite of KioWare.Callbacks in that KioWare.exe calls them to notify the .Net addin of certain events that occur.

.Net Monitored Device

These functions are specific to one .Net addin purpose; devices.

KioWareDotNet

Everything in this section is found in the KiowareDotNet.dll file in the KioWareDotNet namespace.
Example Use:
window.external.KioCallObject("KioWareDotNet.KioWareDotNet", "functionName", param1, param2);

An Example C# Addin Program

Full C# code that changes a toolbar Picture control image.  Add a Reference to KioWare.exe in order to use the public methods within the module.

using System;
using System.Collections.Generic;
using System.Text;
using System.Drawing;
using System.Threading;
using System.Diagnostics;

namespace ToolbarTestNS
{
	public class ToolbarTest
	{
		int curbmp = 1;
		Bitmap bm1;
		Bitmap bm2;
		Kioware.OnShutdownDelegate KiowareShutdown;
		Kioware.OnStartupDelegate KiowareStartup;

		public ToolbarTest()
		{
			KiowareShutdown = new Kioware.OnShutdownDelegate(Events_OnShutdownEvent);
			KiowareStartup = new Kioware.OnStartupDelegate(Events_OnStartupEvent);
			Kioware.Events.OnShutdownEvent += KiowareShutdown;
			Kioware.Events.OnStartupEvent += KiowareStartup;

			bm1 = new Bitmap(@"C:\Inetpub\wwwroot\Skins\0_splash-On.bmp");
			if(bm1 == null)
				EventLog.WriteEntry("ToolbarTest", "Bitmap 1 creation failed");

			bm2 = new Bitmap(@"C:\Inetpub\wwwroot\Skins\0_splash-Disabled.bmp");
			if (bm2 == null)
				EventLog.WriteEntry("ToolbarTest", "Bitmap 2 creation failed");
		}
		~ToolbarTest()
		{
		}
		public void SwapBitmap()
		{
			if (Kioware.Callbacks.ToolbarControlSetBitmap("Toolbar1", "img1", curbmp == 1 ? bm2 : bm1))
			{
				if (curbmp == 1)
				{
					curbmp = 2;
					bm1.RotateFlip(RotateFlipType.Rotate90FlipNone);
				}
				else
				{
					curbmp = 1;
					bm2.RotateFlip(RotateFlipType.Rotate90FlipNone);
				}
			}
			else
				EventLog.WriteEntry("ToolbarTest", "Image set failed");
		}
		void Events_OnStartupEvent()
		{
			System.Diagnostics.EventLog.WriteEntry("ToolbarTest", "Add in started");
		}
		void Events_OnShutdownEvent()
		{
			// close times
			// detach event
			Kioware.Events.OnShutdownEvent -= KiowareShutdown;
			Kioware.Events.OnStartupEvent -= KiowareStartup;
		}
	}
}

The HTML/JavaScript that uses the addin above:

You may also want to download this full Visual Studio addin example.

Config Tool Addins

See KioWare Config Tool Addin Programming