How to Migrate a Custom Kiosk Theme

A custom theme represents a set of CSS files and images, which are typically designed and provided by a customer, as an alternative to Kiosk's default theme. In most cases, custom themes are designed to match the customer's desired set of fonts, colors and images. A custom theme may also involve a custom positioning of user interface elements.

Info

The custom theme is stored in a subfolder of the Kiosk Client customizations folder, i.e. C:\ProgramData\NEC\kiosk\Custom\Themes\<custom_theme_name>

The amount of CSS differences between the default themes from two consecutive Kiosk releases can be very large because of the various features included in each Kiosk release.

Because of this large amount of differences, updating a custom theme to be compatible with the latest default theme is a cumbersome task, in the absence of some tools and procedures to assist with this update. The next section explains how to use the tools provided with Kiosk for making this update process much easier.

Migration Steps

Upgrading your Kiosk Services

Upgrade your Kiosk Services to the latest version using the template files provided with the Kiosk Distribution or obtained from the Adapter Hub Template store.

Upgrading your Kiosk Client

Upgrade your Kiosk Client using the installer provided with the Kiosk Distribution.

After you upgrade your Kiosk Client, the default theme is backed up in a folder named <Installation Folder>\Previous.<old_version>\Themes\Default, where:

<Installation Folder>is the install location as selected in the installer (typically, C:\Program Files (x86)\Kiosk Client).
<old_version> is the older Kiosk application version before the upgrade.

Example

Assume the installation folder is not changed from its default value, C:\Program Files (x86)\Kiosk Client
Assume upgrading from Kiosk 2.1.4 to Kiosk 2.2.6
Then the backup folder is C:\Program Files (x86)\Kiosk Client\Previous.2.1.4\Themes\Default

Comparing the themes

Log in to the upgraded Kiosk Admin with an user account with administrative permissions
Navigate to Utilities
Use the left-side drop zone to select the older theme file:
1. Option 1: Click on the text inside the left-side drop zone to browse for the older theme CSS file
  1. In the Open file dialog, navigate to the default theme backup folder, then select styles.css
  2. The back-up folder path typically looks like C:\Program Files (x86)\Kiosk Client\Previous.<old_version>\Themes\Default
2. Option 2: Open Windows Explorer and navigate to the backup folder, then drag styles.css from Explorer and drop it the left-side drop zone
Use the right-side drop zone to select the newer theme file:
1. Option 1: Click on the text inside the right-side drop zone to browse for the newer theme CSS file
  1. In the Open file dialog, navigate to the current default theme folder, then select styles.css
  2. The current default theme folder path typically looks like C:\Program Files (x86)\Kiosk Client\Themes\Default
2. Option 2: Open Windows Explorer and navigate to the default theme folder, then drag styles.css from Explorer and drop it the left-side drop zone
After you selected both theme files, click the Compare button to generate the differences report in Excel format
Clicking it results in a spinner icon briefly shown on the Compare button; then after a while it will prompt you to open the differences report or to save it locally
1. The effective behavior (Open vs. Save) depends on your browser configuration

Understanding the difference report file

When opened with Excel, the differences report file will look like below.

Notice the presence of 7 columns:

Diff type: This represents the type of the difference from the perspective of the "new" default theme. It may be any of these three values:
1. Added: The respective CSS class did not exist in the old theme and it has been added in the new default theme
2. Modified: The respective CSS class existed in the old theme and it has been modified in the new default theme
3. Removed: The respective CSS class existed in the old theme and it has been removed from the new default theme
OldName: It represents the CSS class name (or a sequence of class names) in the "old" default theme
NewName: It represents the CSS class name (or a sequence of class names) in the "new" default theme
OldValue: It represents the CSS class contents in the "old" default theme
1. This means the text between the first level of curly braces for the respective CSS class, including the curly braces.
NewValue: It represents the CSS class contents in the "new" default theme
OldLine: The line number where the CSS class can be found in the "old" default theme.
NewLine: The line number where the CSS class can be found in the "new" default theme
1. Line numbers may come in handy if you want to have a look in the default theme files using eg a text editor.
2. Most text editors have the possibility to jump to a given line number.

Info

The first line in the report will always be a Modified row depicting the old file name vs. new file name.

Adjusting your old custom theme after upgrading Kiosk Client

Before performing any changes, make sure you have backed up your custom theme folder (the entire files & sub-folders tree).
1. The custom theme folder is a subfolder of the Kiosk Client customizations folder, i.e. C:\ProgramData\NEC\kiosk\Custom\Themes\<custom_theme_name>
2. If anything goes wrong during the process of adjusting the custom theme or simply you do not like the result, you can always return to the initial custom theme if you have backed it up.
Open the difference report with Excel.
Open your old custom theme CSS file in a text editor
1. We suggest using Notepad++ because of its syntax highlight features, which makes it easier to identify CSS class names and contents.
Start with the Removed rows in the Excel file

Hint

Use the DiffType filter which is already part of the Excel file to filter the data by difference type)
1. Per each row, use the full OldName to identify the place where it is used in the custom theme file, and remove it from there too (Remove both the class name and contents, not just the class name)
2. When changes done, mark the respective row as processed in the Excel file
  
  Example
  
  Mark the completed row with green color.
3. Repeat steps a...c until all Removed rows in the Excel file are processed.
Continue with the Added rows
1. Per each row, create a new entry in the custom theme file:
  1. Use the full NewName for the CSS class name
  2. Set the CSS class contents as given by the NewValue field.
    - If this contents refers to colors, fonts, images, be aware that you may need to change them later on to be in line with the custom theme
  3. You can put the new CSS class anywhere in the custom theme file. We recommend to put them after the other "old" classes, but before the KioskAppThemeEnd line.
    - This will come in handy later when you will need to locate the new classes, in order to adjust the colors, fonts etc...
    - Optionally you may add a comment line that separates the newly added CSS classes from the rest of the file.
      
      Example
      
      Comment some useful info like the date when you made these changes, the Kiosk version for which you made the changes, etc ... so that you will keep a sort of an in-place versioning
2. When changes done, mark the respective row as processed in the Excel file in a similar way like you did for the Removed rows
3. Repeat steps a...c steps until all Added rows are processed.
Continue with the Modified rows.

Warning

This will be the most complex step, because Modified can refer to class name, contents, or both.
1. Per each row, use the full OldName to identify the place where it is used in the custom theme file.
2. Replace the CSS class name in the custom theme file as given by the NewName field
3. Replace the CSS class contents with the new contents as given by the NewValue field.
  1. If this contents refers to colors, fonts, images, be aware that you may need to change them to be in line with the custom theme
4. When changes done, mark the respective row as processed in the Excel file in a similar way like you did for the Added / Removed rows
5. Repeat steps a...e until all Modified rows are processed.
Save the custom theme file in the custom theme folder which is a subfolder of the Kiosk Client customizations folder, i.e. C:\ProgramData\NEC\kiosk\Custom\Themes\<custom_theme_name>
Review kioskconf.json from the Kiosk Client data folder, i.e. C:\ProgramData\NEC\kiosk\kioskconf.json, and make sure that under the theme_options node, the correct custom theme name is specified.

Warning

After completing these steps, the Smart Check-In Client Theme should mostly look OK with using the custom theme. However, you will likely still need to tweak some CSS colors and positioning, especially for the new added classes, until you get the desired UI look.