What do you get with eBook?

Instant access to your Digital eBook purchase

Download this book in EPUB and PDF formats

Access this title in our online reader with advanced features

DRM FREE - Read whenever, wherever and however you want

Buy Now

Building UIs with Wijmo

Chapter 1. Getting Started with Wijmo

Wijmo is composed of over 40 user interface widgets ranging from form components to enterprise charts. All of the widgets come with themes. The best features about Wijmo are:

Wijmo is easy to use. It is a complete set of widgets with a wide array of configuration options. Chances are that Wijmo has a widget for every UI component you've used in your projects.
It deals with implementation differences between browsers. All versions of IE since version 6 and other browsers are supported.
It has Platinum support. Although the live phone support costs an annual fee, your team will never get stuck or experience downtime while working with Wijmo.
It is open source and is hosted on a repository on GitHub with a GPL license for open source applications.

Not everything is perfect. Wijmo comes with its rough edges. In this book, I point out the pitfalls and guide you around them. The benefit of learning from this book is that you won't make the mistakes I've made. Learning Wijmo makes web development simpler, quicker, and more enjoyable.

Setting up Wijmo

Downloading and installing Wijmo only takes a few more steps compared to jQuery UI. It has files hosted on a content distribution network for a quick start. For this book, it is recommended that you download and set up the files for development. Since Wijmo is built on jQuery UI, I have included the details on obtaining and customizing jQuery UI. This chapter also covers how to install the minimized files for production environments.

Installing Wijmo the quick way via a CDN

Both jQuery and jQuery UI are hosted by Google and Microsoft on their Content Distribution Networks (CDNs). The Microsoft service hosts standard jQuery UI themes as well as JavaScript. To use a CDN, you need to find the URLs of the files that you want first. Microsoft has a page listing their hosted libraries at asp.net/ajaxlibrary/cdn.ashx. If you click on the jQuery UI releases under the Table of Contents, several versions are listed. Clicking on a version will show you the URLs for the minified and regular versions. For example, jQuery UI 1.10.2 has the following URL:

http://ajax.aspnetcdn.com/ajax/jquery.ui/1.10.2/jquery-ui.min.js

The page also has a nice visual gallery of all the themes for the version, with the URL for the CSS theme below each theme. The URL for Cupertino is:

http://ajax.aspnetcdn.com/ajax/jquery.ui/1.10.2/themes/cupertino/jquery-ui.css

