Learning the Yahoo! User Interface library

By Dan Wellman
    Advance your knowledge in tech with a Packt subscription

  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Introducing the YUI

About this book

The Yahoo! User Interface (YUI) Library is a set of utilities and controls, written in JavaScript, for building richly interactive web applications using techniques such as DOM scripting, DHTML, and AJAX. The YUI Library also includes several core CSS resources. All components in the YUI Library have been released as open source under a BSD license and are free for all uses.

This book covers all released components whether utility, control, core file, or CSS tool.  Methods of the YAHOO Global Object are used and discussed throughout the book.
The basics of each control will be presented, along with a detailed example showing its use to create complex, fully featured, cross-browser, Web 2.0 user interfaces.

Besides giving you a deep understand of the YUI library, this book will expand your knowledge of object-oriented JavaScript programming, as well as strengthen your understanding of the DOM and CSS.

You will learn to create a number of powerful JavaScript controls that can be used straight away in your own applications.

Publication date:
March 2008
Publisher
Packt
Pages
380
ISBN
9781847192325

 

Chapter 1. Introducing the YUI

Welcome to the first chapter of "Web Development with the Yahoo! User Interface Library". Throughout this book, we'll be exploring what makes up the library and what it can do for you. By implementing a selection of the available utilities and controls, we can see exactly how each one works and what functionality and tools it leaves at your disposal.

During this chapter we're going to introduce ourselves to the library by taking an overall view of it. The topics that we are going to cover include:

  • How to get the library, where to get it from, how to install it, and how to work with it in your own web pages.

  • Where it came from, what inspired its creation, who made it, and the core ideas behind it.

  • Exploring the library and investigating what components form its constituent parts.

  • Where we can find important information and news about the library and places where we can go to for help if we need it.

  • The gallery, where you can see who else is using it and what they've been able to achieve.

  • The licensing issues that surround its legal use.

  • Who would make the most of it.

We'll also go over a brief coding example where you will get down to some proper scripting and find out for yourself just how easy it is to get up and running with the components themselves. This is where you will see the power provided by the library at first-hand.

What is the YUI?

The Yahoo! User Interface (YUI) Library is a free collection of utilities and controls, written primarily in JavaScript, that has been produced by the expert developers at Yahoo! to make your life easier as a web developer or front-end user interface designer.

It consists of a series of JavaScript and CSS components that can be used to quickly and easily build the rich and highly interactive applications that today's web consumer expects and demands.

The premise of the library is simple; often when writing JavaScript, you'll come up with a function that works perfectly in one browser, yet badly (or worse, not at all) in alternative browsers. This means that you'll often need a set of different functions to do exactly the same thing in different browsers.

This can be done for some of the major browsers without too much difficulty using standard object detection methods within if statements. However, this can lead to massively increased script files and unwieldy code that takes longer to debug and troubleshoot, and longer to write in the first place.

The YUI wraps both sets of code up into one object that can be used programmatically with one constructor, so instead of dealing with different sets of code for different browsers, you deal with the library and it makes the different calls depending on the browser in use.

Another important aspect of the library that I should mention at this point is its respect for the Global Namespace. All objects created by the library and its entire code run within, and can only be accessed through, the YAHOO Global Namespace object. This means that the entire library, including every utility and every control, and its numerous classes, create just one namespace object within the Global Namespace.

The Global Namespace is the global collection of JavaScript object names, and it is very easy to litter it with potentially conflicting objects, which can become a problem when code is shared between applications. Yahoo minimises its impact on the Global Namespace and so shall we; all of the code that we'll write throughout the course of this book will reside within its own namespace object.

Essentially, the YUI is a toolkit packed full of powerful objects that enables rapid front-end GUI design for richly interactive web-based applications. The utilities provide an advanced layer of functionality and logic to your applications, while the controls are attractive pre-packed objects that we can drop onto a page and begin using with little customization.

Who Is It for and Who Will It Benefit the Most?

The YUI is aimed at and can be used by just about anyone and everyone, from single-site hobbyists to creators of the biggest and best web applications around. Developers of any calibre can use as much or as little of it as they like to improve their site and to help with debugging.

It's simple enough to use for those of you that have just a rudimentary working knowledge of JavaScript and the associated web design technologies, but powerful and robust enough to satisfy the needs of the most aspiring and demanding developers amongst you.

The library will be of interest primarily to front-end developers, as the main aim of the YUI is to provide a framework within which robust and attractive interfaces can be quickly and easily designed and built. It can help you to side-step what can otherwise be insurmountable compatibility issues.

There is no set standard that says you must know this much or that much before you can begin to use the YUI. However, the more you know and understand about JavaScript itself, the more the library will make sense to you and the more that you will be able to gain from using it.

Trying to learn how to make use of the YUI without first knowing about the JavaScript language itself, at least to a basic working standard, is an endeavour likely to end in frustration and disappointment. It would be a great shame if a lack of understanding prevented you from enjoying the benefits that using the library can bring to both your creativity and creations.

So to get the most out of the YUI, you do need to have at least a basic understanding of JavaScript and the principles of object oriented programming. However, a basic working understanding is all that is required and those developers that have less knowledge of scripting will undoubtedly find that they come out of the experience of developing with the YUI knowing a whole lot more than they did to begin with.

The YUI can teach you advanced JavaScript scripting methods, coding and security best practices, and more efficient ways of doing what you want to do. It will even help more advanced programmers streamline their code and dramatically reduce their development time, so everyone can get something from it.

For some, the YUI is also a challenge; it's an excellent opportunity for developers to get involved in a growing community that is creating something inspiring. The Firefox browser is a great example of an open-source, community-driven, collaborative effort of separate but like-minded individuals. Some people may not want to develop web pages or web applications using the library: they may just want to be involved in evolving it to an even greater accomplishment.

I should also point out at this stage that like the library itself, this book expects you to have a prior knowledge and understanding of JavaScript, HTML, and CSS. While the use of the utilities, controls, and CSS tools will be explained in detail throughout the book, any HTML, CSS, or PHP code that is featured in any of the examples may not be explained in detail. Other skills, such as the ability to install and configure a web server, are also required.

Why the Yahoo! User Interface Library?

Using any JavaScript library can save you great amounts of time and frustration when coding by hand, and can allow you to implement features that you may not have the knowledge or skill to make use of. But why should you use the YUI rather than the many other libraries available?

To start with, as I'm sure you already know, Yahoo! is extremely well established, and at the forefront of cutting edge web technology and front-end design principles. The utilities and controls provided by the library have already been tried and tested in their world-class service provision environment. Hence you know that the components are going to work, and work in the way that you expect them to work and that Yahoo! says that they will.

The YUI library is not the only developer-centric offering to come from these world-class leaders and go on to achieve high levels of accomplishment and a following amongst developers; other very successful projects include the extensive Design Pattern library, Yahoo! Widgets, and the Yahoo! Music Engine. They also have a wide range of APIs for you to experiment and work with, so they have already shown a commitment of providing open-source tools designed to succeed.

Additionally, the library has already been publicly available for over a year and in this time has undergone rapid and extensive improvement in the form of bug fixes and additional functionality. Overall, it is not still in beta stage, and has been proven to be an effective addition to your development toolset. Like the Mozilla and Firefox browsers, it has a huge, world-wide following of developers, all seeking to further enhance and improve it.

There are some libraries out there that have been developed which seek to alter the JavaScript language itself, building capabilities into the language that the developers felt should already have been present and extending the language in new and interesting ways.

