CSSE 290 Web Programming

Lecture 17: More Prototype, Scriptaculous (quick look)

Reading: 10.1; 10.2

Attribution:Except where otherwise noted, the contents of this document are Copyright 2012 Marty Stepp, Jessica Miller, and Victoria Kirst. All rights reserved. Any redistribution, reproduction, transmission, or storage of part or all of the contents in any form is prohibited without the author's expressed written permission.

Otherwise noted: Claude Anderson was given permission to modify the slides for CSSE 290 at Rose-Hulman by author Jessica Miller. The authors' original slides, based on Web Programming Step by Step, can be seen at http://webstepbook.com.
Some of the examples in some days' slides are from David Fisher at Rose-Hulman, who was kind enough to allow me to use them. My intention is to mark these examples with [DSF].

Recap: DOM versus innerHTML hacking

Why not just code the previous example this way?

function slideClick() {
	$("thisslide").innerHTML += "<p>A paragraph!</p>";
}

function slideClick() {
	$("main").innerHTML += "<p style='color: red; " +
			"margin-left: 50px;' " +
			"onclick='myOnClick();'>" +
			"A paragraph!</p>";
}

Benefits of DOM over innerHTML

function slideClick() {
	var p = document.createElement("p");
	p.className = "special";
	p.onclick = myOnClick;
	p.innerHTML = "A paragraph!";
	$("thisslide").appendChild(p);
}

.special {
	color: red;
	margin-left: 50px;
}

• cleaner to attach event handlers to DOM object
• cleaner to set styles by attaching classes to DOM objects

Problems with reading/changing styles

<button id="clickme">Click Me</button>

window.onload = function() {
	$("clickme").onclick = biggerFont;
};
function biggerFont() {
	var size = parseInt($("clickme").style.fontSize);
	size += 4;
	$("clickMe").style.fontSize = size + "pt";
}

• style property lets you set any CSS style for an element
• problem: you cannot (usually) read existing styles with it

Accessing styles in Prototype

function biggerFont() {
	// make the text bigger
	var size = parseInt($("clickme").getStyle("font-size"));
	$("clickme").style.fontSize = (size + 4) + "pt";
}

• getStyle method (added to each DOM object by Prototype) allows accessing existing styles

Common bug: incorrect usage of existing styles

$("main").style.top = $("main").getStyle("top") + 100 + "px";            // bad!

• the above example computes e.g. "200px" + 100 + "px" ,
  which would evaluate to "200px100px"
• a corrected version:

  $("main").style.top = parseInt($("main").getStyle("top")) + 100 + "px";  // correct
  

JavaScript: Getting/setting CSS classes

function highlightField() {
	// turn text yellow and make it bigger
	if (!$("text").className) {
		$("text").className = "highlight";
	} else if ($("text").className.indexOf("invalid") < 0) {
		$("text").className += " highlight";
	}
}

• JS DOM's className property corresponds to HTML class attribute
• somewhat clunky when dealing with multiple space-separated classes as one big string

Getting/setting CSS classes in Prototype

function highlightField() {
	// turn text yellow and make it bigger
	if (!$("text").hasClassName("invalid")) {
		$("text").addClassName("highlight");
	}
}

• addClassName, removeClassName, toggleClassName, hasClassName manipulate CSS classes
• similar to existing className DOM property, but don't have to manually split by spaces
• JavaScript's classList property, allows similar manipulations, but is clunkier.

Scriptaculous overview

Scriptaculous : a JavaScript library, built on top of Prototype, that adds:

• visual effects (animation, fade in/out, highlighting)
• drag and drop
• Ajax features:
  • Auto-completing text fields (drop-down list of matching choices)
  • In-place editors (clickable text that you can edit and send to server)
• some DOM enhancements
• other stuff (unit testing, etc.)

Downloading and using Scriptaculous

<script src="http://ajax.googleapis.com/ajax/libs/prototype/1.7.0.0/prototype.js"
 type="text/javascript"></script>

<script src="http://ajax.googleapis.com/ajax/libs/scriptaculous/1.9.0/scriptaculous.js"
 type="text/javascript"></script>

• or download it, extract its .js files to a folder documentation available on the Scriptaculous wiki
• Scriptaculous Effects Cheat Sheet

Learning about Scriptaculous

Online API documentation is incomplete (argh), but the following are useful resources:

• Scriptaculous wiki documentation
  • Visuals
  • Core FX
  • Combo FX
  • Sortables
  • Drag 'n' Drop 1 | 2 | 3 | 4
  • Auto-Completion 1 | 2
  • DOM

