Contents:
JQuery comes with WHIFF
The JQueryUIBase middleware
Targetting a named widget
Configuring Options
Configuring Methods
Configuring Events
The widget types
Date Picker
Autocompletion
Accordion
Progressbar
Slider
Draggable and droppable
Sortable
Styling options
Conclusion
JQuery comes with WHIFF
The WHIFF package includes standard support for the
jquery Javascript Library
and the
jqueryUI Javascript add on library.
Both libraries come automatically with the WHIFF distribution
because they are generally useful for building dynamic and
interactive web pages.
If you want to use a jquery feature on a web page
you must include a reference to the basic jquery library.
The whiff_middleware/jquery/jQueryLib middleware will include
the library automatically.
For example the following simple WHIFF configuration template uses the offset method
from the jquery library to find the position of a div
element on a page.
{{env whiff.content_type: "text/html"/}}
<html>
<head>
<title> jquery position test </title>
</head>
<body>
{{include "whiff_middleware/jquery/jQueryLib"/}}
<br><br><br>
<center>
<div id="testDiv" onclick="showOffset()" style="background-color:yellow; width:150px">
Where am I? (click here)
</div>
</center>
<script>
function showOffset() {
var testDiv = $('#testDiv');
var offset = testDiv.offset();
alert('x: ' + offset.left + ', y: ' + offset.top);
}
</script>
</body>
</html>
Here the line
{{include "whiff_middleware/jquery/jQueryLib"/}}
will pull in the basic jquery library if it hasn't already been added to the page.
If you try to add the library several times using
jQueryLib the
extra add attempts will be ignored.
Similarly if you want to use the jqueryUI add on library you may
use the directive
{{include "whiff_middleware/jquery/jQueryUILib"/}}
The jqueryUI components often require standard CSS style
definitions. WHIFF includes a default stylesheet which provides the
definitions which you can add in a WHIFF configuration as follows:
<link type="text/css"
href="whiff_middleware/jquery/css/ui-lightness/jquery-ui-1.8.2.custom.css"
rel="stylesheet" />
and this stylesheet should normally be added to the
head of the HTML document.
You may also want to "roll your own" stylesheet to get the look and feel you prefer
using the
jqueryUI themeroller.
Please click the text with the yellow background in the embedded frame below to see the
page generated by the template above in action.
The above example uses
jquery directly in a simple manner.
Other uses of
jquery can be complex and tricky.
The JQueryUIBase middleware
The
jqueryUI
library provides useful and attractive dynamic
widgets which allow users to interact with web
pages. Many of these widgets are quite sophisticated
and configuring one of the widgets for a given
task can be a complex job: it may involve getting
and setting a number of options, calling methods
of the widget, and assigning event callbacks for
the widget and also wiring all these things together
with javascript code.
The JQueryUIBase middleware makes it
a bit easier to configure a jqueryUI
widget by automatically generating a number of commonly
useful javascript fragments often used with widgets.
The interfaces to jqueryUI widgets
are characterized by a target, a widget name, options, events,
and methods:
-
The target for a widget is the identifier for the
HTML page component which will contain the widget.
-
The widget name for a widget is a name which identifies
the general behaviour of the widget -- for example the widget name
datepicker allows the user to pick a date from a "calendar"
pop-up.
-
Options are data values which control the
look and behaviour of the widget -- they may have an initial
value and may also be get or set during
the lifetime of the widget.
-
Events represent interactions with the widget.
An event may be assigned a callback function value to perform an action
when the event occurs.
-
Methods are operations which may be performed
on the widget. Javascript programs may alter the behaviour
of a widget by calling methods of the widget.
The
JQueryUIBase middleware includes features
for configuring these widget interfaces as described below.
Targetting a named widget
Every widget must have an associated HTML element and a widget
type. The following configuration associates a widget of type
datepicker with the HTML input element with the
identity
mydateinput
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} mydateinput {{/using}}
{{using widget}} datepicker {{/using}}
{{/include}}
When is your next birthday? <input id="mydateinput" name="thedate">
Please see the
datepicker section below to see
this configuration in a complete example.
Configuring Options
A widget option is a data value associated with a widget.
You can use the
JQueryUIBase middleware to
set an initial value for a widget option and to assign
javascript names for getters and setters for widget options.
For example the following
slider configuration
configures a number of options for the slider widget
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} myslider {{/using}}
{{using widget}} slider {{/using}}
{{using option_max}} 44 {{/using}}
{{using option_min}} -100 {{/using}}
{{using set_value}} setslider {{/using}}
{{using get_value}} getslider {{/using}}
{{using event_change}} displayslider {{/using}}
{{using event_slide}} displayslider {{/using}}
{{/include}}
Please see the "slider" section below for a complete working example
which includes this configuration
In the above configuration the using directive
{{using option_max}} 44 {{/using}}
sets
initial value the
max value for the slider to the javascript integer
44.
In general an initial option value may be set to any
javascript value.
The using directives
{{using set_value}} setslider {{/using}}
{{using get_value}} getslider {{/using}}
assign the
javascript global names setslider and
getslider
to
get and
set the
value option of the slider widget respectively.
The getter and setter names may be used in javascript programs on the page to
change the value option during the lifetime of the slider
widget. The function call
sets the
value option and the function call
var slider_value = getslider();
gets the slider value.
Configuring Methods
A widget method is an action that a program can use to change a widget.
You can use the
JQueryUIBase middleware to
assign a
global javascript name to the method associated with a widget.
For example the following configuration for a sortable widget
assigns the name sortOrder to the toArray widget method.
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} mysortable {{/using}}
{{using widget}} sortable {{/using}}
{{using method_toArray}} sortOrder {{/using}}
{{using event_change}} showSort {{/using}}
{{using event_update}} showSort {{/using}}
{{/include}}
Javascript programs on the page may call the
sortOrder method
to obtain the array from the sortable as follows:
var sortArray = sortOrder();
Please see the
sortable section below for a complete example
which uses this configuration.
Configuring Events
A widget calls an event when something interesting happened to the widget.
You can use the
JQueryUIBase middleware to assign a
javascript function value to an event for a widget.
For example the sortable configuration shown above
also assigns the change and update to have
the same function value showSort. The function showSort
is defined using javascript elsewhere on the page.
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} mysortable {{/using}}
{{using widget}} sortable {{/using}}
{{using method_toArray}} sortOrder {{/using}}
{{using event_change}} showSort {{/using}}
{{using event_update}} showSort {{/using}}
{{/include}}
<script>
function showSort() {
var sortArray = sortOrder();
var display = document.getElementById("display");
var report = sortArray.join(" .. ");
display.innerHTML = report;
}
</script>
The widget types
The remainder of this document provides some simple working examples of
configurations which use
jqueryUI widgets.
- A date picker allows a user to select a date using an interactive calendar.
- An autocompletion input element allows a user to select programming language with suggestions that drop down automatically.
- An accordion allows the user to expand and collapse sections of text on a page.
- A progress bar indicates how much more work needs to be done to complete a procedure.
- A slider allows a user to specify a numeric value interactively.
- Draggables may be moved around the page and dropped into droppables.
Below are WHIFF configurations which generate complete HTML pages containing each of these
widgets, followed by embedded frames which display the generated page.
This document will not duplicate descriptions for the options, methods, events or styling
available for configuring the
widget types. Please see the
jQueryUI demos and documentation site
for detailed information on the widget configurations.
The source code for these examples is distributed with the WHIFF distribution
in the directory INSTALL/doc/docroot/jquery.
To browse the demos (including some demos not explained here)
please go to the
INSTALL/doc/docroot/jquery/index.html index page.
Date Picker
Date pickers provide an intuitive way to specify a day.
The following
datepicker configuration allows the user to specify
the birthdate by clicking on an interactive calendar.
{{env whiff.content_type: "text/html"/}}
<html>
<head>
<title>jQuery datepicker WHIFF test</title>
<link type="text/css"
href="whiff_middleware/jquery/css/smoothness/jquery-ui-1.7.2.custom.css"
rel="stylesheet" />
</head>
<body>
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} mydateinput {{/using}}
{{using widget}} datepicker {{/using}}
{{/include}}
When is your next birthday? <br>
<input id="mydateinput" name="thedate">
</body>
</html>
Note that the page includes the standard
jquery stylesheet distributed with
WHIFF in addition to using
jQueryUIBase to connect a
datepicker
widget to the
mydateinput input element.
Please click in the input box in the embedded frame below to see this widget in action
Autocompletion
Autocompletions drop suggestions for an input element below the
element as the user types. The following page includes an input element
which automatically suggests programming languages related to what the
user types in the element.
{{env whiff.content_type: "text/html"/}}
<html>
<head>
<title>jQuery autocomplete WHIFF test</title>
<link type="text/css" href="whiff_middleware/jquery/css/ui-lightness/jquery-ui-1.8.2.custom.css" rel="stylesheet" />
</head>
<body>
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} myInput {{/using}}
{{using widget}} autocomplete {{/using}}
{{using option_source}}
["c++", "java", "php", "coldfusion", "javascript", "asp",
"ruby", "python", "c", "scala", "groovy", "haskell", "perl"]
{{/using}}
{{/include}}
Pick a programming language <br>
<input id="myInput" name="thedate">
</body>
</html>
Please click in the input box in the embedded frame below
and type
j (for example) to see the autocompletion widget in action.
Autocompletions are particularly useful and powerful when they are combined
with AJAX server callbacks to generate the completion suggestions.
the
Ajax autocompletions tutorial
describes how to configure an autocompletion
field to use an AJAX callback.
Accordion
An accordion allows the user to focus on a small segment of content from
a possible large number of options. The following configuration includes
an accordion (it has been abbreviated to eliminate unnecessary verbage).
{{env whiff.content_type: "text/html"/}}
<html>
<head>
<title>jQuery accordion WHIFF test</title>
<link type="text/css" href="whiff_middleware/jquery/css/smoothness/jquery-ui-1.7.2.custom.css" rel="stylesheet" />
</head>
<body style="width:500px; font-size:8px">
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} myaccordion {{/using}}
{{using widget}} accordion {{/using}}
{{/include}}
<h1>WHIFF/jquery Accordion example</h1>
<div id="myaccordion">
<h3><a href="#">Section 1</a></h3>
<div>
<p>
Mauris mauris ante, blandit et, ultrices a, suscipit eget, quam. Integer...
</p>
</div>
<h3><a href="#">Section 2</a></h3>
<div>
<p>
Sed non urna. Donec et ante. Phasellus eu ligula. Vestibulum sit amet...
</div>
<h3><a href="#">Section 3</a></h3>
...
</div>
</body>
</html>
In the embedded frame below please click on the header lines to see the accordion
segments expand and contract.
Progressbar
You can use a progress bar to indicate how much more work needs to be done
before an operation is complete.
The following example includes a progress bar and provides buttons
for displaying and changing the progress value.
{{env whiff.content_type: "text/html"/}}
<html>
<head>
<title>jQuery progress bar WHIFF test</title>
<link type="text/css" href="whiff_middleware/jquery/css/smoothness/jquery-ui-1.7.2.custom.css" rel="stylesheet" />
</head>
<body style="width:500px">
Progress bar: <br>
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} myprogressbar {{/using}}
{{using widget}} progressbar {{/using}}
{{using option_value}}79{{/using}}
{{using get_value}}get_progress{{/using}}
{{using set_value}}set_progress{{/using}}
{{/include}}
<center>
<div style="width:200px" id="myprogressbar"></div>
</center>
progress is <div id="progress_display">not known</div>
<br>
<button onclick="showProgress()">show progress number</button>
<br>
new progress: <input id="progress_input">
<br>
<button onclick="changeProgress()">change progress</button>
<script>
function showProgress() {
var progress_display = document.getElementById("progress_display");
progress_display.innerHTML = get_progress() + " percent.";
}
function changeProgress() {
var progress_input = document.getElementById("progress_input");
var progress = parseFloat(progress_input.value);
set_progress(progress);
}
</script>
</body>
</html>
In this configuration the
value option for the progress bar
is initially set to
79 and the javascript names
get_progress
and
set_progress name functions to get and set the progress bar
value option. The other javascript functions on the page use the getter and setter
to interact with the progress bar.
Please try to change the progress bar using the input element and the buttons
in the embedded frame below.
Slider
Sliders provide a visually compelling way to specify a numeric value.
The following example configuration includes a slider and also provides
interactive elements for displaying the associated numeric value and
for setting the numeric value.
{{env whiff.content_type: "text/html"/}}
<html>
<head>
<title>jQuery progress bar WHIFF test</title>
<link type="text/css" href="whiff_middleware/jquery/css/smoothness/jquery-ui-1.7.2.custom.css" rel="stylesheet" />
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} myslider {{/using}}
{{using widget}} slider {{/using}}
{{using option_max}} 44 {{/using}}
{{using option_min}} -100 {{/using}}
{{using set_value}} setslider {{/using}}
{{using get_value}} getslider {{/using}}
{{using event_change}} displayslider {{/using}}
{{using event_slide}} displayslider {{/using}}
{{/include}}
</head>
<body style="width:500px">
<h3>WHIFF/slider demo</h3>
<blockquote>
<div id="myslider" style="width:200px"> </div>
</blockquote>
<hr>
value is <div id="display"> zero </div>
<hr>
set value to <input id="inputElement" value="0"> <button onclick="forceSlider()">SET</button>
<script>
var count = 0;
function displayslider() {
count += 1;
var value = getslider();
//al("displayslider got value "+value);
var display = document.getElementById("display");
display.innerHTML = ""+value+", ("+count+")";
}
function forceSlider() {
var inputElement = document.getElementById("inputElement");
var value = inputElement.value;
var fvalue = parseFloat(value);
setslider(fvalue);
displayslider();
}
</script>
</body>
</html>
The slider configuration assigns the names
setslider and
getslider
to get and set the
value for the slider. Both the
change
and the
slide events are given the function value
displayslider
which is defined in javascript elsewhere on the page. The
displayslider and
forceSlider javascript functions use the getter and setter to interact with
the slider widget.
Please drag the slider handle in the embedded frame
below to see the slider value change. You may also explicitly
set the slider value using the input element.
Draggable and droppable
Draggable elements may be moved around the screen with the mouse.
Droppable elements may receive draggables.
The following example includes two draggables
and a droppable.
{{env whiff.content_type: "text/html"/}}
<html>
<head>
<title>jQuery drag/drop WHIFF test</title>
<link type="text/css" href="whiff_middleware/jquery/css/smoothness/jquery-ui-1.7.2.custom.css" rel="stylesheet" />
</head>
<body style="font-family: Arial;">
<h3>WHIFF/jquery droppable demo</h3>
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} mydroppable {{/using}}
{{using widget}} droppable {{/using}}
{{using event_drop}}
function(event, ui) {
var dr = ui.draggable
stuff = [ ""+dr.attr("id")+" dropped in "+$(this).attr("id") ];
var pre = document.getElementById("pre");
pre.innerHTML = stuff.join("\n\n")
}
{{/using}}
{{/include}}
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} mydraggable {{/using}}
{{using widget}} draggable {{/using}}
{{/include}}
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} myOtherdraggable {{/using}}
{{using widget}} draggable {{/using}}
{{/include}}
<div id="mydroppable" style="background-color:pink; width:100px; height:100px; float:left">
Drop here
</div>
<div style="width:10px; height:10px; float:left"></div>
<div id="mydraggable" style="background-color:yellow; width:80px; height:50px; float:left">
Drag me
</div>
<div style="width:10px; height:10px; float:left"></div>
<div id="myOtherdraggable" style="background-color:cyan; width:50px; height:80px; float:left">
Drag me too
</div>
<div style="clear:left"> </div>
<br>
<pre id="pre">
Drop event information will be reported here.
</pre>
</body>
</html>
This configuration assigns a javascript function value to the
drop
droppable event which illustrates how to determine the identities for the droppable
and draggable when a draggable is dropped in a droppable.
Please drag the 'drag me' draggable boxes in the embedded iframe below and drop them
into the 'drop here' droppable box.
Sortable
Sortable containers allow the user to move the elements inside the sortable
around to a new order.
The following configuration includes a sortable which allows the user
to move the colored boxes into a different order.
{{env whiff.content_type: "text/html"/}}
<html>
<head>
<title>jQuery sortable WHIFF test</title>
<link type="text/css" href="whiff_middleware/jquery/css/smoothness/jquery-ui-1.7.2.custom.css" rel="stylesheet" />
</head>
<body>
{{include "whiff_middleware/jquery/jQueryUIBase"}}
{{using targetId}} mysortable {{/using}}
{{using widget}} sortable {{/using}}
{{using method_toArray}} sortOrder {{/using}}
{{using event_change}} showSort {{/using}}
{{using event_update}} showSort {{/using}}
{{/include}}
<h3>WHIFF/jquery sortable demo</h3>
Please drag items below.
<blockquote>
<div id="mysortable" style="width:200px">
<div style="background-color:pink" id="a"> apple </div>
<div style="background-color:limegreen" id="b"> banana </div>
<div style="background-color:magenta" id="c"> cookie</div>
<div style="background-color:yellow" id="d"> donut</div>
<div style="background-color:cyan" id="e"> egg</div>
<div style="background-color:cornsilk" id="f"> fish</div>
</div>
</blockquote>
<script>
function showSort() {
var sortArray = sortOrder();
var display = document.getElementById("display");
var report = sortArray.join(" .. ");
display.innerHTML = report;
}
</script>
<div id="display"> order changes will be reported here. </div>
</body>
</html>
This configuration assigns the javascript name
sortOrder to the sortable
toArray method
and assigns both the
change and the
update events the function value
showSort which is defined as a javascript function separately.
Please drag the colored boxes to a different order
in the embedded frame below.
Styling options
As mentioned earlier the
jQueryUI widgets use standard CSS styling names
and must use a stylesheet to define these names.
If you want to use a different stylesheet than the one that comes automatically with WHIFF
you can change the style sheet reference
<link type="text/css"
href="whiff_middleware/jquery/css/ui-lightness/jquery-ui-1.8.2.custom.css"
rel="stylesheet" />
to point to the alternate style you prefer.
Conclusion
The
jQuery and
jQueryUI javascript libraries
provide powerful methods for presenting information and
on web pages and for adding user interactions to web pages.
This tutorial showed how WHIFF includes automatic support
for these libraries and illustrated a number of working examples that
demonstrate how to use the
jQueryUI widgets in a WHIFF
configuration.