While these libraries can provide additional functionality at a deeper and more integrated level, their use can often be hampered by technical implementation difficulties that will be too difficult to overcome for all but the most advanced and seasoned developers.

The YUI is not like this; it is extremely well documented, stuffed full of examples, and is extremely easy to use. It doesn't get bogged down in trying to alter the JavaScript language at a fundamental level, and instead sits on top of it as a complimentary extension.

There's also no reason why you can't use the YUI library in conjunction with other JavaScript libraries if a particular feature, such as the rounding of box corners as provided by MochiKit for example, is required in your application but not provided by the YUI.

Graded Browser Support

Whichever browser you prefer, there's one thing that I think we can all agree on; all browsers are not created equal. Differing support and a lack of common standards implementation are things that have confounded web developers for as long as there have been web developers.

Although the situation is improving with agreed standards from the W3C, and better and more consistent support for these standards, we are far from being in a position where we can write a bit of code and know that it is going to function on any of the many browsers in use.

There may never come a time when this can be said by developers, but with the YUI, you can already count on the fact that the most popular browsers in use, on all manner of operating systems, are going to be able to take full advantage of the features and functionality you wish to implement.

It doesn't, and can't be expected to support every single web browser that exists, but it does group together common browsers with common capabilities into a graded support framework that provides as much as it can to visitors whichever browser they happen to be using.

Every single browser in existence falls into one of the defined grades; the most common class of browser are the A-grade variety of browsers, which are the browsers that the creators of the library actively support. These are modern, generally standards compliant, and capable of rendering in full the enhanced visual fidelity and advanced interface functionality provided by the library as well as the inner core of content.

X-grade browsers are generally unknown and untested, and account for a wide range of less common, often highly specific browsers that are simply assumed to be able to access the full, enhanced experience. Any browser that has not been extensively tested by the YUI development team is automatically an X-grade browser regardless of its capabilities; IE7 on Vista was classed as X-grade for some time after its release simply because it had not been fully tested by the Yahoo! team.

C-grade browsers are able to access the base or core content and functionality of the library components, but cannot handle the enhanced content. These are browsers that are simply not supported by the library.

Currently, the complete spectrum of A-grade browsers supported by the library includes the following browser and platform configurations:

  • IE7 on Windows XP and Vista

  • IE6 on Windows 98, 2000, Server 2003 and XP

  • Firefox 2.x on Windows 98, 2000, XP and Vista, and Mac OS 10.3 and 10.4

  • Firefox 1.5 on Windows 98, 2000 and XP, and Mac OS 10.3 and 10.4

  • Opera 9 on Windows 98, 2000 and XP, and Mac OS 10.3 and 10.4

  • Safari 2 on Mac OS 10.4

  • Safari 3 on Mac OS 10.4 and 10.5, Windows XP and Vista

These 27 common configurations are able to make use of not just the core content of any applications we create with the YUI, but also all of the enhanced functionality brought on by the library. Any browser not on this list will still receive either an A or C-grade experience, but may be classed as an X-grade browser if it has not been extensively tested.

The graded browser support strategy is based on the notion of progressive enhancement as opposed to graceful degradation. "Graceful degradation" is a term that I'm sure you've heard at some point and involves designing content so that, when it breaks in older browsers, it retains some semblance of order.

This method involves designing a page with presentation in your supported browsers as your main priority while still allowing unsupported browsers to view at least some kind of representation of your content.

Progressive enhancement approaches the problem of supporting browsers with different capabilities from the other way by providing a core of accessible content and then building successive layers of presentation and enhanced functionality on top of this inner core of generalized support.

This screenshot shows how the Rich Text Editor control appears in a C-grade browser. Older readers may recognize the browser used in this experiment as Netscape Navigator version 4, a popular browser approximately a decade ago.

As you can see from this example, the inner core of the page content is a standard HTML<textarea> element, which is displayed completely normally. The page doesn't break, but the high fidelity content is not displayed. Using graceful degradation techniques, the browser would probably attempt to display the Editor, but it would probably look very poor and would certainly not function.

The following screenshot shows how the editor appears in an A-grade browser:

In a capable, supported browser the library can transform the<textarea> element into the full Rich Text Editor control. Now, the following screenshot shows exactly the same page in exactly the same browser but with JavaScript switched off:

Notice the similarity between a C-grade browser and an A-grade browser with JavaScript switched off.

The knowledge that has enabled Yahoo! to use the concept of graded browser support has been gained from wide variety of user-agents that hit their site every single day. They've been accessed by over 10,000 different software and platform configurations since they began focusing on who and how their portal is accessed.

Approximately 96% of this total have received an A-grade experience when using the Yahoo! site, leaving just three percent that are classed as C-grade, and a minimal one percent classed as X-grade.

 

What is the YUI?


The Yahoo! User Interface (YUI) Library is a free collection of utilities and controls, written primarily in JavaScript, that has been produced by the expert developers at Yahoo! to make your life easier as a web developer or front-end user interface designer.

It consists of a series of JavaScript and CSS components that can be used to quickly and easily build the rich and highly interactive applications that today's web consumer expects and demands.

The premise of the library is simple; often when writing JavaScript, you'll come up with a function that works perfectly in one browser, yet badly (or worse, not at all) in alternative browsers. This means that you'll often need a set of different functions to do exactly the same thing in different browsers.

This can be done for some of the major browsers without too much difficulty using standard object detection methods within if statements. However, this can lead to massively increased script files and unwieldy code that takes longer to debug and troubleshoot, and longer to write in the first place.

The YUI wraps both sets of code up into one object that can be used programmatically with one constructor, so instead of dealing with different sets of code for different browsers, you deal with the library and it makes the different calls depending on the browser in use.

Another important aspect of the library that I should mention at this point is its respect for the Global Namespace. All objects created by the library and its entire code run within, and can only be accessed through, the YAHOO Global Namespace object. This means that the entire library, including every utility and every control, and its numerous classes, create just one namespace object within the Global Namespace.

The Global Namespace is the global collection of JavaScript object names, and it is very easy to litter it with potentially conflicting objects, which can become a problem when code is shared between applications. Yahoo minimises its impact on the Global Namespace and so shall we; all of the code that we'll write throughout the course of this book will reside within its own namespace object.

Essentially, the YUI is a toolkit packed full of powerful objects that enables rapid front-end GUI design for richly interactive web-based applications. The utilities provide an advanced layer of functionality and logic to your applications, while the controls are attractive pre-packed objects that we can drop onto a page and begin using with little customization.

Who Is It for and Who Will It Benefit the Most?

The YUI is aimed at and can be used by just about anyone and everyone, from single-site hobbyists to creators of the biggest and best web applications around. Developers of any calibre can use as much or as little of it as they like to improve their site and to help with debugging.

It's simple enough to use for those of you that have just a rudimentary working knowledge of JavaScript and the associated web design technologies, but powerful and robust enough to satisfy the needs of the most aspiring and demanding developers amongst you.

The library will be of interest primarily to front-end developers, as the main aim of the YUI is to provide a framework within which robust and attractive interfaces can be quickly and easily designed and built. It can help you to side-step what can otherwise be insurmountable compatibility issues.

There is no set standard that says you must know this much or that much before you can begin to use the YUI. However, the more you know and understand about JavaScript itself, the more the library will make sense to you and the more that you will be able to gain from using it.

Trying to learn how to make use of the YUI without first knowing about the JavaScript language itself, at least to a basic working standard, is an endeavour likely to end in frustration and disappointment. It would be a great shame if a lack of understanding prevented you from enjoying the benefits that using the library can bring to both your creativity and creations.