Visual effects

appear blindDown grow slideDown (appearing)

blindUp dropOut fade fold puff
shrink slideUp squish switchOff (disappearing)

highlight pulsate shake morph
Effect.Move Effect.Scale Effect.toggle (blind) (Getting attention)

Click effects above

Adding effects to an element

element.effectName();   // for most effects

// some effects must be run the following way:
new Effect.name(element or id);

$("sidebar").shake();

var buttons = $$("results > button");
for (var i = 0; i < buttons.length; i++) {
	buttons[i].fade();
}

• the effect will begin to animate on screen (asynchronously) the moment you call it
• six core effects are used to implement all effects on the previous slides:
  • Effect.Highlight, Effect.Morph, Effect.Move,
    Effect.Opacity, Effect.Parallel, Effect.Scale

Effect options

element.effectName(
	{
		option: value,
		option: value,
		...
	}
);

$("my_element").pulsate({
	duration: 2.0, 
	pulses: 2
});

• many effects can be customized by passing additional options (note the {})
• options (wiki): delay, direction, duration, fps, from, queue, sync, to, transition

Effect events

$("my_element").fade({
	duration: 3.0, 
	afterFinish: displayMessage
});

function displayMessage(effect) {
	alert(effect.element + " is done fading now!");
}

• all effects have the following events that you can handle:
  • beforeStart, beforeUpdate, afterUpdate, afterFinish
• the afterFinish event fires once the effect is done animating
  • useful do something to the element (style, remove, etc.) when effect is done
• each of these events receives the Effect object as its parameter
  • its properties: element, options, currentFrame, startOn, finishOn
  • some effects (e.g. Shrink) are technically "parallel effects", so to access the modified element, you write effect.effects[0].element rather than just effect.element

Learn more about Scriptaculous

• The rest of the Scriptacuous slides give a quick overview of the kinds of things that are available
• In case you are interested (optional for CSSE 290)
• Read the slides to see what is available
• More details in Section 10.2 of the textbook
• And in the Scriptaculous documentation

Drag and drop

Scriptaculous provides several objects for supporting drag-and-drop functionality:

• Draggable : an element that can be dragged
• Draggables : manages all Draggable objects on the page
• Droppables : elements on which a Draggable can be dropped
• Sortable : a list of items that can be reordered

• Shopping Cart demo

Draggable

new Draggable(element or id,
	{ options }
);

• specifies an element as being able to be dragged
• options: handle, revert, snap, zindex, constraint, ghosting, starteffect, reverteffect, endeffect
• event options: onStart, onDrag, onEnd
  • each handler function accepts two parameters: the Draggable object, and the mouse event

Draggable example

<div id="draggabledemo1">Draggable demo. Default options.</div>
<div id="draggabledemo2">Draggable demo.
	{snap: [40,40], revert: true}</div>

document.observe("dom:loaded", function() {
	new Draggable("draggabledemo1");
	new Draggable("draggabledemo2", {revert: true, snap: [40, 40]});
});

Draggable demo.
Default options.

Draggable demo.
{snap:[60, 60], revert:true}

Draggables

• a global helper for accessing/managing all Draggable objects on a page
• (not needed for this course)
• properties: drags, observers
• methods: register, unregister, activate, deactivate, updateDrag, endDrag, keyPress, addObserver, removeObserver, notify

Droppables

Droppables.add(element or id,
	{ options }
);

• specifies an element as being able to be dragged
• options: accept, containment, hoverclass, overlap, greedy
• event options: onHover, onDrop
  • each callback accepts three parameters: the Draggable, the Droppable, and the event
  • Shopping Cart demo

Drag/drop shopping demo

<img id="product1" src="images/shirt.png" alt="shirt" />
<img id="product2" src="images/cup.png" alt="cup" />
<div id="droptarget"></div>

document.observe("dom:loaded", function() {
	new Draggable("product1");
	new Draggable("product2");
	Droppables.add("droptarget", {onDrop: productDrop});
});

function productDrop(drag, drop, event) {
	alert("You dropped " + drag.id);
}

Sortable

Sortable.create(element or id of list,
	{ options }
);

• specifies a list (ul, ol) as being able to be dragged into any order
• implemented internally using Draggables and Droppables
• options: tag, only, overlap, constraint, containment, format, handle, hoverclass, ghosting, dropOnEmpty, scroll, scrollSensitivity, scrollSpeed, tree, treeTag
• to make a list un-sortable again, call Sortable.destroy on it

