Experience

Experience JavaScript Library Manual

1. Introduction

Welcome to Experience manual! This manual provides instructions for how to use Experience in your web pages, a reference documentation for Experience API and even sometimes notes on the design and future plans for Experience.

If you have any suggestions or comments to improve the documentation, you can reach me directly at ahmeds[at]users.sourceforge.net

Enjoy!

2. The experience Namespace

experience serves as the top level namespace for the library and thus all Experience-related objects and classes are declared within it. It also contains objects that provide services used across all the library (like i18n support, for example.)

2.1 API Reference

experience.Core

Core's main purpose is to (optionally) initialize Experience with library-wide parameters but it also encapsulates general utility methods.It's the only public singleton object in the experience namespace. It It supports the following methods:

initialize( params )

Initializes Experience. Optionally calling it with one or more parameters in a hash-like object before using any Experience components will apply the effects of these parameters on any Experience components used after initialization. See the design note at the end of this section.

Example: 
 experience.Core.initialize({ Locale: "ar" }); // Use Arabic locale
Supported Parameters:
Name Required Default Value Description
Locale No 'en_US' Specifies the locale in which messages and labels are displayed. Currently Experience ships with English (en_US) and Arabic (ar) locales.
InterfaceDir No 'ltr' Hints components for which direction they should render their interface according to (but no components currently utilize this value)

bindTip( element, html, customCSSClass = 'experienceTip')

Binds a DHTML tooltip to the element specified by the first argument (or an ID). The tip shows the html specified by the second argument. To style the tips define a CSS class named experienceTip or pass a class name(s) as the third argument.

Example: 
 experience.Core.bindTip('bindToMe', 'Hello! I\'m a cool tooltip!');

unbindTip( element )

Unbinds the DHTML tooltip that was previously bound by bindTip.

initialize Methods

Some functionality in Experience is encapsulated as singleton objects with initialize methods. It takes only one argument that is a hash-like object acting as a map between parameters and values. Unless otherwise stated, calling it is mandatory only when it has required parameters that have no default values. Moreover, subsequent calls to initialize retain the old values of parameters that were not explicitly overridden by specifying new values.

3. Components

This section provides a guide to use Experience components. Each component sub-section starts with a description of the component then moves on to how to use it and finally provides a reference for it's API.

3.1 Experience::Panorama

Panorama is an image viewer. It's designed to enable users to view really large images conveniently performing simple, but very useful operations, like panning and zooming the image and so they don't have to deal with annoying scrollbars. It also features a "navigator" (4 arrows pointing to opposite directions) for automatically scrolling the image and a zoom percentage select box (that also serves as a percentage indicator) like those found is popular image manipulation applications. Please see the demonstration page to actually experience Panorama!

3.1.1 How to Use Panorama

Here's a complete working example (assuming you have unpacked the Experience library distribution to the root of your server) ..

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <!--  Import the prototype library -->
    <script type="text/javascript" src="prototype-1.5.0.js"></script>

    <!--  Import the base Experience namespace -->
    <script type="text/javascript" src="experience.js"></script>

    <!--  Import Experience::Panorama files -->
    <script type="text/javascript" src="experience.panorama.js"></script>
    <link rel="stylesheet" type="text/css" href="experience.panorama.css" />

    <!-- Initialize Panorama -->
    <script type="text/javascript">

    var viewer;

    /* Replace the parameter values with your image's URL, width and height */
    window.onload = function() {
        viewer = new experience.panorama.Viewer({ 
                    ImageURL: "example.jpg", 
                    ImageWidth: 797, 
                    ImageHeight: 1000 
                });
    }

    </script>

    <!-- Done! -->
</head>
<body>
    <!-- Click start to open Panorama in full-window mode -->
    <a href="#" onclick="viewer.show()">Start</a>
</body>
</html>

3.1.1 API Reference

The Experience::Panorama component is contained within the experience.panorama namespace.

experience.panorama.Viewer

Viewer is the class used to instantiate Panorama viewers. It supports the following methods:

