We finished the last blog with a quick script example. Script scares people – after all this is real programming, and indeed you can do some very advanced stuff – but the basics are pretty simple, and I’ll be giving some cookie cutter examples as we go.

To reiterate the example from last time, we added an “acceptance” dialog to the start of X1.

Here was the code we used:

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
 });
};

Let’s go through this line by line.

First we define one of the extension functions. There are 32 of these (in the Tech Preview at least) and all represents points at which X1 is about to do something, where we thing it is likely a customer or 3rd party would like it to pause, or do something different. This one happens really early on, before login, but after the basic system is up and running.

Like many such hooks this is a function that takes a “callback” argument. This is what should happen next once the custom code has completed – so a basic extension might be

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

This says that once initialization is complete show an alert box (basic message box) and then call the callback function to continue processing.

The second part of the original customization is to show a slightly nicer message box. CTXS.ExtensionAPI.showMessage is one of the second set of APIs we provide. There are 11 of these (in the Tech Preview) and they all cause X1 to do something. Along with these you can use regular JavaScript or add 3rd party libraries or extensions. If we missed something – please provide feedback!

There will be full documentation of these APIs. I’m holding off on that until after the tech preview before we create formal documentation, as I want to emphasise that we are looking for feedback and want to tweak these as necessary before the general release, This blog series is going to serve as an early peek at those APIs. This blog is going to focus on some examples – with a fuller list in the next blog.

For a second example, I wanted to return to the custom regions we created in the UI in an early blog. These were just simple coloured bars. With script we can obviously do more!

These custom areas are intended to allow 3rd party content. To recap there are three

#customTop An area in the top header region, currently below the top bar and above the toolbar.
#customBottom An area in the footer region. (Note that in the tech preview this overlaps with the copyright statement. This element may move in future)
#customScrollTop Area at the top of the scrolling region of the page.
This is the main area to put stuff into, whether it should be part of a general page, or part of a new custom page.

Returning to our worked example, we used style to colour those three areas. Now let’s add some script to put some HTML content in.

Before we start adding some script, I want to introduce JQuery. JQuery is a very commonly used extension to the JavaScript language. We use in heavily in X1, and whilst you don’t need to use it [at all] I’m going to use it in my examples, because it leads to neater and more readable code.

Try this (add to script.js)

(<span style="color: blue;">function</span> ($) {

$(<span style="color: brown;">"#customScrollTop"</span>).html("&lt;div class='wwco-mine'&gt;Welcome to X1&lt;/div&gt;");

})(jQuery);

Now the first and last line of this are JQuery boilerplate. You can ignore this, and generally these should be the first and last line of your script.js class. It simply scopes everything you do, and makes sure that nothing you define conflicts with code written elsewhere – and it also makes JQuery available as the ‘$’ operator.

The meat of this sandwich is the middle line. This says find the element with ID ‘customScrollTop’ and set its html content to …

Note how this mimics the CSS format. That is deliberate. The content we are setting is a mini-web page. In this case a block (div) containing the text ‘Hello World’. We have also assigned a CSS class to our block, so we can style / display /hide it under control of code or style. I’d recommend that you add a company name to your css classes (wwco- in this example)  to avoid any conflicts with classes Citrix has used in X1, or that we add in future.

To go with this script, let’s add some CSS (and while we are add it, delete the previous contents of style.css to get rid of the coloured bars). Leave the auto generated section around logo-container and theme-header-bgcolor, and add a section to style the new ‘hello world’ text.

When you have finished, the style.css file should look like this:

<span style="color: green;">/* The following section of the file is reserved for use by StoreFront. */</span>
<span style="color: green;">/* CITRIX DISCLAIMER: START OF MANAGED SECTION. PLEASE DO NOT EDIT ANY STYLE IN THIS SECTION */</span>
<span style="color: brown;">.theme-header-bgcolor</span>{
 <span style="color: red;">background-color</span>:<span style="color: blue;">#32A9C3</span>;
}
<span style="color: brown;">.logo-container</span>{
 <span style="color: red;">background-image</span>: <span style="color: blue;">url('WWCO_logo_white.png')</span>;
 <span style="color: red;">background-size</span>: <span style="color: blue;">112px 29px</span>;
}
<span style="color: green;">/* CITRIX DISCLAIMER: END OF MANAGED SECTION. */</span>
<span style="color: green;">/* You may add custom styles below this line. */</span>

<span style="color: brown;">.wwco-mine</span> {
 <span style="color: red;">display</span>:<span style="color: blue;">none</span>;
}

<span style="color: brown;">.myapps-view .wwco-mine</span>{
 <span style="color: red;">font-size</span>:<span style="color: blue;">60px</span>;
 <span style="color: red;">text-align</span>:<span style="color: blue;">center</span>;
 <span style="color: red;">display</span>:<span style="color: blue;">block</span>;
}

A canned version of that site is here:

http://samples.citrixcloud.net/x1/6-Welcome/receiver.html?-db

Let’s talk through what we have done

  1. In the script we added some content in a container with a class ‘wwco-mine’
  2. In the CSS we added a statement to say this should normally be hidden
  3. In the CSS we added a statement to say that when in the ‘myapps’ view (favourites) it should be shown, and with a specific font size and other style.

This is a pretty standard pattern. Create something, hide it, and then indicate the exceptions when it should be shown. The exceptions can be in code as well as style. Try adding the following (to script.js)

 $(<span style="color: brown;">".wwco-mine"</span>).on(<span style="color: brown;">"click"</span>, <span style="color: blue;">function</span> () {
     $(<span style="color: blue;">this</span>).fadeOut();
 });

This says (with typical JQuery terseness) Find the element with CCS class ‘wwco-mine’.  Watch for the ‘click’ event on this, and when it happens run some code. That code fades out the element that was clicked on.

You can take a look here:

http://samples.citrixcloud.net/x1/7-Fade/receiver.html?-db

Incidentally if you are finding it hard to follow the various edits, you can look at the files we’ve changed on this site (or any of the previous ones) by opening the ‘script.js’ or ‘style.css’ pages in a browser. For example:

http://samples.citrixcloud.net/x1/7-Fade/custom/script.js

http://samples.citrixcloud.net/x1/7-Fade/custom/style.css

I’m going to finish this blog here, and the next will follow in a few days with a full list of all the APIs and a description as to how to use them. After that I want to focus on some use cases and start explaining how to make the customizations pay.

Blogs in this series