So to get the most out of the YUI, you do need to have at least a basic understanding of JavaScript and the principles of object oriented programming. However, a basic working understanding is all that is required and those developers that have less knowledge of scripting will undoubtedly find that they come out of the experience of developing with the YUI knowing a whole lot more than they did to begin with.

The YUI can teach you advanced JavaScript scripting methods, coding and security best practices, and more efficient ways of doing what you want to do. It will even help more advanced programmers streamline their code and dramatically reduce their development time, so everyone can get something from it.

For some, the YUI is also a challenge; it's an excellent opportunity for developers to get involved in a growing community that is creating something inspiring. The Firefox browser is a great example of an open-source, community-driven, collaborative effort of separate but like-minded individuals. Some people may not want to develop web pages or web applications using the library: they may just want to be involved in evolving it to an even greater accomplishment.

I should also point out at this stage that like the library itself, this book expects you to have a prior knowledge and understanding of JavaScript, HTML, and CSS. While the use of the utilities, controls, and CSS tools will be explained in detail throughout the book, any HTML, CSS, or PHP code that is featured in any of the examples may not be explained in detail. Other skills, such as the ability to install and configure a web server, are also required.

Why the Yahoo! User Interface Library?

Using any JavaScript library can save you great amounts of time and frustration when coding by hand, and can allow you to implement features that you may not have the knowledge or skill to make use of. But why should you use the YUI rather than the many other libraries available?

To start with, as I'm sure you already know, Yahoo! is extremely well established, and at the forefront of cutting edge web technology and front-end design principles. The utilities and controls provided by the library have already been tried and tested in their world-class service provision environment. Hence you know that the components are going to work, and work in the way that you expect them to work and that Yahoo! says that they will.

The YUI library is not the only developer-centric offering to come from these world-class leaders and go on to achieve high levels of accomplishment and a following amongst developers; other very successful projects include the extensive Design Pattern library, Yahoo! Widgets, and the Yahoo! Music Engine. They also have a wide range of APIs for you to experiment and work with, so they have already shown a commitment of providing open-source tools designed to succeed.

Additionally, the library has already been publicly available for over a year and in this time has undergone rapid and extensive improvement in the form of bug fixes and additional functionality. Overall, it is not still in beta stage, and has been proven to be an effective addition to your development toolset. Like the Mozilla and Firefox browsers, it has a huge, world-wide following of developers, all seeking to further enhance and improve it.

There are some libraries out there that have been developed which seek to alter the JavaScript language itself, building capabilities into the language that the developers felt should already have been present and extending the language in new and interesting ways.

While these libraries can provide additional functionality at a deeper and more integrated level, their use can often be hampered by technical implementation difficulties that will be too difficult to overcome for all but the most advanced and seasoned developers.

The YUI is not like this; it is extremely well documented, stuffed full of examples, and is extremely easy to use. It doesn't get bogged down in trying to alter the JavaScript language at a fundamental level, and instead sits on top of it as a complimentary extension.

There's also no reason why you can't use the YUI library in conjunction with other JavaScript libraries if a particular feature, such as the rounding of box corners as provided by MochiKit for example, is required in your application but not provided by the YUI.

Graded Browser Support

Whichever browser you prefer, there's one thing that I think we can all agree on; all browsers are not created equal. Differing support and a lack of common standards implementation are things that have confounded web developers for as long as there have been web developers.

Although the situation is improving with agreed standards from the W3C, and better and more consistent support for these standards, we are far from being in a position where we can write a bit of code and know that it is going to function on any of the many browsers in use.

There may never come a time when this can be said by developers, but with the YUI, you can already count on the fact that the most popular browsers in use, on all manner of operating systems, are going to be able to take full advantage of the features and functionality you wish to implement.

It doesn't, and can't be expected to support every single web browser that exists, but it does group together common browsers with common capabilities into a graded support framework that provides as much as it can to visitors whichever browser they happen to be using.

Every single browser in existence falls into one of the defined grades; the most common class of browser are the A-grade variety of browsers, which are the browsers that the creators of the library actively support. These are modern, generally standards compliant, and capable of rendering in full the enhanced visual fidelity and advanced interface functionality provided by the library as well as the inner core of content.

X-grade browsers are generally unknown and untested, and account for a wide range of less common, often highly specific browsers that are simply assumed to be able to access the full, enhanced experience. Any browser that has not been extensively tested by the YUI development team is automatically an X-grade browser regardless of its capabilities; IE7 on Vista was classed as X-grade for some time after its release simply because it had not been fully tested by the Yahoo! team.

C-grade browsers are able to access the base or core content and functionality of the library components, but cannot handle the enhanced content. These are browsers that are simply not supported by the library.

Currently, the complete spectrum of A-grade browsers supported by the library includes the following browser and platform configurations:

  • IE7 on Windows XP and Vista

  • IE6 on Windows 98, 2000, Server 2003 and XP

  • Firefox 2.x on Windows 98, 2000, XP and Vista, and Mac OS 10.3 and 10.4

  • Firefox 1.5 on Windows 98, 2000 and XP, and Mac OS 10.3 and 10.4

  • Opera 9 on Windows 98, 2000 and XP, and Mac OS 10.3 and 10.4

  • Safari 2 on Mac OS 10.4

  • Safari 3 on Mac OS 10.4 and 10.5, Windows XP and Vista

These 27 common configurations are able to make use of not just the core content of any applications we create with the YUI, but also all of the enhanced functionality brought on by the library. Any browser not on this list will still receive either an A or C-grade experience, but may be classed as an X-grade browser if it has not been extensively tested.

The graded browser support strategy is based on the notion of progressive enhancement as opposed to graceful degradation. "Graceful degradation" is a term that I'm sure you've heard at some point and involves designing content so that, when it breaks in older browsers, it retains some semblance of order.

This method involves designing a page with presentation in your supported browsers as your main priority while still allowing unsupported browsers to view at least some kind of representation of your content.

Progressive enhancement approaches the problem of supporting browsers with different capabilities from the other way by providing a core of accessible content and then building successive layers of presentation and enhanced functionality on top of this inner core of generalized support.

This screenshot shows how the Rich Text Editor control appears in a C-grade browser. Older readers may recognize the browser used in this experiment as Netscape Navigator version 4, a popular browser approximately a decade ago.

As you can see from this example, the inner core of the page content is a standard HTML<textarea> element, which is displayed completely normally. The page doesn't break, but the high fidelity content is not displayed. Using graceful degradation techniques, the browser would probably attempt to display the Editor, but it would probably look very poor and would certainly not function.

The following screenshot shows how the editor appears in an A-grade browser:

In a capable, supported browser the library can transform the<textarea> element into the full Rich Text Editor control. Now, the following screenshot shows exactly the same page in exactly the same browser but with JavaScript switched off:

Notice the similarity between a C-grade browser and an A-grade browser with JavaScript switched off.

The knowledge that has enabled Yahoo! to use the concept of graded browser support has been gained from wide variety of user-agents that hit their site every single day. They've been accessed by over 10,000 different software and platform configurations since they began focusing on who and how their portal is accessed.

Approximately 96% of this total have received an A-grade experience when using the Yahoo! site, leaving just three percent that are classed as C-grade, and a minimal one percent classed as X-grade.

 

What Comes with the YUI?


Some JavaScript libraries are condensed into a single script file such as the jQuery library. While this can make linking to them easier, it can be inefficient depending on how much of the library you actually use.