[constructor]( params )

Creates a Panorama viewer.

Example: 
/* Create a Panorama viewer passing in the required parameters */
var viewer = new experience.panorama.Viewer({ 
    ImageURL: "example.jpg", 
    ImageWidth: 797, 
    ImageHeight: 1000 
});
Supported Parameters:
Name Required Default Value Description
ImageURL Yes   Specifies the URL of the image to be displayed. You have to specify ImageWidth and ImageHeight as well. See also the setImage method.
ImageWidth Yes   Specifies the width (in pixels) of the image to be displayed.
ImageHeight Yes   Specifies the height (in pixels) of the image to be displayed.
ZoomFactor No 0.05 Specifies the percentage of the current image size in which Panorama zooms in/out.
MoveBy No 2 Specifies the length (in pixels) of the "step" in which the navigator moves the image.
MoveRate No 15 Specifies the rate (in milliseconds) in which the navigator move the image a step.
ReversePanning No false Tells Panorama whether to reverse panning direction or not.
ReverseScrolling No true Tells the navigator whether to reverse the direction of automatic scrolling or not.
InnerUpperOffset No 40 Specifies the top-left inner offset (in pixels) between Panorama edges and an image when viewing an image whose dimensions are larger than Panorama's. When an image dimension is smaller than Panorama's, it's centered.
ShowStatus No true Tells Panorama whether to indicate current status or not. It indicates status in text next to the zoom percentage select box.
ShowNavigator No true Tells Panorama whether to show the navigator or not.
ShowZoomSelectBox No true Tells Panorama whether to show zoom percentage select box or not.
IconDirectory No 'icons' Tells Panorama where to look for the directory containing Panorama icons.
IconExtension No '.gif' The file extension Panorama uses while loading icon images which are located in the directory specified by the IconDirectory parameter. Change this only if you have created a new icon theme with a different file extension than .gif.
RenderIn No null Specifies an element (or it's ID) in which the viewer will render itself. If not specified, the viewer a will render itself in full-window mode.

show()

Sets the viewer to be visible. The viewer is by default invisible in full-window mode and visible when using the RenderIn parameter.

hide()

Sets the viewer to be invisible.

setImage( url, width, height )

Changes the image currently displayed in the viewer. It accepts three required arguments specifying a new image URL, width and height (in pixels), respectively.

Example: 
 viewer.setImage('http://example.com/example.jpg', 400, 500);

getImage()

Returns a three-element array containing currently displayed image URL, width and height (in pixels), respectively.

addOnFullWindowListener( listener )

Adds a listener (a function) to be called just before the viewer will occupy the whole window. This works for both when the viewer is used only in full-window mode (without specifying a RenderIn parameter) after calling show no it or when the viewer was rendered in an element and the user clicked the Go Full-Window icon. It's useful for adding a chuck of code to be executed before the viewer goes full-window.

removeOnFullWindowListener( listener )

Removes a listener (a function) that was added through addOnFullWindowListener

addOnUnFullWindowListener( listener )

Adds a listener (a function) to be called just before the viewer will stop occupying the whole window. This works for both when the viewer is used only in full-window mode (without specifying a RenderIn parameter) after user clicks the Close icon or when the viewer was rendered in an element and the user clicked the Restore icon. It's useful for adding a chuck of code to undo changes introduces by a listener added through addOnFullWindowListener.

removeOnUnFullWindowListener( listener )

Removes a listener (a function) that was added through addOnUnFullWindowListener

3.2 Experience::Cloudy

Cloudy is a weighted list (tag cloud) generator. It's very simple to use and gives the developer control over the behavior and the looks of the list.

3.2.1 How to Use Cloudy

Here's a complete working example (assuming you have unpacked the Experience library distribution to the root of your server) ..

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <!--  Import the prototype library -->
    <script type="text/javascript" src="prototype-1.5.0.js"></script>

    <!--  Import the base Experience namespace -->
    <script type="text/javascript" src="experience.js"></script>

    <!--  Import Experience::Cloudy -->
    <script type="text/javascript" src="experience.cloudy.js"></script>

    <!-- Initialize Cloudy -->
    <script type="text/javascript">

    /* Prepare an array of your items (usually this will be generated) 
    from a database */
    var items = [
        { label: "Ruby", weight: 9, href: "http://ruby-lang.org" },
        { label: "PHP",  weight: 2, href: "http://php.net" },
        { label: "Java", weight: 6, href: "http://java.sun.com" },
        { label: "C#",   weight: 4, href: "http://mono-project.com"  }
    ];


    /* Create a new WeightedList object and render it */
    window.onload = function() {
        var list = new experience.cloudy.WeightedList({
                        Items: items, 
                        RenderIn: 'renderHere'
                   });
        list.render();
    }

    </script>

    <!-- Done! -->
</head>
<body>
    <div id="renderHere" ></div>
</body>
</html>

3.2.2 How to Style Cloudy

You can style items (tags), which are essentially <a> elements, by defining a CSS class named cloudyItem. For example:

.cloudyItem {   
    padding: 0 4px;
}

.cloudyItem:hover {
    background-color: #56677C;
    color: #F6F9FB;
}

To style the tip that (optionally) show when hovering over a tag, define a CSS class named cloudyTip. For example: 

.cloudyTip {
    background-color: #93B200;
    color: white;
    padding: 2px;
}

These class names can be changed on a per-WeightedList basis. See the API Reference section.

3.2.3 API Reference

The Experience::Cloudy component is contained within the experience.cloudy namespace.

experience.cloudy.WeightedList

This class is the workhorse of the Cloudy component. It renders an array of items into a weighted list whose look and feel can be controlled through many parameters. It supports the following methods:

[constructor]( params )

Creates a WeightedList object. It accepts one or more parameters in a hash-like object that are detailed later in this section. The two required and most important parameters are RenderIn and Items. The RenderIn parameter specifies the element (or it's id) in which to render the weighted list (ie a div). The Items parameter specifies an array of items to be rendered by this WeightedList object. It's a numerically indexed array of hash-like objects that represent the items in the list. Each item can have these properties:

  • label (required): the label (title or name) of the item.
  • weight (required): a number representing the weight of the item
  • href: the href attribute value of the item link
  • html: a piece of HTML (or just plain text) to display when the user hovers over the item.
  • handlers: a hash-like object mapping between event names (i.e. mouseover) and their handling functions
Example: 
 
/* Prepare an array of items */
var itemsArr = [
    {
        label: "Ruby", 
        weight: 8,
        href: "http://ruby-lang.org",  
        html:   "A wonderful language", 
        handlers: {click: handleClick} 
    },
    {
        label: "Java", 
        weight: 6,  
        href: "http://sun.java.com", 
        html:   "A clean language", 
        handlers: {click: handleClick} 
    },
    {
        label: "Perl",    
        weight: 3, 
        href: "http://en.wikipedia.org/wiki/Perl", 
        html: "For Perlistani people!", 
        handlers: {click: handleClick} 
    } 
];

/* Create a WeightedList object */
var list = new experience.cloudy.WeightedList({ 
    RenderIn: 'someElementId',
    Items : itemsArr
});
Supported Parameters:
Name Required Default Value Description
RenderIn Yes   Specifies the element (or it's ID) in which to render the weighted list.
Items Yes   Specifies a numerically indexed array of items to render.
MinFontSize No 8 Specifies the font size for the item with the least weight.
MaxFontSize No 40 Specifies the font size for the item with the most weight.
Unit No 'px' Specifies the CSS unit of the font sizes.
ItemCSSClass No 'cloudyItem' Specifies the CSS class name(s) to be applied to items.
TipCSSClass No 'cloudyTip' Specifies the CSS class name(s) to be applied to tips that (optionally) show when hovering over an item.

render()

Renders the WeightedList into a set of <a> tags.

4. That's All

That's all for now. More excite to come later!