This is my third blog post in a series related to the Receiver X1 Tech Preview.

We have shared some background about X1 and practical tips to deploy X1. In this post we will dive deeper on how to customize with CSS.

CSS

The key to customization in X1 is Cascading Style Sheets (CSS). This is a standard part of the HTML specification familiar to web developers. For those who are new to web programming, it can be a bit daunting, but simple changes are really easy in CSS.

We have deliberately focused on standard technologies when looking at the X1 APIs to make customization extremely easy instead of forcing everyone to learn a new tool. CSS is the first and foremost means for customization. In fact if you use the StoreFront admin console to make changes under the covers CSS is created to match those changes (see last blog).

Tools

To do much more you need to break out an editor – notepad will do, but I recommend something like Visual Studio or Visual Studio Express Web. These tools will warn you of any syntax errors and save you time in the long run.

In this blog I’ll use Visual Studio Express for Web and Chrome as my browser, as it has excellent development tools. IE and FireFox are pretty good as well, so choose your own poison.

Be sure to run your tool as administrator, or you won’t be able to write any of the files. (Later I’ll show you how you can take a copy of the web site to develop away from the server, but let’s keep it simple for now).

In Visual Studio, use ‘Open Web Site’, select local file system and then your site. For me this is C:\inetpub\wwwroot\Citrix\PurpleWeb’ (Substitute your own store name in for ‘Purple’).

If you’d prefer to stick with notepad, note that it will also has to run as admin to allow you to edit the style.css and script.js files in the PurpleWeb\custom directory. For those just cutting and pasting from the blog, this will be just fine.

Note that once the site is loaded into a tool like Visual Studio it looks a bit overwhelming. This is because it contains all of X1 and all of the classic ‘green bubble’ Receiver. You can ignore 99% of this. All we care about is the contents of the ‘custom’ directory, and specifically the style.css and script.js files.

Let’s open style.css and make some simple changes

Add the following to the bottom of the file:

<span style="color: brown;">#customTop</span> {
 <span style="color: red;">height</span><span style="color: blue;">:30px</span>;
 <span style="color: red;">background</span><span style="color: blue;">:red</span>;
}

This says. “Find the area called ‘customTop’ (strictly with id=’customTop’) and set its height to 30 pixels and its background color to red.

Reload the X1 UI and you will find it has acquired a new region.

This region is exclusively for customization. A red stripe is fine – but you probably want to put other stuff into it – custom toolbars, messages etc. We will talk more about this next blog. There are two other regions called #customScrollTop and #customBottom. Let’s define them all and take a look.

Add the following to the bottom of style.css. Save, and reload the web page

<span style="color: brown;">#customScrollTop</span>{
 <span style="color: red;">height</span><span style="color: blue;">:30px</span>;
 <span style="color: red;">background</span><span style="color: blue;">:blue</span>;
}

<span style="color: brown;">#customBottom</span>{
 <span style="color: red;">height</span><span style="color: blue;">:30px</span>;
 <span style="color: red;">background</span><span style="color: blue;">:pink</span>;
}

(Note the pink strip clashes with the copyright message. This will be fixed by release 🙂 )

The blue strip (#customScrollTop) scrolls with the rest of the page, the other two are fixed. You can make these larger or smaller, or hide/show in different circumstances. As a simple example try adding the following lines:

<span style="color: brown;">.myapps-view #customTop</span> {
 <span style="color: red;">display</span><span style="color: blue;">:none</span>;
}

Back to the web site and you will see that the blue region, is no longer shown on the ‘Favorites’ page. This new statement says “If the ‘customTop’ element lives under an element marked with the ‘myapps-view’ class, then hide it”. (myapps-view is the internal name for ‘favorites’).

(Canned web site here: http://samples.citrixcloud.net/X1/4-Regions/receiver.html?-db)

This is another of the marker classes I mentioned in the previous blog. They are very powerful for showing/hiding or highlighting parts of the UI, whether custom regions or specific apps.

Here is the full(ish) list.

.large Large display (i.e. not a phone)
.small Small display (phone like)
.highdpi High DPI images (x2) being used
.myapps-view On the favorites view (also known as ‘my apps’)
.desktops-view Desktops view
.store-view The ‘Apps’ tab (or store if you prefer)
.appinfo-view The sub view used to show details of a single app.

Before we delve any deeper, lets look at the tools the browser provides for inspecting and understanding the UI. In Chrome, hit F12 (or go to Menu->More Tools->Developer Tools)

This opens a complex developer UI. Much of this is beyond our needs, but here are some gems here worth learning. The most useful is the magnifying glass. Use this to select part of the UI and inspect it. Click on ‘Apps’ then the magnifying glass, then the Red Bar. You should see something like this:

Note that this is showing the style information you just entered—height of 30 pixels and red background.

Click on ‘Favorites’ and see what it says for this element. It is now showing an extra rule fired, and that this rule is hiding the bar. Rules are cumulative – so the hidden bar is still red. You can see this if you were to change the second rule to something like height:15px (and remove the display:none part).

I’m not going to go into much more depth as to how to use these tools – but just be aware that they are there and extremely useful when trying to work out why your customization isn’t behaving as expected.

However do be cautious. There are many classes defined in the X1 UI, and Citrix may choose to change many of them. Don’t rely on an undocumented class, or a specific structure of the UI, or you may find your customizations won’t survive an upgrade of StoreFront.

There is only so much you can do with style alone. Next blog I’m going to get into script and how to use the APIs we created specifically for 3rd party extensions. However I’m going to end by giving you a quick example. I’ll explain this in detail next time.

In script.js (in the custom directory) type:

CTXS.Extensions.postInitialize = <span style="color: blue;">function</span> (callback) {

 CTXS.ExtensionAPI.showMessage({
     messageTitle: <span style="color: brown;">"Welcome!"</span>,
     messageText: <span style="color: brown;">"Only for WWCo Employees"</span>,
     okButtonText: <span style="color: brown;">"Accept"</span>,
     okAction: callback
 });

};

You can see the result here.

http://samples.citrixcloud.net/x1/5-Acceptance/receiver.html?-db

Details next time

Richard

Blogs in this series