Sortable demo

<ol id="simpsons">
	<li id="simpsons_0">Homer</li>
	<li id="simpsons_1">Marge</li>
	<li id="simpsons_2">Bart</li>
	<li id="simpsons_3">Lisa</li>
	<li id="simpsons_4">Maggie</li>
</ol>

document.observe("dom:loaded", function() {
	Sortable.create("simpsons");
});

Sortable list events

document.observe("dom:loaded", function() {
	Sortable.create("simpsons", {
			onUpdate: listUpdate
	});
});

• onChange handler function receives the dragging element as its parameter
• onUpdate handler function receives the list as its parameter

Sortable list events example

document.observe("dom:loaded", function() {
	Sortable.create("simpsons", {
			onUpdate: listUpdate
	});
});

function listUpdate(list) {
	// can do anything I want here; effects, an Ajax request, etc.
	list.shake();
}

Subtleties of Sortable events

• for onUpdate to work, each li must have an id of the form listID_index

  <ol id="simpsons">
  	<li id="simpsons_0">Homer</li>
  	<li id="simpsons_1">Marge</li>
  	<li id="simpsons_2">Bart</li>
  	<li id="simpsons_3">Lisa</li>
  	<li id="simpsons_4">Maggie</li>
  </ol>
  

• if the elements of the list change after you make it sortable (if you add or remove an item using the DOM, etc.), the new items can't be sorted
  • must call Sortable.create on the list again to fix it

Auto-completing text fields

Scriptaculous offers ways to make a text box that auto-completes based on prefix strings:

• Autocompleter.Local : auto-completes from an array of choices
• Ajax.Autocompleter : fetches and displays list of choices using Ajax

Using Autocompleter.Local

new Autocompleter.Local(
	element or id of text box, 
	element or id of div to show completions,
	array of choices, 
	{ options }
);

• you must create an (initially empty) div to store the auto-completion matches
  • it will be inserted as a ul that you can style with CSS
  • the user can select items by pressing Up/Down arrows; selected item is given a class of selected
• pass the choices as an array of strings
• pass any extra options as a fourth parameter between { }
  • options: choices, partialSearch, fullSearch, partialChars, ignoreCase

Autocompleter.Local demo

<input id="bands70s" size="40" type="text" />
<div id="bandlistarea"></div>

document.observe("dom:loaded", function() {
	new Autocompleter.Local(
		"bands70s",
		"bandlistarea",
		["ABBA", "AC/DC", "Aerosmith", "America", "Bay City Rollers", ...], 
		{}
	);
});

Autocompleter styling

<input id="bands70s" size="40" type="text" />
<div id="bandlistarea"></div>

#bandlistarea {
	border: 2px solid gray;
}
/* 'selected' class is given to the autocomplete item currently chosen */
#bandlistarea .selected {
	background-color: pink;
}

Using Ajax.Autocompleter

new Ajax.Autocompleter(
	element or id of text box, 
	element or id of div to show completions,
	url, 
	{ options }
);

• when you have too many choices to hold them all in an array, you can instead fetch subsets of choices from the server using Ajax
• instead of passing choices as an array, pass a URL from which to fetch them
  • the choices are sent back from the server as an HTML ul with li elements in it
• options: paramName, tokens, frequency, minChars, indicator, updateElement, afterUpdateElement, callback, parameters

Ajax.InPlaceEditor

new Ajax.InPlaceEditor(element or id,
	url,
	{ options }
);

• options: okButton, okText, cancelLink, cancelText, savingText, clickToEditText, formId, externalControl, rows, onComplete, onFailure, cols, size, highlightcolor, highlightendcolor, formClassName, hoverClassName, loadTextURL, loadingText, callback, submitOnBlur, ajaxOptions
• event options: onEnterHover, onLeaveHover, onEnterEditMode, onLeaveEditMode

Ajax.InPlaceCollectionEditor

new Ajax.InPlaceCollectionEditor(element or id,
	url,
	{
		collection: array of choices,
		options
	}
);

• a variation of Ajax.InPlaceEditor that gives a collection of choices
• requires collection option whose value is an array of strings to choose from
• all other options are the same as Ajax.InPlaceEditor

Playing sounds (API)

Sound.play("music/java_rap.mp3");
Sound.play("music/wazzaaaaaap.wav");

• to silence a sound playing in progress, use Sound.play('', {replace: true});
• cannot play sounds from a local computer (must be uploaded to a web site)

Other neat features

• slider control:

  new Control.Slider("id of knob", "id of track", {options});
  