The YUI Library is split into its constituent components, making it easy to pick and mix which utilities and controls are used, and making it much more efficient to implement. In addition to the large collection of JavaScript files the library provides a great deal more.

The Library Topography

The library is currently divided into four distinct sections; the library core files, a series of utilities, a set of controls, and some excellent CSS tools. There are a total of 33 different components, at the time of writing, and the library is continually growing and being refined.

There are also three versions of most of the library's utilities and controls, including a full version of the underlying JavaScript file that powers each component, complete with white space and comments for better readability and understanding, which can help your learning and development.

As well as the full versions, there are also -min.js and -debug.js versions of all the utilities and controls; the min (for minified) files have had all white space and comments removed, and variable names have been shortened where possible to cut down drastically on file size.

The min versions of each component are the ones served by Yahoo! and are perfect for production-release applications. These are the ones that you should be using most of the time in your own implementations, and the ones that we will be using throughout for most of the coding examples included in this book.

The debug version of each component is designed to be used in conjunction with the Logger Control rather than presented to your visitors. Along with white space and comments, these files also contain additional code which logs messages to the Logger console during key interactions within the components.

The differences between the full and min versions of each file can be quite large, with the min versions often being less than half the size of the full version. The only comment in each of the min files is the copyright notice, which has to stay intact in every file. Other than that, these files are pretty much solid chunks of hard code and readability is therefore very poor.

There are also three different file designations that each component can be classed as; fully released components are termed GA (for General Availability). GA components are typically the oldest, have been tested extensively, and had most of the bugs weeded out. They are reliable and have been considerably refined.

Beta designated utilities and controls are still in the process of being ironed out, but they have been released to the development community for wider testing, bug highlighting, and feature suggestion.

Any component termed experimental is still in the conceptual phase of its design and may or may not be promoted to Beta or GA status.

The Core Files

The core of the library consists of the following three files:

  • YAHOO Global Object

  • DOM Collection

  • Event Utility

The Global Object sets up the Global YUI namespace and provides other core services to the rest of the utilities and controls. It's the foundational base of the library and is a dependant of all other library components (except for the CSS tools). A useful browser detection method is also available via this utility.

The DOM Collection provides a series of convenience methods that make working with the Document Object Model much easier and quicker. It adds useful selection tools, such as those for obtaining elements based on their class instead of an id, and smoothes out the inconsistencies between different browsers to make interacting with the DOM programmatically a much more agreeable experience.

The Event utility provides a unified event model that co-exists peacefully with all of the A-grade browsers in use today and offers a consistent method of accessing the event object. Most of the other utilities and controls also rely heavily upon the Event utility to function correctly.

Since the core files are required in most YUI implementations, they have been aggregated into a single file: yahoo-dom-event.js. Using this one file instead of three individual files helps to minimise the number of HTTP requests that are made by your application.

The Utilities

The utilities provide you with different sets of user-interface functionality that you can implement within your web pages. They provide programming logic and deal specifically with the behaviour and interactions between your visitors and the different objects and elements on your pages.

They are more of a concept that you begin with and then build upon, and they provide the foundation from which you create your vision. They provide unseen behaviour; for example, the Animation utility isn't something your visitors will see directly, but its effects on the element being animated will of course be visible.

Like the core files of the library, the utilities have all been rolled up into one easy to link to master file: utilities.js. Again, this can be used to make your application run more efficiently when using all of the utilities together.

The set of utilities included in the current release of the library (which is constantly changing and growing) are as follows:

  • Animation Utility

  • Browser History Manager

  • Connection Manager

  • Cookie Utility [beta]

  • DataSource Utility [beta]

  • Drag and Drop Utility

  • Element Utility [beta]

  • Get Utility

  • ImageLoader Utility

  • JSON Utility

  • Resize Utility [beta]

  • Selector Utility [beta]

  • YUILoader Utility

The Controls

The controls on the other hand are a collection of pre-packaged objects that can be placed directly on the page as they are, with very little customization. Your visitors can then interact with them.

These are objects on the page that have properties that you can adjust and control, and are the cornerstone of any web-based user interface.

These controls will be highly recognisable to most visitors to your site and will require little or no learning in order to use. The complete suite of controls currently included with the library is:

  • AutoComplete Control

  • Button Control

  • Calendar Control

  • Charts Control [experimental]

  • Color Picker Control

  • Container

  • DataTable Control [beta]

  • ImageCropper [beta]

  • Layout Manager [beta]

  • Menu Control

  • RichTextEditor Control [beta]

  • Slider Control

  • TabView Control

  • TreeView Control

  • Uploader [experimental]

The CSS Tools

The CSS Tools form the smallest, but by no means the least useful, component of the library. The utilities and controls are designed to be used almost independently (although some of the files do depend on other files in the library to function properly), but the CSS tools are designed to be used together (although they can also be used separately if desired) and provide a framework for standardising the visual representation of elements on the page.

The following four tools make up the current CSS section of the library:

  • Reset CSS

  • Fonts CSS

  • Grids CSS

  • Base CSS

The CSS tools have just two versions of each CSS file instead of three: a full version and a minimum version; there are no debug versions in this section of the library. Like with the yahoo-dom-event utility, some of the CSS files have also been combined into one file for your convenience. You can use reset-fonts-grids.css or reset-fonts.css depending on your requirements.

The Library's Structure

Once the library has been unpacked, you'll see that there are a series of folders within it; the build folder contains production-ready code that you can use immediately on your web site. This is where the code that makes each component work, and all of its associated resources, such as images and style-sheets can be found.

The docs directory contains the complete API documentation for every library component. This is where you can find the classes that make up each component, look at the underlying code, and review the properties and methods available to you.

The examples folder contains a series of demonstrative web pages that highlight the key functionality or behaviour of each library component and mirrors the example space found online.

The tests folder contains a series of pages which use the Logger Control to check that each component is functioning correctly for the platform on which it is being run. Each method for the component being tested is called, and the results are logged for you to examine.

Another set of folders that you'll need frequently when using the library controls are the assets folders. Each of the controls has its own assets folder which contains things like supporting images and style-sheets, as well as the sam skin files (if applicable) for display purposes.

There are some other files and folders within the library, such as an index for the library so that you can easily look for documentation or examples and release notes. The screenshot on the next page shows the folder structure of the library.

Due to the changing nature of the beta, and the experimental utilities and controls, we will not be looking at them in any great detail in this book. For information regarding any of these components, see the YUI site and API guides.

What Else Does Yahoo! Provide?

There are some additional resources that are available courtesy of Yahoo! to help you use the library to its maximum potential. There are a series of very helpful "Cheat Sheets" that you can view online from any of the individual component's information pages, and which have also been bundled up into a zip file for you to download for offline viewing.

These resources provide a useful and centralised reference manual which lists the key methods, properties, and syntax patterns of each of the fully released components and gives some basic examples of their implementation.

Some of the beta and experimental components do not have their own cheat sheets as these are still subject to change. The cheat sheets for the rest of the components however, are extremely useful and act as an invaluable reference whilst working with the library.

There is a discussion forum which developers can use to discuss their projects and get help from experts. It's not a proper forum as such; it's actually a Yahoo! Group, which is kind of like a cross between a forum and a mailing list.

Nevertheless, if you've got a problem with getting a utility or control to do what you want it to, you can search the list of messages in the group to see what you're doing wrong, or submit a question if there is no information listed.

