Getting Started with Wijmo

Contents

What in the World is Wijmo?

Wijmo is a kit of UI widgets based on jQuery UI. Wijmo widgets are optimized for client-side Web development and utilize the power of jQuery for superior performance and ease of use. All Wijmo widgets come equipped with over 20 themes and support ThemeRoller.

This guide will introduce you to jQuery concepts and then get you started with your first Wijmo project. From there, you can move on to our library of demos to get a stronger feel for what Wijmo can do for you.

jQuery Syntax

jQuery syntax was designed to allow developers to easily select DOM element(s) and then perform some action on the element(s). The rudimentary syntax is as follows:

$(selector).action()

$ references jQuery; (selector) queries the DOM element or elements; and .action() performs an action on the element.

Examples of jQuery syntax:

  • $(this).hide() hides the current element.
  • $("p").hide() hides all paragraphs.
  • $("p.wow").hide() hides all paragraphs of the class "wow".
  • $("#wow").hide() hides an element with the id of "wow".

jQuery Selectors

Before you start using jQuery, it’s crucial to understand the concept of jQuery selectors. jQuery selectors utilize CSS syntax, thus allowing developers to precisely select elements to apply effects to. Using these selectors, you can select specific DOM elements or groups of elements by attribute name, tag name, ID, or even by content. The different types of selectors are as follows:

jQuery Element Selectors

In jQuery, you can use CSS selectors to choose specific DOM elements. For example:

  • $(this) selects the current DOM element.
  • $("div") selects all <div> elements.
  • $(".super") selects all elements of the class "super".
  • $("div.super") selects all <div> elements of the class "super".
  • $("#wow") selects the first element with the id "wow".
  • $("div#wow") selects the first <div>element with the id "wow".

jQuery Attribute Selectors

If you’d like to select an element by attribute rather than by DOM elements, you can use Xpath expressions to select elements with a specific attribute. For example:

  • $("[href]") selects all elements with an href attribute.
  • $("[href="#"]") selects all elements with an href attribute with a value equal to "#".
  • $("[href!="#"]") selects all elements with an href attribute with a value that is not equal to "#".

jQuery CSS Selectors

If you want to change the CSS property for a DOM element, you can use a CSS selector. For example, the following jQuery script changes the background color of all <div> elements to red:

$("div").css("background-color","red");

Document Ready Function

To prevent jQuery code from running before the document is completely loaded, all jQuery functions should be placed within the $(document).ready function. For example:

$(document).ready(function(){   
// Do something on document ready.  
});

If you prefer, you can use a shortened version of the $(document).ready function instead. For example:

$(function() {
// do something on document ready
});

All scripts residing inside of the $(document).ready function will load as soon as the DOM is loaded and before the page contents are loaded.

jQuery Options

jQuery options are simply properties passed into a widget as an argument. Each Wijmo widget has a default configuration of options; of course, there will be instances where you want to override these defaults to customize the widget.

To give an example, let’s assume that the wijprogressbar widget has a maxValue option with a default value of 100, but you’d like this value to be 85. Changing the maxValue option from its default to a value of 85 is as simple as passing an argument to the wijprogressbar:

$(‘#progressbar’).wijprogressbar({
	maxValue: 85
});

With the maxValue option set to 85, the range of values on the wijprogressbar widget will be 0 – 85, as the minValue property is set to 0 by default. If you want to change the minValue option to 25, just add a comma after the maxValue argument and then write your minValue argument:

$(‘#progressbar’).wijprogressbar({
	maxValue: 85,
	minValue: 25
});

You can pass as many options to the widget as you want – just remember your commas!

How to Reference Wijmo

You can easily load Wijmo into your web page using a Content Delivery Network (CDN). CDN makes it quick and easy to use external libraries, and deploy them to your users. A CDN is a network of computers around the world that host content. Ideally, if you’re in the United States and you access a webpage using a CDN, you’ll get your content from a server based in the US. If you’re in India or China, and you access the SAME webpage, the content will come from a server a little closer to your location.

When web browsers load content, they commonly will check to see if they already have a copy of the file cached. By using a CDN, you can benefit from this. If a user had previously visited a site using the same CDN, they will already have a cached version of the files on their machine. Your page will load quicker since it doesn’t need to re-download your support content.

Wijmo has had CDN support from the very beginning. You can find the CDN page at http://wijmo.com/downloads/#wijmo-cdn. The markup required for loading Wijmo into your page looks similar to this:

<!--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>
   
<!--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" />
   
<!--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>

In this markup, you'll notice that some of the .js files are labeled as *.min.js. These files have been minified - in other words, all unnecessary characters have been removed - to make the pages load faster. You will also notice that there are no references to individual .js files. The JavaScript for all widgets, CSS, and jQuery references have been combined into one file, respectively, such as wijmo-complete.2.0.0.min.js. If you want to link to individual .js files, see the Dependencies topic for each widget.

Creating Your First jQuery Project

Now that you’ve grasped the main concepts of jQuery, you’re ready to begin your first project. In this sample project, you’re going to add a Wijmo Open widget, wijcalendar, to your project and then customize a few of its options.

The first step is to create an .html page and add links to the dependencies to your project within the <head> tags. To do this, you just link to the content delivery network (CDN) file for each project:

Note: Please reference the latest dependencies from the CDN at http://wijmo.com/downloads/#wijmo-cdn.

<!--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>

You’ll also want to add your CSS style sheets, which you can do by adding the following CDN links to your project within the <head> tags:

<!--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" />

To create the wijcalendar HTML element, place the following markup within the body of the .html document:

<div id="calendar1" style="position:relative;left:40px;top:40px;"></div>

Now you need to initialize the wijcalendar widget, which you can do by adding the following script within the <head> tags of the .html document:

<script type="text/javascript">
    $(function () {
        $("#calendar1").wijcalendar();
});
</script>

View the full wijcalendar sample markup page for an example of what the markup should look like.

The wijcalendar has a predefined configuration of option settings, so it’s ready to use as soon as you initialize it. If you opened your project in a Web browser right now, you’d find a completely functional calendar widget, which will look like this:

Calendar without 'other month days'.

But what if the project plans specify that the days of the previous and subsequent months shouldn’t be shown on the calendar? Removing them couldn’t be simpler: all you have to do is set the showOtherMonthDays option to false by passing it into the calendar widget as an argument:

$("#calendar1").wijcalendar({
	showOtherMonthDays: false
});

Open your project in a Web browser and observe that the other month days no longer appear on the calendar. It will looks like this:

Calendar without 'other month days'.

You can pass multiple options to a widget. If you need to pass another option to the calendar, just place a comma after the showOtherMonthDays: false argument and place the new argument after it. The example below shows how to pass the displayDate option in addition to the showOtherMonthDays option:

$("#calendar1").wijcalendar({
    showOtherMonthDays: false,
    displayDate: new Date('2010/08/25')
});

Adding and customizing a Wijmo widget is that simple. However, this example just scrapes the surface of what you can do with Wijmo widgets. For more detailed information regarding the Wijmo widgets, visit the Wijmo documentation, where you will find an overview and API reference for the individual widgets. If you'd like help getting started with Wijmo Open, see the Wijmo Complete Quick Start. For more advanced examples of scripting, you can also explore our demos page.

Retrieved from "http://wijmo.com/wiki/index.php/Getting_Started_with_Wijmo"