However, the reader is encouraged to select from one of the Wijmo themes, as they are more compatible with the library. Wijmo has a Theme Explorer (http://wijmo.com/demo/themes/) showcasing six themes (as of version 3.20131.1) as shown in the following screenshot:

The URL for the Rocket theme is:

http://cdn.wijmo.com/themes/rocket/jquery-wijmo.css

Wijmo provides a separate CSS for Widgets that change with each version. The URLs take the form: http://cdn.wijmo.com/jquery.wijmo-pro.all.[version].min.css. For the version at the time of writing this book, the form is: http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.css.

The JavaScript files for Wijmo follow a similar format:

To use Wijmo via a CDN, these URLs must be placed in script and link elements, as shown:

<!DOCTYPE HTML>
<html>
<head>
  <title>Example</title>
  <!--jQuery References-->
  <script src="http://code.jquery.com/jquery-1.9.1.min.js" type="text/javascript"></script>
  <script src="http://code.jquery.com/ui/1.10.1/jquery-ui.min.js" type="text/javascript"></script>
  <!--Wijmo Widgets JavaScript-->
  <script src= "http://cdn.wijmo.com/jquery.wijmo-open.all.3.20131.1.min.js" type="text/javascript"></script>
  <script src= "http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.js" type="text/javascript"></script>
  <!--Theme-->
  <link href="http://cdn.wijmo.com/themes/aristo/jquery-wijmo.css"rel="stylesheet" type="text/css" />
  <!--Wijmo Widgets CSS-->
  <link href="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.css"rel="stylesheet" type="text/css" />
  <script id="scriptInit" type="text/javascript">
    $(document).ready(function () {
      $('#dialog').wijdialog({
        autoOpen: true,
        captionButtons: {
          refresh: { visible: false }
        }
      });
    });
  </script>
</head>
<body>
  <div id="dialog" title="Basic dialog">
    <p>Meet Wijmo.</p>
  </div>
</body>
</html>

If the Wijmo CDN files have been added properly, you should see a distinct "window" with the standard minimize, expand, and close buttons as shown in the following screenshot:

When browsers load JavaScript or CSS files, they check to see if the file is in the cache. If the user already has a cached version on his machine, then the browser loads from the cache instead of downloading the content. Serving jQuery over CDN will likely reduce the download size for the user. However, the Wijmo and jQuery UI libraries are less frequently used in web development so they are not likely to be cached. Instead of loading the full libraries from a CDN, creating a custom download with only the components used in your project, as covered in the next section, reduces the size. As a result, your web application will load faster.

Installing Wijmo for development

jQuery UI has five main areas of functionality. You can create a custom download that includes only the features necessary for your web application, resulting in a smaller library for browsers to download.

To avoid the pitfalls of using a jQuery UI theme, it is recommended to completely avoid the ThemeRoller on http://jqueryui.com. If Wijmo is configured with a jQuery UI theme such as Redmond, a few quirks will appear as show in the screenshot:

Customizing jQuery UI for download

The jQuery UI download page, http://jqueryui.com/download/, lets you select only the features required for your project to create a set of smaller files for the browser to download. This is usually a better idea than using a CDN, since jQuery UI has many releases each year and the chances of your project using the same version that the browser has already downloaded is low. For this book, download jQuery UI 1.10.2 with the default options. Later on, you will want to unselect the features that you don't use and see if your project still functions.

When customizing a jQuery UI library, the dependencies are sorted out for you. When a component is enabled, its dependencies are automatically selected. As you minimize your files for production, keep in mind that most of the effects along with some interactions and widgets may not be necessary. For example, only the slide effect is used in the accordion and dialog widgets. If your project only uses these widgets, then the other effects are not necessary.

Downloading Wijmo

To start, go to http://wijmo.com/downloads/ and scroll down to the bottom. There is a navigation panel on the right-hand side with the Downloads link as shown in the following screenshot:

This loads the Downloads page, which consists of a list of ways to include Wijmo in your project along with an introductory video, Get Started with Wijmo, at the bottom. Click on the Free Trial button to download Wijmo Professional. The licensing options, along with a comparison chart of features, are at the end of this chapter. After clicking on the Free Trial button, you will need to register an account if you're a new user. Once you log in with your new account, you will see a link to download the library and you will be able to see a screen as shown in the following screenshot:

You will notice that there are JavaScript and CSS files for individual components and features in the Wijmo folder. They can be helpful when you want to reduce the size of the download for production. Since only the current version of Wijmo is downloadable from the website, you will want to keep a backup of your download.

Installing jQuery UI for development

Inside the jQuery UI download both the minified files for production and the uncompressed source code for development are present. Using the development versions makes it easy to debug, as you don't have to step through the minified code. To set up your development environment, copy the files js\jquery-ui- 1.10.2.custom.js and js\jquery-1.9.1.js into a lib folder.

Installing Wijmo for development

Like the jQuery UI download, the Wijmo download contains all the files that you need for development and production. For this book, we will be using features in Wijmo Professional. Wijmo Professional depends on components in Wijmo Open. You need to copy the following files from the Wijmo download into the lib folder:

js\jquery.wijmo-open.3.20131.2.all.js
js\jquery.wijmo-pro.all.3.20131.2.js
css\jquery.open.css
css\jquery.wijmo-pro.3.20131.2.css
css\images
Themes\rocket\jquery-wijmo.css
Themes\rocket\images

When copying the theme images, merge the folder contents. Note that the image paths are relative in the CSS and will work as long as you have the folder in the same directory as the CSS file. The Wijmo Professional files include the version number of the release that was downloaded. These change with each release, while the image and theme files are relatively static. The version, as of early 2013, is 3.20131.2. Simply replace it with your version number for the rest of the book or just use the version 3.20131.2.

Adding Wijmo to an HTML document

All that remains is to add Wijmo to your HTML document. You can do this by adding the script and link elements to the files in the lib folder as shown:

<!DOCTYPE HTML>
<html>
<head>
  <title>Example</title>
  <!--jQuery References-->
  <script src="../lib/jquery-1.9.1.js" type="text/javascript"></script>
  <script src="../lib/jquery-ui.custom.js" type="text/javascript"></script>
  <!--Wijmo Widgets JavaScript-->
  <script src="../lib/jquery.wijmo-open.3.20131.2.all.js" type="text/javascript"></script>
  <script src="../lib/jquery.wijmo-pro.all.3.20131.2.js" type="text/javascript"></script>
  <!--Theme-->
  <link href="../lib/jquery-wijmo.css" rel="stylesheet" type="text/css" />
  <!--Wijmo Widgets CSS-->
  <link href="../lib/jquery.wijmo-open.3.20131.2.css" rel="stylesheet" type="text/css" />
  <link href="../lib/jquery.wijmo-pro.3.20131.2.css" rel="stylesheet" type="text/css" />
  <script id="scriptInit" type="text/javascript">
    $(document).ready(function () {
      $('#dialog').wijdialog({
        autoOpen: true,
        captionButtons: {
          refresh: { visible: false }
        }
      });
    });
  </script>
</head>
<body>
  <div id="dialog" title="Basic dialog">
    <p>Click OK to close this window.</p>
  </div>
</body>
</html>

Wijmo licensing

Wijmo Open is licensed under both MIT and GPL. The MIT license allows you to use the software in any way you want as long as the copyright attribution is kept. Wijmo Open is an expansion of jQuery UI with more widgets and options. A few of the widgets not included in jQuery UI that are in Wijmo Open are:

Expander
Radio Button
TextBox
DropDown
CheckBox
List
Popup
Splitter
SuperPanel
Video Player

Below the differences between jQuery UI and Wijmo are mentioned, showcasing which of the features are present in both or the other.

Wijmo Professional is intended for businesses developing closed-source projects. It includes everything from Wijmo Open, in addition to the following:

Charts
ComboBox
Datasource
Grid
Input
- Date
- Mask
- Number
Media
- Carousel
- Gallery
- Lightbox
Pager
Rating
Tree
Upload
Wizard

The license cost is per developer at a rate of $495 (https://wijmo.com/purchase/). However, ComponentOne does offer a GPLv3 license for use in open source applications.

Description

Until recently, writing applications using JavaScript and HTML was difficult, because developers had to make the user interface by themselves; however, this started changing with the introduction of JavaScript libraries such as jQuery, jQuery UI, and KnockoutJS. An extension of jQuery UI, Wijmo adds features and widgets on top of jQuery UI and makes it easier to add user interface widgets to HTML documents. Building UIs with Wijmo gives you a tour of what Wijmo offers at a glance. With code recipes and well-explained examples, you will be able to use Wijmo in no time. The book gives details on options not explained in the documentation and helps you avoid those that don't work. The examples only feature the necessary code, with recommendations and best practices. This book introduces Wijmo, grouping widgets by their common application area or usage. It walks the user through the features of the dialog widget with examples as an introduction to the library. Then, widgets for forms, images, tootips, and other topics are explored. Features only available in the Wijmo dialog widget compared to the jQuery UI widget are thoroughly explained with examples. Common form components such as checkboxes, dropdowns, and inputs have Wijmo counterparts which keep the theme consistent and add functionalities. When Wijmo is used with Knockout, the UI automatically refreshes when the data changes. This book takes it further with WebSockets for two way communication between the server and client. With Building UIs with Wijmo, you will learn all the common web development components in Wijmo. You will get started using Wijmo in no time.

What you will learn

Set up Wijmo for development and production Change the Dialog widget s appearance Replace form components with widgets Autoplay images with the Carousel widget Create a LightBox widget and customize its buttons Play videos in the Gallery widget Fix the appearance of the InputDate widget Program real-time applications with declarative bindings in the MVVM style

What do you get with eBook?