If you're a member of any other Yahoo! Groups already, you just need to join the ydn-javascript group. If not, you'll need to sign up for a free Yahoo! account and then join the group. There are tens of thousands of registered members and the number is growing on a daily basis, so if you do have any problems and find that you need to ask a question, there's a very good chance that someone, including the library's creators, will be willing and able to help.

The forum is home to a growing community of developers that have been brought together by the YUI; community involvement is an excellent way to connect with developers and can take a project in new and impressive directions.

To keep up-to-date on developments in the YUI and read associated news statements and technical articles about the library and the Yahoo! Developer Network in general, or to watch screen casts from the development team and other experts, you can visit the YUI blog at http://yuiblog.com.

This is a companion blog not just for the YUI library but also for the Yahoo! Design Pattern Library. This is separate from the YUI and is not something that we'll be looking at in this book, but it is worth mentioning because the two libraries can be used together in many situations.

The entire selection of different video screencasts and podcasts are brought together in one place for easy searching in the YUI theatre. Both the blog and the theatre are subscribable via RSS, so that you can have up-to-date news and announcements surrounding the library.

There is also a section of the YUI site where you can look at the implementations of the library by other people and on other web sites. There are only a few showcase examples listed on this page, and some of the examples link to other parts of the Yahoo! network rather than to external sites, but there are a couple of high profile sites using YUI and this page can be a great place to find inspiration.

This page is also where you can find links to the online component examples. These are detailed examples that demonstrate the default, core abilities of each module in an uncluttered environment and have been provided by the actual developers of the utilities and controls.

Finally, there are a few interesting articles about different aspects of the library that can be found on the YUI developer site. The first article is an FAQ that provides some standard answers to some standard questions.

Other articles discuss topics such as Yahoo's approach to graded browser support, the benefits of serving library files from Yahoo! servers, and current best practice with regard to security measures.

For those of you that want to join the YUI development community and give something back to the Yahoo! Developers that have bestowed this awesome tool upon us, there is also the facility to submit bug reports or feature requests.

This is an excellent channel of feedback and as the YUI team point out, many useful features have been added to the library following a feature request. It also allows the team to remove errors and refine the features of existing components.

Are There Any Licensing Restrictions?

All of the utilities, controls, and CSS resources that make up the YUI have been publicly released, completely for free, under the open-source BSD license. This is a very unrestrictive license in general and is popular amongst the open-source community.

For those of you who don't know anything about what the license stands for and what it allows you to do, I'll give you quick overview now so that you need not worry about it again. Consider these next few paragraphs your education in open-source software licensing!

BSD stands for Berkeley Software Distribution and was originally designed and used by a team of developers who created an open-source operating system of the same name that was similar in many ways to the UNIX platform (and even shared part of its code-base with it). Many of today's most popular operating systems, including Windows and OSX are derived from or contain code from the original BSD operating system.

The current BSD version, sometimes known as the New BSD license, differs from the original in that it has had the restrictive UC Berkeley advertising clause removed, making it almost equivalent to the MIT license but with the addition of a brief final clause prohibiting the use of the copyright owners name for endorsement without obtaining prior consent.

This means that you can pretty much do whatever you want to do with the library source code; you can use it as it is, you can modify it as you wish, add to it, or even remove bits. You can use the files in the format in which they are provided, or you can use the code within them in the distribution of a compiled, closed-source application.

You can use it in your own personal projects, as part of a commercial venture or even within an educational framework. You can do all of this provided that you retain the copyright notice in your source code, or the copyright notice present on each of the library files remains intact.

If you're using the library files as the original JavaScript files as they come in the library, all you need to do is make sure that the existing copyright notice is left at the top of every file that you use. In a compiled application, it should be clearly visible in the help section or user manual.

 

Installing the YUI


The YUI is not an application in its own right, and it doesn't need to be installed as such. Getting started with the YUI is extremely simple; you first choose whether to download all of the source files from Yahoo and use them locally as part of your web sites' hierarchy, or whether to use the URLs provided on the YUI developer pages to reference the library files stored on Yahoo's web server.

These are the exact same files that are used in many different interface implementations across the Yahoo! network and as such can be depended on for being almost continuously available, and even if Yahoo! does decide to take these files down at some point in the future, I'm sure that this will be announced in a timely manner.

Another benefit of using Yahoo's network bandwidth to provide the functionality behind your application is that their network is global in nature, with servers running in many geographically distinct parts of the world.

Being able to serve library files from a location closer to your visitors' location results in a better response from your application; this is good news for your visitors and therefore good news for your business.

Additionally, as I mentioned earlier, there are different versions of each of the working files in the library including a 'minified' file that has been stripped of whitespace and comment blocks. The Yahoo servers provide these minified versions of the files, but in addition, they also serve the files in a GZIP format, making the files up to 90% smaller and therefore, much more efficient for transportation across the Internet. Finally, Yahoo! also helps the cache hit rates by issuing expires headers with expiration dates set far in the future. But best of all, these benefits are all provided for free.

If you've decided that you want to download the YUI in its entirety, you'll find a link on the YUI home page at http://developer.yahoo.com/yui which will lead you to the library's project site at SourceForge.net.

SourceForge is renowned as the world's largest open-source software development site and currently host over 100,000 different projects. All you really need from there is the library itself as virtually all of the documentation and useful information resides on the YUI site on the Yahoo! portal.

So as far as installing the library goes, the most that you'll need to do is to download the library to your computer and unpack it to a local directory where you can easily find the files, assets, and resources that you require for your current project, and if you choose to let Yahoo! host the files for you, you won't even need to do that.

Creating an Offline Library Repository

In order to follow the examples in this book, you will need to download a copy of the library and ensure that it is accessible to the pages that we are going to make. So you will need to create a new folder on your hard drive called yuisite. This folder is where all of our examples will reside.

Inside this folder, create another new folder called yui. When you unpack the library, you will see a folder called build inside it (as in the previous screenshot). You will need to copy and paste the entire build directory into the yui folder that you have just created. You won't need to add any files to the build directory, all of the files that we create will sit in the yuisite folder.

It is important that this structure is correct; otherwise none of the examples that we create as we progress through this book will work. A common indicator that library files are not accessible is a JavaScript error stating that YAHOO is undefined.

 

Using the Library Files in Your Own Web Pages


One thing that you need to check when using different controls and utilities from the library is which, if any, of the other utilities will be needed by the component that you wish to use; fortunately the online documentation and cheat sheets will list out any dependencies of any component that you choose, so finding out isn't hard.

There is only one file that must be used in every implementation of any of the various components: the YAHOO Global Object. This utility creates the namespaces within which all of the YUI library code resides, and contains some additional methods that are used by other files throughout the library.

It must appear before any of the other library files because if references to other component files appear before the Global Object, none of the namespaces used will be recognised by your script. This will cause a JavaScript error stating that YAHOO is undefined.

The CSS files should be linked to in the<head> section of your page, as any other CSS file would be. For SEO purposes, and to support the notions of progressive enhancement, the JavaScript that invokes and customises the library components should be as close to the bottom of the page as possible. Also, you can easily separate your JavaScript from your HTML altogether and keep your scripts in separate files.

To use the animation utility from the Yahoo! servers for example, the following script tag would be required:

<script type="text/javascript" src="http://yui.yahooapis.com/ current_version/build/animation/animation-min.js">
</script>

