Customizing Receiver for Web

Note: An updated version of this blog for StoreFront 2.0 is available here.

Citrix Receiver for Web provides a built-in support for customizing its user interface. In this blog article, I shall explain and demonstrate how to implement UI customization using this built-in support. If you follow this approach, your customization will have a better chance of surviving release upgrade. All examples in this article are based on Cloud Gateway Express 1.1.

After a Receiver for Web site is created, there is a folder named contrib under the site (default location is C:\inetpub\wwwroot\sites\Citrix\StoreWeb\contrib). This contains the built-in hooks for UI customization. It is recommended that all customization code and media are stored under this folder because the content of this folder will be preserved upon upgrade to the subsequent releases. Please note, however, that there is no guarantee that customization will always work out of the box across release upgrade, especially when the UI changes significantly.

CSS Customization

CSS customization can be used to easily change many aspects of the site appearance, including fonts, colors and images. A CSS file named custom.style.css is included in the contrib folder. This CSS file is referenced after the site’s main CSS files and hence the CSS style definitions specified in this file override similar definitions specified elsewhere. You can make use of Web development tools such as Firebug (for Firefox) or the developer tools provided by Internet Explorer and Google Chrome to identify the CSS selectors (element types, IDs or classes) you want to customize. Here are a couple of examples.

Example 1: Rebranding the Logon Screen

First let’s try to change the background image. As illustrated in the screen shot below, using Firebug, we identify that the CSS selector for the background image is body.

We copy the new background image abstract-waves-on-a-blue-background.jpg to the contrib folder. Add the following CSS definition to custom.style.css:
body {
background-image: url("abstract-waves-on-a-blue-background.jpg");
}

Reload the page and the new background image has taken effect as follows:

Next, let’s change the logo. We identify the CSS selector for the logo is #logonbox-logoimage.

Copy the new logo image logo_world.png to the contrib folder. Add the following CSS definition to custom.style.css:

#logonbox-logoimage {
background-image: url("logo_world.png");
}

Reload the page and the new logo is displayed:

Finally, let’s change the font color and weight for the logon form labels. Using Firebug, we identify that the CSS selector for the logon form labels is #logonbox-logonform label.

Add the following CSS definition to custom.style.css:

#logonbox-logonform label {
color: yellow;
font-weight: bold;
}

Reload the page and you can see that the labels for the logon form become yellow and bold.

Example 2: Customizing the Home Screen

First, let’s replace the logo in the header area. We identify the CSS selector for the logo is #header-logo.

Copy the new header logo image logo_header.png to the contrib folder. Add the following CSS definition to custom.style.css

#header-logo {
background-image: url("logo_header.png");
}

Reload the page and the logo in the header area is replaced:

Next, let’s change the font color for application names to make it more readable. We identify that the CSS selector for the fort for application names is .myapps-name.

Simply add the following CSS definition to custom.style.css:

.myapps-name
{
color: yellow;
}

Similarly, adding the following CSS definitions to custom.style.css changes the font color for the user name and Log Off link in the header area:

#resources-header #header-userinfo {
color: lightgreen;
}

#resources-header #header-logofflink {
color: lightgreen;
}

Here is the resultant Home Screen:

JavaScript Customization

JavaScript customization can be used to inject additional content into the UI and load other scripts, CSS style sheets and HTML fragments via Ajax. A JavaScript file named custom.script.js is included in the contrib folder and referenced by the HTML file for the Receiver for Web UI. This custom JavaScript file is referenced after the site’s main JavaScript files so that any functions defined in the custom file override functions with the same names defined elsewhere.

Example 3: Adding a Hyperlink to the Footer Area

Using Firebug, we identify that the ID for the footer area is #resources-footer. We add the following JavaScript code to custom.script.js:

Example 4: Loading Extra UI Files

In this example, we load extra HTML and CSS files to achieve the same effect as Example 3. If you have applied the customization in Example 3 in your site, you have to undo the changes before following the instruction below.

First, create a new file named footer.htm in the contrib folder with the following HTML fragment:

The $.ajax call loads the CSS style sheet footer.css and the $('#resources-footer').load call loads the HTML fragment defined in footer.htm to the footer div. The resultant screen is exactly the same as that of Example 3.

String Customization

Customized string bundle files for all supported languages are included in the contrib folder. They are simple JavaScript files that define a set of name-value pairs. Strings defined in these files override the built-in strings for the given language.

Example 5: Customizing Texts in the Header Area

Let’s change the text of the “Log Off” link to “Sign Out” and “Welcome” to “Signed in as”.

First, we need to locate the string IDs. Open the English string file (default location is C:\inetpub\wwwroot\Citrix\StoreWeb\scripts\en\ctxs.wrstrings.js) in a text editor.

Then search this file for the strings “Log Off” and “Welcome” and note the string IDs, in this case LogOff and Welcome.

Edit the English version of the custom strings file custom.wrstrings.en.js in the contrib folder and add updated strings as follows:

A similar process can be followed to change any of the existing strings found in the UI. Strings can be altered for other languages by providing the customization in the appropriate custom string file, e.g., custom.wrstrings.fr.js for French.

Limitations

As noted at the beginning of this article, all contents in the contrib folder will be preserved across release upgrade. However, page elements may be added, removed or renamed in future releases of Receiver for Web. As a result, customizations may fail to work after upgrading to a future release.