• Builder - convenience class to replace document.createElement :

  var img = Builder.node("img", {
    src: "images/lolcat.jpg",
    width: 100, height: 100,
    alt: "I can haz Scriptaculous?"
  });
  $("main").appendChild(img);
  

• Tabbed UIs

JavaScript events

• the click event (onclick) is just one of many events that can be handled
• problem: events are tricky and have incompatibilities across browsers
  • reasons: fuzzy W3C event specs; IE disobeying web standards; etc.
• solution: Prototype includes many event-related features and fixes

Attaching event handlers the Prototype way

element.onevent = function;
element.observe("event", function);

// call the playNewGame function when the Play button is clicked
$("play").observe("click", playNewGame);

• to use Prototype's event features, you must attach the handler using the DOM element object's observe method (added by Prototype)
• pass the event name as a string, and the function name to call
• handlers must be attached this way for Prototype's event features to work

• observe substitutes for addEventListener (not supported by IE)

The event object

function name(event) {
	// an event handler function ...
}

• Event handlers can accept an optional parameter to represent the event that is occurring. Event objects have the following properties / methods:

• *   replaces non-standard srcElement and which properties
• ** replaces non-standard return false;, stopPropagation, etc.

Mouse events

Mouse event objects

The event passed to a mouse handler has these properties:

• *   replaces non-standard properties pageX and pageY
• ** replaces non-standard properties button and which

Mouse event example

<pre id="target">Move the mouse over me!</pre>

window.onload = function() {
	$("target").observe("mousemove", showCoords);
};

function showCoords(event) {
	$("target").innerHTML = 
		  "pointer: (" + event.pointerX() + ", " + event.pointerY() + ")\n"
		+ "screen : (" + event.screenX + ", " + event.screenY + ")\n"
		+ "client : (" + event.clientX + ", " + event.clientY + ")";
}

Move the mouse over me!

Recap: The keyword this

this.fieldName                  // access field
this.fieldName = value;          // modify field

this.methodName(parameters);    // call method

• all JavaScript code actually runs inside of an object
• by default, code runs in the global window object (so this === window)
  • all global variables and functions you declare become part of window
• the this keyword refers to the current object

Recap: Event handler binding

window.onload = function() {
	$("textbox").observe("mouseout", booyah);   // bound to text box here
	$("submit").observe("click", booyah);       // bound to submit button here
};

function booyah() {           // booyah knows what object it was called on
	this.value = "booyah";
}

• event handlers attached unobtrusively are bound to the element
• inside the handler, that element becomes this (rather than the window)

Fixing redundant code with this

<fieldset>
	<label><input type="radio" name="ducks" value="Huey"  /> Huey</label>
	<label><input type="radio" name="ducks" value="Dewey" /> Dewey</label>
	<label><input type="radio" name="ducks" value="Louie" /> Louie</label>
</fieldset>

function processDucks() {
	if ($("huey").checked) {
		alert("Huey is checked!");
	} else if ($("dewey").checked) {
		alert("Dewey is checked!");
	} else {
		alert("Louie is checked!");
	}
	alert(this.value + " is checked!");
}

• if the same function is assigned to multiple elements, each gets its own bound copy

Page/window events

• The above can be handled on the window object. An alternative to window.onload:

window.onload = function() { ... };
document.observe("dom:loaded", function() {
	// attach event handlers, etc.
});

Keyboard/text events

• focus: the attention of the user's keyboard (given to one element at a time)

Key event objects

• issue: if the event you attach your listener to doesn't have the focus, you won't hear the event
  • possible solution: attach key listener to entire page body, outer element, etc.

Form events

• Prototype adds the following methods to form controls' DOM objects:

Prototype form shortcuts

$F("formID")["name"]

• gets parameter with given name from form with given id

$F("controlID")

• $F function returns the value of a form control with the given id

  if ($F("username").length < 4) {
  	$("username").clear();
  	$("login").disable();
  }
  

Stopping an event

<form id="exampleform" action="http://foo.com/foo.php">...</form>

window.onload = function() {
	$("exampleform").observe("submit", checkData);
};

function checkData(event) {
	if ($F("city") == "" || $F("state").length != 2) {
		alert("Error, invalid city/state.");  // show error message 
		event.stop();
		return false;
	}
}

• to abort a form submit or other event, call Prototype's stop method on the event

Event-handling example

Use events to do some cool animations!

We use timer events, with methods setInterval and clearInterval

setInterval(code,millisec) returns ID of timer event

clearInterval(id_of_setinterval)