As the animation utility also depends on the YAHOO Global Object, and the Event and DOM utilities, the yahoo-dom-event utility should also be used (but don't forget that the YAHOO Global Object must appear first), so the script tag shown below would actually have to appear before the above one:

<script src="http://yui.yahooapis.com/current_version/build/
yahoo-dom-event/yahoo-dom-event.js">
</script>

Once these script tags have been added to your page, the code required to animate your object or element would go into its own script tag in the<body> section of the page.

Now, we'll take our first look at one of the library components in detail: the Calendar control. We can take a quick look at its supporting classes to see what methods and properties are available to us, and can then move on to implement the control in the first of our coding examples.

 

Code Placement


Good coding practice should always be adhered to, whether designing with the YUI or not. Keeping your JavaScript and CSS code in separate files helps to minimise the amount of code that a search engine spider has to index, which could help contribute to a better results page listing. But it does have its downsides too; every file that your page links to adds another HTTP request to the interaction between your visitor and your server, which can result in slower performance.

In real-world implementations, we would always keep as much of our JavaScript and CSS in separate files as possible, keeping a clear distinction between content, behaviour, and presentation layers. For the purpose of this book however, we will be keeping the HTML and JavaScript code in one file. I stress that this is not the correct way to do things and is done purely so that the examples do not become bloated with numerous files.

 

Perfect Date Selection with the Calendar Control


For our first coding example, we'll take a quick look at the Calendar Control. The YUI Calendar allows you to easily create a variety of attractive and highly functional calendar interfaces which can allow your visitors to quickly and easily select single dates, or range of dates.

It's an easy component to master, making it ideal for our very first coding example. Not much coding is required for a basic calendar implementation, and the control can easily be customized using the Calendar classes' extensive range of properties, or by over-riding the default styling.

There is also a range of different formats of Calendar that we can create; there's the basic, single-select, one-page calendar control which displays one month at a time, or there's a larger, multi-page calendar which allows multiple months to be displayed at once. Multi-select calendars can come in either single or multiple month display formats.

The rendered calendar is instinctively intuitive to use and is presented in a very attractive manner. Almost anyone being presented with it will instantly know how to use it. By default, it features a clear and sensible interface for selecting a date, arranging the dates of the current or starting month in a grid headed by the day of the week.

It also features automatic rollovers for valid or selectable dates, automatic current date selection, and an infinite date range both forwards and backwards in time that the visitor can move through to select the date of their choice. When navigating between months, the individual days automatically reorder themselves so that the correct date appears in the correct day of the week.

Several supporting classes make up the Calendar control; two separate classes represent the two different types of calendar that can be rendered and another class contains math utilities which allow you to add, subtract, or compare different dates. We will take a look at the classes that make up this control to see what is available and exactly how it works before we begin coding.

The Basic Calendar Class

The most basic type of calendar is the single-panel Calendar which is created with the YAHOO.widget.Calendar class. To display a calendar, an HTML element is required to act as a container for the calendar. The screenshot shows a basic Calendar control:

The constructor can then be called specifying, at the very least the id of the container element as an argument. You can also specify the id of the Calendar object as an argument, as well as an optional third argument that can accept a literal object containing various configuration properties.

The configuration object is defined within curly braces within the class constructor. It contains a range of configuration properties and keys that can be used to control different Calendar attributes such as its title, a comma-delimited range of pre-selected dates, or a close button shown on the calendar.

There are a large number of methods defined in the basic Calendar class; some of these are private methods that are used internally by the Calendar object to do certain things and which you normally wouldn't need to use yourself. Some of the more useful public methods include:

  • Initialisation methods including init, initEvents, and initStyles which initialise either the calendar itself or the built-in custom events and style constants of the calendar.

  • A method for determining whether a date is outside of the current month: isDateOOM.

  • Navigation methods such as nextMonth, nextYear, previousMonth, and previousYear that can be used to programmatically change the month or year displayed in the current panel.

  • Operational methods such as addMonths, addYears, subtractMonths, and subtractYears which are used to change the month and year shown in the current panel by the specified number of months or years.

  • The render method is used to draw the calendar on the page and is called in for every implementation of a calendar, after it has been configured. Without this method, no Calendar appears on the page.

  • Two reset methods: reset which resets the Calendar to the month and year originally selected, and resetRenderers which resets the render stack of the calendar.

  • Selection methods that select or deselect dates such as deselect, deselectAll, desellectCell, select, and selectCell.

As you can see, there are many methods that you can call to take advantage of the advanced features of the calendar control.

The CalendarGroup Class

In addition to the basic calendar, you can also create a grouped calendar that displays two or more month panels at once using the YAHOO.widget.CalendarGroup class. The control automatically adjusts the Calendar's UI so that the navigation arrows are only displayed on the first and last calendar panels, and so that each panel has its own heading indicating which month it refers to.

The CalendarGroup class contains additional built-in functionality for updating the calendar panels on display, automatically. If you have a two-panel calendar displaying, for example, January and February, clicking the right navigation arrow will move February to the left of the panel so that March will display as the right-hand panel. All of this is automatic and nothing needs to be configured by you.

There are fewer methods in this class; some of those found in the basic Calendar class can also be found here, such as the navigation methods, selection methods, and some of the render methods. Native methods found only in the CalendarGroup class include:

  • The subscribing methods sub and unsub, which subscribe or unsubscribe to custom events of each child calendar.

  • Child functions such as the callChildFunction and setChildFunction methods which set and call functions within all child calendars in the calendar group.

 

Implementing a Calendar


To complete this example, the only tool other than the YUI that you'll need is a basic text editor. Native support for the YUI is provided by some web authoring software packages, most notably Aptana, an open-source application that has been dubbed 'Dreamweaver Killer'. However, I always find that writing code manually while learning something is much more beneficial.

It is very quick and easy to add the calender, as the basic default implementations require very little configuration. It can be especially useful in forms where the visitor must enter a date. Checking that a date has been entered correctly and in the correct format takes valuable processing time, but using the YUI calendar means that dates are always exactly as you expect them to be.

So far we've spent most of this chapter looking at a lot of the theoretical issues surrounding the library; I don't know about you, but I think it's definitely time to get on with some actual coding!

The Initial HTML Page

Our first example page contains a simple text field and an image which once clicked will display the Calendar control on the page, thereby allowing for a date to be selected and added to the input. Begin with the following basic HTML page:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<title>YUI Calendar Control Example</title>
<link rel="stylesheet"
type="text/css"
href="yui/build/calendar/assets/skins/sam/calendar.css">
<script type="text/javascript"
src="yui/build/yahoo-dom-event/
yahoo-dom-event.js"></script>
<script type="text/javascript"
src="yui/build/calendar/calendar-min.js"></script>
<style type="text/css">
input {
margin:0px 10px 0px 10px;
}
</style>
</head>
<body class="yui-skin-sam">
<div>
<label>Please enter your date of birth:</label>
<input type="text" name="dobfield" id="dobfield">
<img id="calico" src="icons/cal.png"
alt="Open the Calendar control">
</div>
<div id="mycal"></div>
</body>
</html>

We begin with a valid DOCTYPE declaration, a must in any web page. For validity, we can also add the lang attribute to the opening<html> tag and for good measure, enforce the utf-8 character set. Nothing so far is YUI-specific, but coding in this way every time is a good habit.

We link to the stylesheet used to control the appearance of the calendar control, which is handled in this example by the sam skin within the<link> tag. Accordingly, we also need to add the appropriate class name to the<body> tag.

Following this, we link to the required library files with<script> tags; the calendar control is relatively simple and requires just the YAHOO, DOM, and Event components (using the aggregated yahoo-dom-event.js file for efficiency), as well as the underlying source file calendar-min.js.

A brief<style> tag finishes the<head> section of the page with some CSS relevant to this particular example, and the<body> of the page at this stage contains just two<div> elements: the first holds a<label>, text field, and a calendar icon (which can be used to launch the control), while the second holds the calendar control. When viewed in a browser, the page at this point should appear like this:

Note

The calendar icon used in this example was taken, with gratitude from Mark Carson at http://markcarson.com.

Beginning the Scripting

We want the calendar to appear when the icon next to the text field is clicked, rather than it being displayed on the page-load, so the first thing we need to do is to set a listener for the click event on the image.

Directly before closing</body> tag, add the following code:

<script type="text/javascript">
//create the namespace object for this example
YAHOO.namespace("yuibook.calendar");
//define the lauchCal function which creates the calendar
YAHOO.yuibook.calendar.launchCal = function() {
}
//create calendar on page load
YAHOO.util.Event.onDOMReady(YAHOO.yuibook.calendar.launchCal);
</script>

Let's look at each line of the above code. We first use the .namespace() method of the YAHOO utility to set up the namespace object used for this example. Next we define the anonymous launchCal function, which will hold all of the code that generates the calendar control.

Then we use the .onDOMReady() method of the Event utility to execute the launchCal function when the DOM is in an usable state. We'll be looking at the DOM utility in much greater detail later in the book.

Now we can add the extremely brief code that's required to actually produce the Calendar. Within the braces of our anonymous function, add the following code:

//create the calendar object, specifying the container
Var myCal = new YAHOO.widget.Calendar("mycal");
//draw the calendar on screen
myCal.render();
//hide it again straight away
myCal.hide();

This is all that we need to create the Calendar; we simply define myCal as a new Calendar object, specifying the underlying container HTML element as an argument of the constructor.

Once we have a Calendar object, we can call the .render() method on it to create the calendar and display it on the page. No arguments are required for this method. Since we want the calendar to be displayed when its icon is clicked, we hide the calendar from view straight away.

To display the calendar when the icon for it is clicked, we'll need one more anonymous function. Add the following code beneath the .hide() method:

//define the showCal function which shows the calendar
Var showCal = function() {
//show the calendar
myCal.show();
}

Now we can attach a listener which detects the click event on the calendar icon:

//attach listener for click event on calendar icon
YAHOO.util.Event.addListener("calico", "click", showCal);

Save the file that we've just created as calendar.html or similar in your yuisite directory. If you view it in your browser now and click the Calendar icon, you should see this:

The calendar is automatically configured to display the current date, although this is something that can be changed using the configuration object mentioned earlier.

If you use a DOM explorer to view the current DOM of a page with an open calendar on it, you'll see that a basic Calendar control is rendered as a table with eight rows and seven columns.

The first row contains the images used to navigate between previous or forthcoming months and the title of the current month and year. The next row holds the two-letter representations of each of the different days of the week, and the rest of the rows hold the squares representing the individual days of the current month. The screenshot on the next page show some of the DOM representation of the Calendar control used in our example page:

Now that we can call up the Calendar control by clicking on our Calendar icon, we need to customize it slightly. Unless the person completing the form is very young, they will need to navigate through a large number of calendar pages in order to find their date of birth. This is where the Calendar Navigator interface comes into play.

We can easily enable this feature using a configuration object passed into the Calendar constructor. Alter your code so that it appears as follows:

//create the calendar object, using container & config object
myCal = new YAHOO.widget.Calendar("mycal", {navigator:true});

Clicking on the Month or Year label will now open an interface which allows your visitors to navigate directly to any given month and year:

The configuration object can be used to set a range of calendar configuration properties including the original month and year displayed by the Calendar, the minimum and maximum dates available to the calendar, a title for the calendar, a close button, and various other properties.

Let's update our Calendar instance so that it features a title and a close button. Add the following properties to the literal object in our constructor:

//create the calendar object, specifying the container and a literal
//configuration object
myCal = new YAHOO.widget.Calendar("mycal", {navigator:true, title:"Choose your Date Of Birth", close:true});

This is what our Calendar should now look like:

Configuration properties like those we have just set, can also be set outside of the constructor using the .queueProperty() and .fireQueue() methods, or by using the .setProperty() method. Let's use these to alter our Calendar so that the first column header is set to Monday instead of Sunday. Add the following code directly before the call to the .render() method:

//configure the calendar to begin on Monday
myCal.cfg.setProperty("start_weekday", "1");

When the calendar is displayed now, Monday will be the first day instead of Sunday:

Finally, we need to add some additional code that will allow the date that is selected to be inserted into the text field. We can do this using some of the custom events defined by the calendar classes.

Highly Eventful

Both the Calendar and CalendarGroup classes have a series of custom events defined for them which allow for easily listening and reacting to interesting moments during any calendar or calendar group interaction.

The two classes both have the same set of events defined for them, including:

  • beforeDeselectEvent: Fired before a cell is deselected, allowing you to abort the operation if needed

  • beforeHideEvent: Fired just before the calendar is hidden

  • beforeHideNavEvent: Fired just before the calendar navigator is hidden

  • beforeRenderEvent: Fired before the calendar is drawn on screen

  • beforeSelectEvent: Fired before a cell is selected

  • beforeShowEvent: Fired just before the calendar is shown

  • beforeShowNavEvent: Fired just before the calendar navigator is shown

  • changePageEvent: Fired once the current calendar page has been changed

  • clearEvent: Fired once the calendar has been cleared

  • deselectEvent: Fired once the cell has been deselected

  • hideEvent: Fired once the calendar has been hidden

  • hideNavEvent: Fired once the calendar navigator has been hidden

  • renderEvent: Fired once the calendar has been drawn on screen

  • resetEvent: Fired once the calendar has been reset

  • selectEvent: Fired once a cell, or range of cells, has been selected

  • showEvent: Fired once the calendar has been shown

  • showNavEvent: Fired once the calendar navigator has been shown

This rich event system allows you to easily watch for cells being selected or deselected, month panel changes, render events, or even the reset method being called, and add code to deal with these key moments effectively. As you can see, most of the events form pairs of before and after events, which allows you to easily cancel or abort an operation before it has any visual impact.

Let's now take a look at how these custom Calendar events can be used. First define the function that will handle the select event; add the following code directly after the showCall() function:

//attach listener for click event on calendar icon
YAHOO.util.Event.addListener("calico", "click", showCal);
//define the ripDate function which gets the selected date
var ripDate = function(type, args) {
}
//subscribe to the select event on Calendar cells
myCal.selectEvent.subscribe(ripDate);

Every time the select event is detected, our ripDate function will be executed. The type and args objects are automatically created by the control; the args object is what we are interested in here, because it gives us easy access to an array of information about our Calendar.

Now, within the curly braces of the ripDate() function set the following variables:

//get the date components
Var dates = args[0];
Var date = dates[0];
Var theYear = date[0];
Var theMonth = date[1];
Var theDay = date[2];

The first item in the args array is an array of selected dates, so we first save this to the variable dates. As this is a single-select calendar, only the first item of the dates array will contain data, so this is also saved to a variable: the date variable.

Each date is itself an array, with the first item corresponding to the year, the second item equaling the month, and the third item mapped to the individual date. All of these values are saved into variables.

Var theDate = theMonth + "/" + theDay + "/" + theYear;

This part of the function uses standard concatenation techniques to build a string containing the individual date components in the format in which we want to present them (so that, for example, it would be extremely easy to express dates in UK format, where the date appears before the month):

//get a reference to the text field
Var field = YAHOO.util.Dom.get("dobfield");
//insert the formatted date into the text field
field.value = theDate;
//hide the calendar once more
myCal.hide();

Finally, we use the very handy DOM utility's .get() method to grab a reference to the text field, set the value of the text field to our date string, and then hide the calendar once more.

Save the file once more and view it again in your browser of choice. After clicking the Calendar icon and choosing a date, it should be displayed in the text field:

At this point, we can take a brief look at how we can override the default styling of the calendar. I think we should change the calendar's close button and make it look a little more like a traditional close button. This can be done with the following simple CSS rule, which should be inserted into the<style> tag in the<head> of our document:

.yui-skin-sam .yui-calcontainer .calclose {
background:url("icons/myclose.gif") no-repeat;
}

Because we're using the default sam skin, we should begin the selector with this class name and then target the name of the container and close elements. Other elements of the calendar, such as the navigation arrows, can easily be styled in this way. Using a DOM explorer to expose the names of other parts of the calendar is also an easy way to change other elements of the calendar. Our Close button should now appear like this:

The DateMath Class

In addition to the two classes catering for two different types of calendar, a class, YAHOO.widget.DateMath, defines a series of utilities for performing simple mathematical calculations or comparisons on dates. It has only a small number of static properties and a small set of methods. There are no events defined in this class and no configuration attributes.

All of its methods return either a boolean value indicating whether the comparison was true or false, or a modified date object. Some of them will be used very frequently, while others will be used only rarely (but are still very useful).

Our date of birth calendar isn't really appropriate for seeing how the DateMath calls can be used. In order to examine some of the available methods, we should create a new calendar. In a blank page of your text editor, begin with the following HTML:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<title>YUI MathDate Class Example</title>
<link rel="stylesheet"
type="text/css"
href="yui/build/calendar/assets/skins/sam/calendar.css">
<script type="text/javascript"
src="yui/build/yahoo-dom-event/yahoo-dom-event.js">
</script>
<script type="text/javascript"
src="yui/build/calendar/calendar-min.js"></script>
</head>
<body class="yui-skin-sam">
<div id="mycal"></div>
<div id="results"></div>
</body>
</html>

This very simple page will form the basis of our example. Next, add the following<script> tag to the<body> tag of the page, directly below the results<div> tag:

<script type="text/javascript">
//create the namespace object for this example
YAHOO.namespace("yuibook.calendar");
//define the initCal function which creates the calendar
YAHOO.yuibook.calendar.initCal = function() {
}
//create calendar on page load
YAHOO.util.Event.onDOMReady(YAHOO.yuibook.calendar.initCal);
</script>

We create the same namespace object for this page and initially generate the calendar using the .onDOMReady() method and an anonymous function in exactly the same way as we did before. Next, add the following code to the YAHOO.yuibook.calendar.initCal() function:

//create the calendar object, specifying the container
var myCal = new YAHOO.widget.Calendar("mycal");
//draw the calendar on screen
myCal.render();

We create the calendar in the same way as in the previous example and render it on the page. This time, we don't need to worry about hiding it again as it will be a permanent fixture of the page.

Before we start looking at the DateMath methods, let's get a reference to the current date. Add the following code directly below the .render() method call:

//get and display today's date
var dayNum = myCal.today.getDay();
var dayString = myCal.Locale.WEEKDAYS_LONG[dayNum];
var date = myCal.today.getDate();
var monthNum = myCal.today.getMonth();
var monthString = myCal.Locale.MONTHS_LONG[monthNum];
var year = myCal.today.getFullYear();
var results1 = document.createElement("div");
results1.innerHTML = "Today is " + dayString + ", " + date + "
" + monthString + " " + year;
YAHOO.util.Dom.get("results").appendChild(results1);

It is easy to obtain today's date in UTC format using the today property of the Calendar class. Once we have this, we can get references to the date and month numerical representations and from these we can get the full day name and month name using Locale.WEEKDAYS_LONG[dayNum] and Locale.MONTHS_LONG[monthNum].

The Locale object is automatically created by the control and contains localised day and month names. It is primarily used to add new locales and specify alternative day and month names, but because it defaults to English, we can simply read the properties and pull out what we want.

Once we have the information we need, it is simple enough to create a new<div> element, populate it with our formatted date string and then attach it to our results<div> element. Your page should look similar to the following screenshot:

Now we can have some fun with a few of the DateMath methods. First, add the following directly beneath our last block of code:

//work out date in 10 days time
DataMath classmethodsvar futureDate = YAHOO.widget.DateMath.add(myCal.today,
YAHOO.widget.DateMath.DAY, 10);
var results2 = document.createElement("div");
results2.innerHTML = "In ten days time it will be " + futureDate;
YAHOO.util.Dom.get("results").appendChild(results2);

We can use the .add() method of the YAHOO.widget.DateMath class to add a specified amount of time to a date object. In this example, the date object is obtained using the myCal.today property once more (as we can't use the date variable that already exists as this is a number not a full date object), but any date object could be used.

The .add() method takes three arguments. The first is the date object on which the addition should be carried out, the second is one of the built-in field constants representing the unit to be added (which could be days, weeks, months, years), and the final argument is the actual amount to be added.

For the purposes of this example, I have left the futureDate field in full UTC format, but we could easily extract just the parts of the date that we want, just as we did to get the today date.

Let's now look at the almost identical .subtract() method. Add the following code:

//work out date two months ago
var pastDate = YAHOO.widget.DateMath.subtract(myCal.today,
YAHOO.widget.DateMath.MONTH, 2);
var results3 = document.createElement("div");
results3.innerHTML = "Two months ago the date was " + pastDate;
YAHOO.util.Dom.get("results").appendChild(results3);

You can see how easy the DateMath class makes addition and subtraction of date objects. The class has other useful methods such as the .getDayOffset() and .getWeekNumber() methods. We can expose the functionality of these two methods with the following code:

//work out day and week numbers of current date
DataMath classmethodsvar numberOfDays = YAHOO.widget.DateMath.getDayOffset(myCal.today,
year);
var weekNumber = YAHOO.widget.DateMath.getWeekNumber(myCal.today,
year);
results4 = document.createElement("div");
results4.innerHTML = numberOfDays + " days have elapsed so far this
year";
results5 = document.createElement("div");
results5.innerHTML = "We are in week number " + weekNumber;
YAHOO.util.Dom.get("results").appendChild(results4);
YAHOO.util.Dom.get("results").appendChild(results5);

Save the file as datemath.html and view it in your browser of choice:

 

Summary


During the course of this chapter we have taken an in-depth view into what the YUI is, where it came from, and the things that spurred it into existence. We have seen everything that the license gives us permission to do and investigated the different ways of serving the files that power it. We've also looked at who can make the most of the library, how to install it, and how to use it in your own web pages.

Lastly, we finished off all the theory with a practical example that had you creating and customising your first user interface control: a calendar, and working with one of its supporting classes: the DateMath class. I hope that this first example has made you eager to experiment with the library further and has shown you how easy it is to implement YUI components.

About the Author

  • Dan Wellman

    Dan Wellman is an author and frontend engineer living on the South Coast of the UK and working in London. By day he works for Skype and has a blast writing application-grade JavaScript. By night he writes books and tutorials focused mainly on frontend web development. He is also a staff writer for the Tuts+ arm of the Envato network, and occasionally writes for .Net magazine. He's the proud father of four amazing children, and the grateful husband of a wonderful wife.

    Browse publications by this author
Learning the Yahoo! User Interface library
Unlock this book and the full library for $5 a month*
Start now