prototype.js の開発者向けメモ

バージョン 1.5.0 対応

last update: March 4^th 2007

それは何？
関連資料
ユーティリティ関数
$() 関数を使う
$$() 関数を使う
$F() 関数を使う
$A() 関数を使う
$H() 関数を使う
$R() 関数を使う
Try.these() 関数を使う
文字列を操る
文字列の置換
文字列テンプレート
Ajax オブジェクト
Ajax.Request クラスを使う
Ajax.Updater クラスを使う
この "?" とか豆腐みたいなのとかは何なの？
数え上げ、列挙……まったくもう！
Ruby スタイルのループ
配列をパワーアップ！
お薦めの書籍
prototype.js リファレンス
JavaScript 基本クラスの拡張
Object クラスに対する拡張
Number クラスに対する拡張
Function クラスに対する拡張
String クラスに対する拡張
Array クラスに対する拡張
document DOM オブジェクトに対する拡張
Event オブジェクトに対する拡張
prototype.js によって新しく定義されたオブジェクトとクラス
PeriodicalExecuter オブジェクト
Prototype オブジェクト
Enumerable オブジェクト
Hash オブジェクト
ObjectRange クラス
Class オブジェクト
Ajax オブジェクト
Ajax.Responders オブジェクト
Ajax.Base クラス
Ajax.Request クラス
options 引数オブジェクト
Ajax.Updater クラス
Ajax.PeriodicalUpdater クラス
Element オブジェクト
Element.ClassNames クラス
Abstract オブジェクト
Abstract.Insertion クラス
Insertion オブジェクト
Insertion.Before クラス
Insertion.Top クラス
Insertion.Bottom クラス
Insertion.After クラス
Field オブジェクト
Form オブジェクト
Form.Element オブジェクト
Form.Element.Serializers オブジェクト
Abstract.TimedObserver クラス
Form.Element.Observer クラス
Form.Observer クラス
Abstract.EventObserver クラス
Form.Element.EventObserver クラス
Form.EventObserver クラス
Position オブジェクト (仮ドキュメント)

それは何？

prototype.js は Sam Stephenson によって書かれた JavaScript ライブラリです。この熟考の上記述された標準に準拠したコードは、Web 2.0 において特徴となるリッチでインタラクティブなウェブページを制作する際の重荷を、あなたの肩から取り去ってくれるでしょう。

もしこのライブラリを使ったことがあるなら、充実したドキュメントがこのライブラリの売りではないことに気がついたはずです。私は他の開発者と同様に、ソースコードを読み、試行錯誤しながら prototype.js を理解しました。自分が学んでいる間にメモを取り、それを他の人たちと共有することは価値があるのでは、と考えたのです。

加えて、このライブラリによって提供されているオブジェクト、クラス、関数、拡張機能についての非公式リファレンスも提供しています。

ここで提供する例とリファレンスを読んでいると、プログラミング言語 Ruby に詳しい開発者は Ruby のビルトインクラスと、このライブラリが実装している拡張が非常に似ていることに気がつくかもしれません。

ユーティリティ関数

ライブラリには多くのオブジェクトやユーティリティ関数が定義されています。これらの関数により、何度も同じことをタイプしたり、わかりきったイディオムを繰り返す煩わしさから開放されます。

$() 関数を使う

$() 関数は頻発する DOM の document.getElementById() 関数へのショートカットです。 DOM 関数と同様に、この関数は引数として渡された ID を持つ要素 (element) を返します。

ただし DOM 関数とは異なり、この関数はさらに進んでいます。返される要素オブジェクトはいくつかの追加メソッドにより拡張されています。これらの追加メソッドは要素を隠したり表示したり、その大きさを取得したり、別の要素に向けてスクロールしたり、というような多くのタスクを簡単にできるようにしてくれます。返される要素に追加されたメソッドの一覧は、Element オブジェクトのリファレンスで見ることができます。

<html>
<head>
<title> Test Page </title>
<script src="prototype.js"></script>

<script>
	function test(){
		var d = $('myDiv');
		alert(d.innerHTML);
		d.hide();
		d.show();
		d.addClassName('active');
	}
</script>
</head>

<body>
	<div id="myDiv">
		<p>This is a paragraph</p>
	</div>
	<div id="myOtherDiv">
		<p>This is another paragraph</p>
	</div>

	<input type="button" value="Test $()" onclick="test();"/><br/> 

</body>
</html>

この関数のもうひとつの利点は、ID 文字列だけでなく要素オブジェクトそのものを渡すこともできる、ということです。どちらの型の引数も受け取ることができるような他の関数を書くときには、とても便利に使えます。

$$() 関数を使う

$$() 関数は、コンテンツの枠組みから CSS をきれいに分離しようとする場合にとても役立ちます。この関数は、一つ以上の CSS フィルタ式 (CSS ルールを定義するのに使われているセレクタと似ています) を引数として受け取り、そのフィルタにマッチする要素の配列を返します。

使い方は簡単です。以下を見てください。

<script>
function test$$(){
	/*
	  in case CSS is not your forte, the expression below says
	  'find all the INPUT elements that are inside 
	  elements with class=field that are inside a DIV
	  with id equal to loginForm.'
	*/
	var f = $$('div#loginForm .field input');
	var s = '';
	for(var i=0; i<f.length; i++){
		s += f[i].value + '/';
	}
	alert(s); // shows: "joedoe1/secret/"
	
	//now passing more than one expression
	f = $$('div#loginForm .field input', 'div#loginForm .fieldName');
	s = '';
	for(var i=0; i<f.length; i++){
		s += ( f[i].value ? f[i].value : f[i].innerHTML ) + '/';
	}
	alert(s); //shows: "joedoe1/secret/User name:/Password:/"
}


</script>

<div id='loginForm'>
	<div class='field'>
		<span class='fieldName'>User name:</span>
		<input type='text' id='txtName' value='joedoe1'/>
	</div>
	<div class='field'>
		<span class='fieldName'>Password:</span>
		<input type='password' id='txtPass' value='secret' />
	</div>
	<input type='submit' value='login' />
</div> 
<input type=button value='test $$()' onclick='test$$();' />

パフォーマンスについてちょっと記しておきます。 prototype.js の $$() 関数の現在の実装では、特に効率的な実装を重視しているわけではありません。この関数を頻繁に使って、深く複雑な HTML 文書を処理しようとしているのなら、単純に $$() 関数自体を置き換えることができる、他のフリーの実装を検討した方がいいかもしれません。

$F() 関数を使う

$F() もまた便利なショートカットです。この関数はテキストボックスやドロップダウンリストのような、入力フォームフィールドの値を返します。この関数は要素の ID、要素オブジェクトそのもののどちらも引数として渡すことができます。

<script>
	function test3()
	{
		alert(  $F('userName')  );
	}
</script>

<input type="text" id="userName" value="Joe Doe"><br /> 
<input type="button" value="Test3" onclick="test3();"><br />

$A() 関数を使う

$A() 関数は引数を一つ受け取り、 Array オブジェクトに変換します。

この関数は Array クラスに対する拡張と連携し、列挙可能なリスト(enumerable list) を Array オブジェクトに簡単に変換、コピーします。オススメの利用法は DOM の NodeLists から通常の配列への効率的な変換です。下の例を見てください。

<script>

	function showOptions(){
		var someNodeList = $('lstEmployees').getElementsByTagName('option');
		var nodes = $A(someNodeList);

		nodes.each(function(node){
				alert(node.nodeName + ': ' + node.innerHTML);
			});
	}
</script>

<select id="lstEmployees" size="10" >
	<option value="5">Buchanan, Steven</option>
	<option value="8">Callahan, Laura</option>
	<option value="1">Davolio, Nancy</option>
</select>

<input type="button" value="Show the options" onclick="showOptions();" >

$H() 関数を使う

$H() 関数は、渡されたオブジェクトを、列挙可能な(enumerable) Hash オブジェクト (連想配列のようなもの) に変換します。

<script>
	function testHash()
	{
		//let's create the object
		var a = {
			first: 10,
			second: 20,
			third: 30
			};

		//now transform it into a hash
		var h = $H(a);
		alert(h.toQueryString()); //displays: first=10&second=20&third=30
	}

</script>

$R() 関数を使う

$R() 関数は new ObjectRange(lowerBound, upperBound, excludeBounds) と書く所を短く記述するためのものです。

このクラスの完全な解説は、 ObjectRange クラスのドキュメントを見てください。ここでは each メソッドを通じてイテレータの使い方を示すシンプルな例を見てみましょう。このメソッドについては、 Enumerable オブジェクトのドキュメントにより詳しく解説されています。

<script>
	function demoDollar_R(){
		var range = $R(10, 20, false);
		range.each(function(value, index){
			alert(value);
		});
	}

</script>

<input type="button" value="Sample Count" onclick="demoDollar_R();" />

Try.these() 関数を使う

Try.these() 関数は、いくつかの関数を成功するまで順番に試す、ということを簡単にしてくれます。この関数は任意の数の関数を引数として受け取り、呼び出しに成功するまでひとつずつ順番に呼び出します。返り値は呼び出しが成功した関数の返り値となります。

下の例では、xmlNode.text 関数はいくつかのブラウザで動作し、xmlNode.textContent は他のいくつかのブラウザで動作します。 Try.these() 関数を使うことにより、動作する方の関数を返すことが出来ます。

<script>
function getXmlNodeValue(xmlNode){
	return Try.these(
		function() {return xmlNode.text;},
		function() {return xmlNode.textContent;}
		);
}
</script>

文字列を操る

String はパワフルなオブジェクトです。 prototype.js はその能力を活用し、さらに次の次元へと誘います。

文字列の置換

文字列の置換に関しては、JavaScript は既に正規表現が使える String.Replace メソッドなどを持っています。しかし、これらは prototype.js で導入された代替関数ほど柔軟性がありません。

新しい String.gsub メソッドを見てみましょう。このメソッドを使うと、固定文字列や正規表現パターンで、文字列の検索・置換を行うだけでなく、置換処理に際してさらに制御することができるようになります。例えば、見付かった文字列が(単に置換されるだけでなく)どう変換されるか、をメソッドに指示するのに文字列テンプレートを使うことができます。

次の例では、't' を含む単語を探して、't' 以降を 'tizzle' で置き換えます。もう少し詳しく書くと、正規表現において括弧に括られた \w+ を使ってキャプチャグループを宣言しています。このグループによってキャプチャされた値は、置換用のテンプレート文字列で #{1} を使うことで取得できます。

例においては、't' よりも前にある文字列をキャプチャし、その後ろに 'tizzle' を追加します。正規表現内にさらにキャプチャグループがある場合も、それらの値を #{2}, #{3} などで取得できます。

<script>
function talkLikeYouKnowSomething(){
	var s = 'prototype string extensions can help you';
	var snoopdogfy = /\b(\w+)t\w+\b/;
	var snooptalk = s.gsub(snoopdogfy, '#{1}tizzle' );
	alert(snooptalk); // shows: "prototizzle stizzle extizzle can help you"				
}
</script>

まだまだあります。この例ではパターンマッチと置換に限定していたので、置換能力を生かしきれていません。望んだ置換結果を得るために、独自のロジックを使うことができるようにするには、どうすればいいのでしょうか？ gsub の二つめの引数に関数を渡すことで、それが実現できます。この関数は引数として配列を受け取り、配列のインデックス 0 にはマッチしたテキストが、それ以降(インデックス 1 から N)にキャプチャグループの値が入ります。

<script>
function scamCustomers(){
	var prices = 'book1 $12.5, magazine $5.50, pencil $1.20';
	var priceFinder = /\$([0-9\.]+)/;
	var r = prices.gsub(priceFinder, jackUp);
	alert(r);//shows: "book1 $13.75, magazine $6.05, pencil $1.32"
}
	
function jackUp(matches){
	//increases the prices by 10%
	var price = parseFloat(matches[1]);
   	return '$' + Math.round(110 * price)/100;
}
</script>

文字列テンプレート

アプリケーション中での JavaScript コードの量が増えるにつれ、同じタイプのオブジェクトの集合を書式化して表示する機会も増えるのではないでしょうか。

オブジェクトのリストをループで回し、オブジェクトのプロパティに基づいて定型の書式化文字列にあてはめる、というコードは珍しいものではないでしょう。 prototype.js はまさにこのような事例を手助けしてくれる Template クラスを提供しています。

以下の例では、ショッピングカート内の商品を書式化し、複数にわたる HTML 行として列挙するものです。

<script>
function printCart(){
	//creating a sample cart
	var cart = new Object();
	cart.items = [ ];
	//putting some sample items in the cart
	cart.items.push({product: 'Book 123', price: 24.50, quantity: 1});
	cart.items.push({product: 'Set of Pens', price: 5.44, quantity: 3});
	cart.items.push({product: 'Gift Card', price: 10.00, quantity: 4});
	
	//here we create our template for formatting each item
	var itemFormat = new Template(
			'You are ordering #{quantity} units ' + 
			'of #{product} at $#{price} each'
			);
	var formatted = '';
	
	for(var i=0; i<cart.items.length; i++){
		var cartItem = cart.items[i];
		formatted += itemFormat.evaluate(cartItem) + '<br/>\n';
	}
	
	alert(formatted);
	/* SHOWS:
	You are ordering 1 units of Book 123 at $24.5 each<br/>
	You are ordering 3 units of Set of Pens at $5.44 each<br/>
	You are ordering 4 units of Gift Card at $10 each<br/>
	*/
}
</script>

新しいメソッドの一覧は String クラスに対する拡張のリファレンスを見てください。

toc

Ajax オブジェクト

ここまでで説明した関数はもちろん素晴らしいのですが、実際の所最先端モノというわけではありませんよね？これくらいは自分自身で書けるかもしれませんし、自分のスクリプトとして既に同じような物を持っているかもしれません。しかし、これらの関数は氷山の一角に過ぎないのです。

あなたが prototype.js に興味を持ったのは、その AJAX 能力に注目したからでしょう。それでは AJAX 的コードが必要な時に、いかにこのライブラリが助けてくれるかを解説していきましょう。

Ajax オブジェクトは、AJAX 機能を記述する際に必要となるトリッキーなコードを覆い隠し、シンプルにするためにライブラリにより事前に定義されたオブジェクトです。このオブジェクトには AJAX コードのカプセル化を提供するいくつかのクラスを含んでいます。そのうちのいくつかを見てみましょう。

Ajax.Request クラスを使う

もしまだ他の支援ライブラリを使っていないのなら、XMLHttpRequest オブジェクトを作成し、非同期の進捗を追跡し、返り値を取り出して処理する、という多くのコード全てを自分で記述していることでしょう。そしてサポートしなければいけないブラウザーが 1 種類だけの時にはラッキー、と感じていることでしょう。

AJAX 機能の実装を手助けするために、ライブラリでは Ajax.Request クラスが定義されています。

ここでは、URL http://yourserver/app/get_sales?empID=1234&year=1998 にリクエストを投げると、下のような XML レスポンスを返すようなサーバとやりとりするアプリケーションを開発しているとしましょう。

<?xml version="1.0" encoding="utf-8" ?> 
<ajax-response>
	<response type="object" id="productDetails">
		<monthly-sales>
			<employee-sales>
				<employee-id>1234</employee-id> 
				<year-month>1998-01</year-month> 
				<sales>$8,115.36</sales> 
			</employee-sales>
			<employee-sales>
				<employee-id>1234</employee-id> 
				<year-month>1998-02</year-month> 
				<sales>$11,147.51</sales> 
			</employee-sales>
		</monthly-sales>
	</response>
</ajax-response>

この XML を取得するために Ajax.Request オブジェクトを使ってサーバとやりとりする方法はいたって簡単です。下の例を見てください。

<script>
	function searchSales()
	{
		var empID = $F('lstEmployees');
		var y = $F('lstYears');
		var url = 'http://yourserver/app/get_sales';
		var pars = 'empID=' + empID + '&year=' + y;
		
		var myAjax = new Ajax.Request(
			url, 
			{
				method: 'get', 
				parameters: pars, 
				onComplete: showResponse
			});
		
	}

	function showResponse(originalRequest)
	{
		//put returned XML in the textarea
		$('result').value = originalRequest.responseText;
	}
</script>

<select id="lstEmployees" size="10" onchange="searchSales()">
	<option value="5">Buchanan, Steven</option>
	<option value="8">Callahan, Laura</option>
	<option value="1">Davolio, Nancy</option>
</select>
<select id="lstYears" size="3" onchange="searchSales()">
	<option selected="selected" value="1996">1996</option>
	<option value="1997">1997</option>
	<option value="1998">1998</option>
</select>
<br /><textarea id="result" cols=60 rows=10 ></textarea>

Ajax.Request オブジェクトのコンストラクタの二番目のパラメータを見てください。 {method: 'get', parameters: pars, onComplete: showResponse} というパラメータは(JSON書式の)無名オブジェクトです。ここで示しているのは、文字列 'get' という値を持つプロパティ method、HTTP リクエストのクエリ文字列を値として持つプロパティ parameters、関数 showResponse を値として持つプロパティ(メソッドでもある) onComplete、という三つのプロパティを持つオブジェクトを引数として渡している、ということです。

このオブジェクトを作成する際に定義できるプロパティは他にもあります。例えば true か false を指定することでサーバへの AJAX 呼び出しを非同期にするかどうかを指示することができる asynchronous プロパティ (デフォルト値は true) などです。

このパラメータでは AJAX 呼び出しのためのオプションを指定します。このサンプルでは、最初の引数の url を変数 pars に含まれるクエリ文字列を付加して HTTP GET で呼び出し、 Ajax.Request オブジェクトがレスポンスを取得し終わった時に showResponse 関数を呼び出します。

知っているかもしれませんが、XMLHttpRequest は HTTP 呼び出しの最中に進捗を報告します。この進捗報告には四つの段階があります (Loading, Loaded, Interactive, Complete)。これらの任意の段階で、Ajax.Request に独自の関数を呼び出すようにさせることが出来ます (Completeがよく使われます)。オブジェクトに関数を指定するためには、例の中の onComplete のように、Request のコンストラクタへのオプションに onXXXXX というような名前のプロパティ(メソッド)を指定します。指定した関数は、オブジェクトから引数を二つ渡して呼び出されます。一つは XMLHttpRequest (以下 XHR) オブジェクトそのもの、もう一つは評価(eval)された X-JSON HTTP レスポンスヘッダ (もしあれば) です。 XHR を使って返されたデータを取得したり、呼び出しの HTTP リザルトコードが含まれる status プロパティをチェックしたりすることができます。スクリプトや JSON 書式のデータを返したい場合、X-JSON ヘッダがとても便利です。

結果を処理する際に興味深いオプションがあとふたつあります。 onSuccess オプションは AJAX 呼び出しがエラー無しに実行できた時に呼び出される関数として指定することができ、同様に onFailure オプションは呼出し時になんらかのサーバーエラーが発生したときに呼び出される関数として指定することができます。これらのふたつの関数は、他の onXXXXX オプション関数と同様に、AJAX 呼び出しを担い X-JSON ヘッダを評価する XHR (XMLHttpRequest) を引数として呼び出されます。

この例では XML レスポンスに対して何ら興味深い処理はしていません。単に XML をテキストエリアに書き出しているだけです。レスポンスの典型的な利用法としては、XML の内部から必要な情報を見つけ出していくつかのページ内要素を更新したり、ページ内で HTML を生成するためにある種の XSLT 変換を行うこと、などがあるでしょう。

別の形のイベントコールバックの使い方も存在します。どの AJAX 呼び出しを使っている場合でも、特定のイベントにおいて常に実行されてほしいコードがある場合、新しい Ajax.Responders オブジェクトを使うことができます。

AJAX 呼び出しが実行中の時に、回転するアイコンのような何らかの視覚効果を見せたいとしましょう。この際二つのグローバルイベントハンドラを使うことができます。一つは最初の呼び出しが始まったときにアイコンを表示するもの。もう一つは最後の呼び出しが終わったときにアイコンを非表示にするものです。以下の例を見てください。

<script>
	var myGlobalHandlers = {
		onCreate: function(){
			Element.show('systemWorking');
		},

		onComplete: function() {
			if(Ajax.activeRequestCount == 0){
				Element.hide('systemWorking');
			}
		}
	};

	Ajax.Responders.register(myGlobalHandlers);
</script>

<div id='systemWorking'><img src='spinner.gif'>Loading...</div>

より詳細な説明は、Ajax.Request リファレンスと options リファレンスを見てください。

Ajax.Updater クラスを使う

もし既にフォーマットされた HTML を返すことができるサーバー URL がある場合、このライブラリの Ajax.Updater クラスを使えばさらに楽をすることができます。このクラスでは、AJAX 呼び出しから返ってくる HTML で、その要素を埋めれば良いかを伝えるだけで済みます。ごちゃごちゃ書くより例を見てもらった方がいいでしょう。

<script>
	function getHTML()
	{
		var url = 'http://yourserver/app/getSomeHTML';
		var pars = 'someParameter=ABC';
		
		var myAjax = new Ajax.Updater(
			'placeholder', 
			url, 
			{
				method: 'get', 
				parameters: pars
			});
		
	}
</script>

<input type="button" value="GetHtml" onclick="getHTML()" />
<div id="placeholder"></div>

onComplete 関数が無く、要素 ID がコンストラクタに渡されていることを除けば、コードがひとつ前の例ととても似ているのがわかると思います。クライアント側でサーバーエラーをどのように処理するかを示すために、少しコードを変更してみましょう。

エラー状態を捕捉するための関数を指定するのに、コンストラクタ呼び出しにさらにオプションを追加します。具体的には onFailure オプションを使います。また、placeholder が成功したときのみ更新されるようにするために、最初のパラメータを単なる要素 ID から success (全て OK なら使われる) と failure (何か問題があれば使われる) のふたつのプロパティを持つオブジェクトに変更します。今回の例では failure プロパティは使わず、 onFailure オプションで reportError 関数を使います。

<script>
	function getHTML()
	{
		var url = 'http://yourserver/app/getSomeHTML';
		var pars = 'someParameter=ABC';
		
		var myAjax = new Ajax.Updater(
					{success: 'placeholder'}, 
					url, 
					{
						method: 'get', 
						parameters: pars, 
						onFailure: reportError
					});
		
	}

	function reportError(request)
	{
		alert('Sorry. There was an error.');
	}
</script>

<input type="button" value="GetHtml" onclick="getHTML()" />
<div id="placeholder"></div>

サーバー側の処理が HTML マークアップに加えて JavaScript コードを返す場合、Ajax.Updater オブジェクトは JavaScript コードを評価 (eval) することができます。オブジェクトにレスポンスを JavaScript として扱わせるには、オブジェクトのコンストラクタの最後の引数で、プロパティ中に evalScripts: true; を追加するだけです。ただし、注意するべき点がひとつあります。これらのスクリプトブロックはページのスクリプトとして追加されるわけではありません。オプション名 evalScripts が示すように、スクリプトは 評価(eval) されます。どんな違いがあるかって？リクエストされた URL が以下のように返してきたとしましょう:

<script language="javascript" type="text/javascript">
	function sayHi(){
		alert('Hi');
	}
</script>

<input type="button" value="Click Me" onclick="sayHi()" />

もし以前自分で試したことがあるなら、これがうまく動かないことを知っているかもしれません。これは、スクリプトブロックは評価(eval)されるものの、上記のようなスクリプトは sayHi という名前の関数を作成しないからです。何もしないのです。関数を作成するには、スクリプトが関数を作成するように変更しなければなりません。以下のようになります。

<script language="javascript" type="text/javascript">
	sayHi = function(){
		alert('Hi');
	};
</script>

<input type="button" value="Click Me" onclick="sayHi()" />

上記の例では変数を宣言するのに var キーワードを使わなかったことに注意してください。そうすると、(少なくとも IE では) スクリプトブロックにローカルな関数オブジェクトを作ることになってしまいます。 var キーワードが無い場合、私たちの意図通りに window スコープの関数オブジェクトが作成されます。

より詳細な説明は、Ajax.Updater リファレンスと options リファレンスを参照してください。

この "?" とか豆腐みたいなのとかは何なの？

(訳註: この節は日本語の環境に慣れ親しんでいる方々には違和感のある説明かもしれません。とりあえずは原文を尊重して翻訳します)

さて、Ajax.Updater オブジェクトを使って、簡単なテストスクリプトを書いてページを更新している間はうまくいっています。実際のデータを使ってスクリプトを走らせるまでは、何も問題はありません。突然、非英語文字が表れるべき所にクエスチョンマークや表示できない記号が表示されるのです。

もちろん、まず最初に疑うのは prototype.js でしょう。でもちょっとライブラリを責めるのは待ってください。あなたはどれだけ文字エンコーディング、コードページ、そしてブラウザがどのようにそれらを扱うかを理解していますか？もし理解しているのなら、あなたは自分で問題を解決できるでしょう。もし Web 開発者の 8 割方の方 (いいかげんな著者の推測ですが) がそうであるように、文字エンコーディングを軽く見ているのなら、続きを読んでみてください。

わたしは自分がこの件に関する権威のようなふりをするつもりはありませんし、最善の解ついての完全な説明はできません。代わりに、わたしが使っている方法をそのまま説明し、あなた自身の状況において適用しうる方法を見つけるためのヒントを提供します。

単純なことに、答えはこの文にあります。「ブラウザーが期待しているものを提供しなさい」 Unicode/UTF-8 文字を含むページを更新しようとしているのなら、ブラウザにそのことを知らせる必要があります。

ここではサーバ上にある静的 HTML ファイルのテキストを更新する単純なケースから始めましょう。あなたがファイルを作成する際、使っているテキストエディタにも依りますが、おそらくファイルは ANSI (わかりやすく言えば Unicode ではない) フォーマットで保存されていることでしょう。多くのテキストエディタ、特にソースコードエディタではこれがデフォルトとなっています。というのは、ファイルサイズがより小さくなりうることと、ソースコードを編集するのに Unicode 文字が含まれることは比較的珍しいからです。

サーバ上に static-content.html という名前のファイルがあるとします。これは ANSI フォーマットで保存されています。

<div>
	Hi there, José. Yo no hablo español.
</div>

メインページにおいて、中身が以下のようなコード片を使って更新されます。

<script>
	function updateWithFile(){
		var url = 'static-content.html';
		var pars = '';
		var myAjax = new Ajax.Updater(
				'placeholder', url, 
				{method: 'get', parameters: pars});
	}
</script>
<div id="placeholder">(this will be replaced)</div>
<input id="btn" value="Test With Static File" 
                 onclick="updateWithFile()" type="button"/>

ボタンをクリックすると、静的ファイルが読み込まれますが、非英語の文字はクエスチョンマークか他の記号で置き換えられてしまいます。表示されるテキストは、ブラウザによって変わりますが "Hi there, Jos?. Yo no hablo espa?ol." や "Hi there, Jos?Yo no hablo espa?" のようになるでしょう。

このケースでは、解決方法は単純で、静的ファイルを適切なフォーマットで保存し直すだけです。では UTF-8 で保存して、再度スクリプトを走らせてみましょう (まともなテキストエディタなら Save As ダイアログにそうするオプションがあるはずです)。これで正しいテキストが表示されるはずです (もしダメなら、ブラウザが古いファイルをキャッシュしているかもしれません。ファイル名を変えて試してみてください)。

供給している HTML が静的ではない場合や、なんらかのアプリケーションフレームワーク (ASP.NET, PHP, もしくは Perl でさえ!) から動的に生成されている場合には、その HTML を生成しているコードが適切なエンコーディングとコードページでテキストを生成していること、そして HTTP レスポンスヘッダにそのことを知らせるヘッダが含まれていることを確認してください。各プラットフォームではこれを実施する方法は異なりますが、大体は同じようなものです。

例として、ASP.NET では web.config ファイルでグローバルにこの設定を行うことができます。デフォルトの設定はこの問題を避けるために適した場所でしょう。 web.config ファイルには以下のセクションがあるはずです。

<globalization requestEncoding="utf-8" responseEncoding="utf-8" />

旧来の ASP 3.0 では、以下コードで問題を解決できます。

Response.CodePage = 65001
Response.CharSet = "utf-8"

PHP では、レスポンスヘッダを追加する文法は以下のようになります。

<?php header('Content-Type: text/html; charset=utf-8'); ?>

いずれにせよ、あなたの究極のゴールは以下のような HTTP ヘッダがレスポンスに含まれるようにすることです。

Content-Type: text/html; charset=utf-8

この例では UTF-8 を使いましたが、もし異なった設定が必要なら、簡単に変更できます。

数え上げ、列挙……まったくもう！

我々は皆、ループについてよく知っています。配列を作成し、同種の要素を詰め込んで、ループを制御する命令 (for, foreach, while, repeat などなど) を使い、数字のインデックスを使って順番に要素にアクセスし、要素に対して何かを行います。

考えてみると、コードの中に配列を導入するという時には、遅かれ早かれループ中でそれを使うことになるわけです。そんな時、配列オブジェクトがそんな繰り返しを手助けしてくれる機能を持っていたらいいと思いませんか？そうです、多くのプログラム言語が配列や同様の構造 (コレクションやリストなど) にそのような機能を提供しています。

もちろん我らが prototype.js も、繰り返すデータを扱う際に使える技をたくさん詰め込んだ Enumerable オブジェクトを提供しています。 prototype.js ライブラリはより一歩踏み込んで、 Array クラスが Enumerable のすべてのメソッドを備えるように拡張しています。

Ruby スタイルのループ

標準的な JavaScript では、配列の要素を順番に表示しようとする場合、以下のように書くことでうまくいきます。

<script>
	function showList(){
		var simpsons = ['Homer', 'Marge', 'Lisa', 'Bart', 'Maggie'];
		for(i=0;i<simpsons.length;i++){
			alert(simpsons[i]);
		}
	}

</script>

<input type="button" value="Show List" onclick="showList();" />

我らが prototype.js では、このループをこんな風に書き換えることができます。


	function showList(){
		var simpsons = ['Homer', 'Marge', 'Lisa', 'Bart', 'Meg'];
		simpsons.each( function(familyMember){
			alert(familyMember);
		});
	}

「で？　だから何？　いつものをおかしな書き方しただけじゃない」と思うかもしれません。確かに、上の例ではたいして驚くようなことはしていません。まあこんな簡単な例では大きく変えられるような所はありませんし。とにかく、もうちょっと続きを読んでください。

先に進む前に、each メソッドに渡された関数を見てください。これを iterator 関数と呼ぶことにします。

配列をパワーアップ！

先に述べたように、同じ種類の、同じプロパティとメソッドを持つ要素を配列に入れるのは一般的なことです。この強力な配列を使って、iterator 関数がどのようなメリットをもたらしてくれるのかを見てみましょう。

条件にマッチする要素を探します。

<script>
	function findEmployeeById(emp_id){
		var listBox = $('lstEmployees')
		var options = listBox.getElementsByTagName('option');
		options = $A(options);
		var opt = options.find( function(employee){
			return (employee.value == emp_id);
		});
		alert(opt.innerHTML); //displays the employee name
	}
</script>

<select id="lstEmployees" size="10" >
	<option value="5">Buchanan, Steven</option>
	<option value="8">Callahan, Laura</option>
	<option value="1">Davolio, Nancy</option>
</select>

<input type="button" value="Find Laura" onclick="findEmployeeById(8);" />

別の切り口から見てみましょう。配列中の要素をフィルタし、その中から必要なメンバーだけを取り出すには以下のようにします。

<script>
	function showLocalLinks(paragraph){
		paragraph = $(paragraph);
		var links = $A(paragraph.getElementsByTagName('a'));
		//find links that do not start with 'http'
		var localLinks = links.findAll( function(link){
			//we'll just assume for now that external links
			// do not have a '#' in their url
			return link.href.indexOf('#') >= 0;
		});
		//now the link texts
		var texts = localLinks.pluck('innerHTML');
		//get them in a single string
		var result = texts.inspect();
		alert(result);
	}

</script>
<p id="someText">
	This <a href="http://othersite.com/page.html">text</a> has 
	a <a href="#localAnchor">lot</a> of 
	<a href="#otherAnchor">links</a>. Some are 
	<a href="http://wherever.com/page.html">external</a>
	and some are <a href="#someAnchor">local</a>
</p>
<input type="button" value="Find Local Links" onclick="showLocalLinks('someText')" />

この文法を好きになるには、もう少し修行が必要かもしれません。提供されているすべての関数については、Enumerable と Array のリファレンスを参照してください。

お薦めの書籍

Some books are just too good not to pass the word forward. The following books have helped me a lot learning the new skills required to adequately create AJAX applications and also consolidate the skills I though I already mastered. I think a good book is money well-spent, that keep paying for itself for a long time.

prototype.js リファレンス

JavaScript 基本クラスの拡張

prototype.js ライブラリが機能を提供する方法のひとつは、既存の JavaScript クラスを拡張することです。

Object クラスに対する拡張

メソッド	種類	引数	説明
extend(destination, source)	static	destination: 任意のオブジェクト, source: 任意のオブジェクト	source から destination に対して全てのプロパティ、メソッドをコピーすることで、継承を実現する方法を提供する。
inspect(targetObj)	static	targetObj: 任意のオブジェクト	targetObj の人間向けに表現された文字列を返す。指定されたオブジェクトが inspect インスタンスメソッドを定義していない場合は、デフォルトで toString の返り値を使う。
keys(targetObj)	static	targetObj: 任意のオブジェクト	渡されたオブジェクトの、すべてのプロパティ名とメソッド名を Array として返す。
values(targetObj)	static	targetObj: 任意のオブジェクト	渡されたオブジェクトの、すべてのプロパティ値とメソッド値 (Function オブジェクト) を Array として返す。
clone(targetObj)	static	targetObj: 任意のオブジェクト	targetObj の浅いコピーを返す。

Number クラスに対する拡張

メソッド	種類	引数	説明
toColorPart()	instance	(なし)	与えられた数値の16進数表現を返す。色の RGB 部分を HTML/CSS 用表現に変換する際に便利。
succ()	instance	(なし)	次の番号を返す。繰り返しを伴う状況で使われます。
times(iterator)	instance	iterator: Function(index) という型の関数オブジェクト	引数 index に現在の index 値を渡しながら iterator 関数を繰り返し呼び出す。

以下の例は 0 から 9 を alert メッセージボックスに表示します。

<script>
	function demoTimes(){
		var n = 10;
		n.times(function(index){
			alert(index);
		});
		/***************************
		 * you could have also used: 
		 *           (10).times( .... ); 
		 ***************************/
	}

</script>

<input type="button" value="Test Number.times()" onclick="demoTimes()" />

Function クラスに対する拡張

メソッド	種類	引数	説明
bind(object [, arg1 [, arg2 [...]]])	instance	object: メソッドを所持するオブジェクト	object に関連づけられた関数(内部で object を this として参照可能)のインスタンスを返す。返される関数は、元の関数と同じ引数(arg1, arg2, ... etc)となる。
bindAsEventListener(object [, arg1 [, arg2 [...]]])	instance	object: メソッドを所持するオブジェクト	object に関連づけられた関数(内部で object を this として参照可能)のインスタンスを返す。返される関数は、現在の event オブジェクトを引数として受け取り、オプションで他の追加の引数を受け取る。

これらの拡張がどう働くかを見てみましょう。

<input type="checkbox" id="myChk" value="1" /> Test?
<script>
	//declaring the class
	var CheckboxWatcher = Class.create();

	//defining the rest of the class implementation
	CheckboxWatcher.prototype = {

	   initialize: function(chkBox, message) {
			this.chkBox = $(chkBox);
			this.message = message;
			//assigning our method to the event
			
			this.chkBox.onclick = 
			   this.showMessage.bindAsEventListener(this, ' from checkbox');
			
	   },

	   showMessage: function(evt, extraInfo) {
		  alert(this.message + ' (' + evt.type + ')' + extraInfo);
	   }
	};


	var watcher = new CheckboxWatcher('myChk', 'Changed');
</script>

String クラスに対する拡張

メソッド	種類	引数	説明
camelize()	instance	(なし)	ハイフンで区切られた文字列を camelCaseString に変換します。例えばスタイルのプロパティを扱うコードを書く際に便利。
capitalize()	instance	(なし)	最初の文字を大文字にして返す。
dasherize()	instance	(なし)	下線 '_' をダッシュ '-' に置換する。
escapeHTML()	instance	(なし)	HTML マークアップが適切にエスケープされた状態の文字列を返す。
evalScripts()	instance	(なし)	文字列中に含まれる各 <script /> ブロックを評価(eval)する。
extractScripts()	instance	(なし)	文字列中のすべての <script /> ブロックを含む Array オブジェクトを返す。
gsub(pattern, replacement)	instance	pattern: 検索する文字列もしくは正規表現。 replacement: 単なる文字列、もしくはテンプレート文字列、もしくは置換を行う Function(strings[]) 形式の関数。	現在の文字列に対して、パターン文字列(もしくは正規表現)を検索し、置換文字列もしくは置換関数の返り値で置換した物を返す。置換関数には正規表現でマッチした文字列と、グループ化指定でマッチした文字列の配列が渡されます。 (訳註: 正確には、String#match() の返り値がそのまま渡されるので、正規表現に "g" オプションが付いていると若干挙動が異なる) replacement が文字列の場合、#{n} という形式の特殊テンプレート文字列を含むことができます。 #{n} の n は正規表現のグループ化のインデックスを示し、 #{0} はマッチ全体に置き換えられ、#{1} は最初のグループ、#{2} は次のグループ、というように置換されます。
parseQuery()	instance	(なし)	toQueryParams() と同じ。
scan(pattern, replacement)	instance	pattern: 検索する文字列もしくは正規表現。 replacement: 各マッチに対して適用される Function(strings[]) 形式の関数。	文字列中のマッチしたパターンに対して、繰り返し操作を適用する手段を提供する。 pattern 引数には文字列か正規表現オブジェクトを渡すことができるが、正規表現の方が便利であろう。同様に、replacement 引数も文字列か関数を渡すことができるが、使い道があるのは関数の方だけであろう。
strip()	instance	(なし)	先頭、末尾のホワイトスペースを取り除いた文字列を返す。
stripScripts()	instance	(なし)	<script /> ブロックを取り除いた文字列を返す。
stripTags()	instance	(なし)	HTML, XML タグが取り除かれた状態の文字列を返す。
sub(pattern, replacement [, count])	instance	pattern: 検索する文字列もしくは正規表現。 replacement: 文字列もしくは置換を行う Function(strings[]) 形式の関数。 count: 置換を行う回数 (省略すると 1)。	gsub とほぼ同様だが、 count 引数で指定することにより、置換回数を制限できる点が異なる。
toArray()	instance	(なし)	文字列を文字単位に分割し Array として返す。
toQueryParams()	instance	(なし)	クエリー文字列を、ハッシュのようなパラメータ名によりインデックス化された連想 Array に変換する。
truncate(length [, truncation])	instance	length: 返される文字列の最大の長さ。 truncation: 返される文字列の、指定長以降の文字が置換される文字列 (省略すると '...')。	指定された長さに制限された文字列を生成するのに用いられる。文字列が最大長を守るために切り詰められる必要がある場合、最後の数文字が truncation 引数で指定された文字列で置換される。 (例: var s='123456790'; alert(s.truncate(5)); //表示結果 '12...' )
underscore()	instance	(なし)	キャメル型文字列 (単語の先頭を大文字にして繋ぐ) を下線型文字列 (単語を下線 '_' で繋ぐ) に変換する。 (例: var s='Namespace::MyClass123'; alert(s.underscore()); //表示結果 'namespace/my_class123' ) この関数は Ruby on Rails の機能を提供することを狙っているようだ。
unescapeHTML()	instance	(なし)	escapeHTML() の逆の関数。

Array クラスに対する拡張

まず、Array は Enumerable の拡張です。なので Enumerable オブジェクトで定義されるすべての便利な関数が使えます。それ以外に、以下のメソッドが実装されています。

メソッド	種類	引数	説明
clear()	instance	(なし)	配列を空にし、自分自身を返す。
compact()	instance	(なし)	要素のうち null や undefined でないものだけを配列として返す。このメソッドは配列自身は変更しない。
first()	instance	(なし)	配列の最初の要素を返す。
flatten()	instance	(なし)	フラットな 1 次元の配列を返す。返される配列は、再帰的に各要素を辿って、それが配列ならその中身の要素を返す、という形で構築される。
indexOf(value)	instance	value: 探そうとしている値	配列中に指定された value が存在した場合に 0 起点の位置を返す。 value が存在しない場合は -1 を返す。
inspect()	instance	(なし)	配列とその要素を、見やすくした文字列として返す。
last()	instance	(なし)	配列の最後の要素を返す。
reverse([applyToSelf])	instance	applyToSelf: 配列自身も逆順にされるかどうかを指定	逆順にした配列を返す。引数が与えられないか、与えられた引数が true なら、インスタンスである配列自身が変化する。そうでなければ、配列自身は変化しない。
shift()	instance	(なし)	最初の要素を返し、それを配列から取り除く。結果として配列の長さは 1 短くなる。
without(value1 [, value2 [, .. valueN]])	instance	value1 ... valueN: 配列に存在していたら除外される値	引数リストに含まれる要素を除いた配列を返す。このメソッドは配列自身は変更しない。

これらのメソッドがどう働くかを見てみましょう。

<script>
var A = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'];
alert(A.inspect()); // "['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']"
var B = A.without('e','f');
alert(B.inspect()); // "['a', 'b', 'c', 'd', 'g', 'h']"
alert(A.inspect()); // did not change A: "['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']"
A.push(null);
A.push('x');
A.push(null);
A.push('y');
alert(A.inspect()); // "['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', null, 'x', null, 'y']"
A = A.compact();
alert(A.inspect()); // "['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'x', 'y']"
var e = A.shift();
alert(e); // "a" 
alert(A.inspect()); // "['b', 'c', 'd', 'e', 'f', 'g', 'h', 'x', 'y']"
alert(A.indexOf('c')); // 1
alert(A.first()); // 'b'
alert(A.last()); // 'y'
A.clear();
alert(A.inspect()); // "[]"
A = ['a', 'b', 'c'];
B = A.reverse(false);
alert(B.inspect()); // "['c', 'b', 'a']"
alert(A.inspect()); // A left untouched: "['a', 'b', 'c']"
A.reverse(true);
alert(A.inspect()); // "['c', 'b', 'a']"	
A = ['a', 'b',  ['c1','c2','c3'] , 'd',  ['e1','e2']  ];
B = A.flatten();
alert(B.inspect()); // "['a','b','c1','c2','c3','d','e1','e2']"		
alert(A.inspect()); // unchanged: "['a','b',['c1','c2','c3'],'d',['e1','e2']]"		
</script>

document DOM オブジェクトに対する拡張

メソッド	種類	引数	説明
getElementsByClassName(className [, parentElement])	instance	className: 要素に関連づけられた CSS クラス名, parentElement: オブジェクトもしくは ID を指定することにより、取得される要素をその内側に限定する	与えられたクラス名に関連づけられた全ての要素を返す。もし parentElement が指定されなければ、ドキュメント body 全体が検索される。

Event オブジェクトに対する拡張

プロパティ	型	説明
KEY_BACKSPACE	Number	8: 定数。バックスペースキーのコード
KEY_TAB	Number	9: 定数。タブキーのコード。
KEY_RETURN	Number	13: 定数。リターンキーのコード。
KEY_ESC	Number	27: 定数。ESC キーのコード。
KEY_LEFT	Number	37: 定数。左矢印キーのコード。
KEY_UP	Number	38: 定数。上矢印キーのコード。
KEY_RIGHT	Number	39: 定数。右矢印のコード。
KEY_DOWN	Number	40: 定数。下矢印のコード。
KEY_DELETE	Number	46: 定数。Delete キーのコード。
observers:	Array	キャッシュされた observer のリスト。オブジェクトの内部的な実装詳細の部分。

メソッド	種類	引数	説明
element(event)	static	event: Event オブジェクト	イベントを発生した要素を返す。
isLeftClick(event)	static	event: Event オブジェクト	マウスの左ボタンがクリックされた場合には true を返す。
pointerX(event)	static	event: Event オブジェクト	ページ内のマウスポインタの X 座標を返す。
pointerY(event)	static	event: Event オブジェクト	ページ内のマウスポインタの Y 座標を返す。
stop(event)	static	event: Event オブジェクト	イベントのデフォルトの挙動を中断し、他に伝播しないようにする際にこの関数を使用する。
findElement(event, tagName)	static	event: Event オブジェクト, tagName: 探したい要素のタグ名	イベントを発生したオブジェクトから始めて、指定された名前のタグを持つ最初の要素が見つかるまで DOM ツリーを上流に遡る。
observe(element, name, observer, useCapture)	static	element: オブジェクトかID, name: イベント名 ('click', 'load' など), observer: イベントを処理する関数 function(evt), useCapture: true なら, capture 段階でイベントを処理し, false なら bubbling 段階で処理する	イベントに対して、イベントハンドラを追加する。
stopObserving(element, name, observer, useCapture)	static	element: オブジェクトかID, name: イベント名 ('click' など), observer: イベントを処理する関数, useCapture: true なら capture 段階でイベントを処理し, false なら bubbling 段階で処理する	イベントからイベントハンドラを取り除く。
_observeAndCache(element, name, observer, useCapture)	static		プライベートメソッド。気にしない。
unloadCache()	static	(なし)	プライベートメソッド。気にしない。メモリからキャッシュされた observer を全てクリアする。

このオブジェクトを使って window オブジェクトの load イベントにイベントハンドラを追加する方法を見てみましょう。

<script>
	Event.observe(window, 'load', page_loaded, false);

	function page_loaded() {
	  Event.observe('parent_node', 'click', item_clicked, false);
	}
	
	function item_clicked(evt){
		var child = Event.element(evt);
		alert('The child node with id=' + child.id + ' was clicked');
		Event.stop(evt); //avoid another call related to 'parent_node' itself
	}
</script>	
...
<div id="parent_node">
	<div id="child1">First</div>
	<div id="child2">Second</div>
	<div id="child3">Third</div>
</div>

prototype.js によって新しく定義されたオブジェクトとクラス

ライブラリがあなたを助けてくれるもうひとつの方法は、オブジェクト指向で設計されたものでも一般的な関数風な使い方でも使うことができる多くのオブジェクトを提供することです。

PeriodicalExecuter オブジェクト

このオブジェクトは指定された関数を繰り返し、タイマーを使って指定された間隔で呼び出す機能を提供します。

メソッド	種類	引数	説明
[ctor](callback, interval)	constructor	callback: a function that will be passed the PeriodcalExecuter object itself as the only argument, interval: 秒数	関数を繰り返し呼び出すこのオブジェクトのインスタンスをひとつ作成する。
registerCallback()	instance	(なし)	タイマーを再設定する。
stop()	instance	(なし)	タイマーをキャンセルし、callback 関数が呼び出されないようにする。
onTimerEvent()	instance	(なし)	実際にタイマーにより呼び出される関数。内部で自分自身を引数として callback 関数を呼び出す。

プロパティ	型	説明
callback	Function(objExecuter)	呼び出される関数。 objExecuter: 呼び出しを実行する PeriodcalExecuter オブジェクト。
timer	Timer	繰り返し callback 関数を呼び出す責任を担うタイマーオブジェクトへのハンドル。
frequency	Number	呼び出される間隔(秒)。
currentlyExecuting	Boolean	callback関数が実行中かどうかを示す。

Prototype オブジェクト

Prototype オブジェクトには、使われているライブラリのバージョン番号を宣言する以外は重要な役割はありません。

プロパティ	型	説明
Version	String	ライブラリのバージョン番号。
emptyFunction	Function()	空の関数オブジェクト。
K	Function(obj)	単に指定されたパラメータを返すだけの関数オブジェクト。
ScriptFragment	String	スクリプトを識別するための正規表現。

Enumerable オブジェクト

Enumerable オブジェクトを使うことにより、リスト形式のオブジェクト内の要素に対しての繰り返しコードを、よりエレガントに書くことができます。

他の多くのオブジェクトが、その有用なインターフェースを活用するために Enumerable を継承しています。

メソッド	種類	引数	説明
each(iterator)	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	リスト内の各要素を最初の引数として、指定された iterator 関数を呼び出します。二番目の引数として要素のインデックスが渡されます。
all([iterator])	instance	iterator: Function(value, index) という型を満たす関数オブジェクト。オプション。	この関数は集合のすべての要素値を指定された関数を用いてテストする方法を提供する。 all 関数は、全ての要素が iterator 関数に対して true と解釈される値を返す場合にのみ true を返す。そうでなければ false を返す。 iterator が指定されなければ、要素自身が評価され true となるかどうかがチェックされる。要するに "全ての要素がテストをパスするかどうかをチェックする" ものである。
any([iterator])	instance	iterator: Function(value, index) という型を満たす関数オブジェクト, 省略可能。	この関数は集合のすべての要素値を指定された関数を用いてテストする方法を提供する。 any 関数は、少なくとも一つの要素が iterator 関数に対して true と解釈される値を返す場合に true を返す。そうでなければ false を返す。 iterator が指定されなければ、要素自身が評価され true となるかどうかがチェックされる。要するに "いずれかの要素がテストをパスするかどうかをチェックする" ものである。
collect(iterator)	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	集合の各要素に対して iterator 関数を呼び出し、その返り値をまとめて Array として返す。返される配列は集合の各要素に対する返り値が、順序を保って入れられる。
detect(iterator)	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	集合の各要素に対して iterator 関数を呼び出し、最初に true (正確には not-false) を返した要素を返す。 true を返す要素がなかった場合、detect は null を返す。
entries()	instance	(なし)	toArray() と同じ。
find(iterator)	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	detect() と同じ。
findAll(iterator)	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	集合の各要素に対して iterator 関数を呼び出し、iterator 関数が true と解釈される値を返した要素すべてを集めた Array を返す。この関数は reject() の逆の機能を提供する。
grep(pattern [, iterator])	instance	pattern: 要素にマッチさせる RegExp オブジェクト, iterator: Function(value, index) という型を満たす関数オブジェクト	集合の各要素の文字列値に対して正規表現 pattern をテストし、正規表現にマッチするすべての要素を含む Array を返す。 iterator 関数が指定された場合、マッチした各要素に対してその iterator を呼び出した結果が含まれる Array を返す。
include(obj)	instance	obj: 任意のオブジェクト	集合の中に指定されたオブジェクトが存在するかどうかをチェックする。オブジェクトが見つかれば true を返し、そうでなければ false を返す。
inGroupsOf(number, fillWith)	instance	number: グループ毎の項目数, fillWith: 空き項目を埋める値	一つめの引数で指定された数ごとに集合を分割し、それらの集合として返す。呼出し元の集合の数が一つめの引数で割り切れない場合、最後のグループの空き項目は、もし二つめの引数が指定されていればそれで、そうでなければ null で満たされる。簡単な例: ['a','b','c','d'].inGroupsOf(3,'?') は [ ['a','b','c'] , ['d','?','?'] ] となる。
inject(initialValue, iterator)	instance	initialValue: 初期値として用いられる任意のオブジェクト, iterator: Function(accumulator, value, index) という型を満たす関数オブジェクト	iterator 関数を用いて集合のすべての要素を結合する。 iterator は前回の呼び出しの結果である accumulator 引数を伴って呼び出される。最初の呼び出しでは accumulator 引数には initialValue が渡される。繰り返しの最後の返り値が最終的な結果として用いられる。
invoke(methodName [, arg1 [, arg2 [...]]])	instance	methodName: 各要素で呼び出されるメソッドの名前, arg1..argN: メソッドの呼び出しで渡される引数	集合の各要素に対して methodName で指定されたメソッドを呼び出す。呼び出しでは指定された引数 (arg1 to argN) が渡され、その結果を Array オブジェクトとしてまとめて返す。
map(iterator)	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	collect() と同じ。
max([iterator])	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	集合の各要素に対して、最大値 (iterator が指定された場合は各要素に対して適用された際の返り値の最大値) を返す。
member(obj)	instance	obj: 任意のオブジェクト	include() と同じ。
min([iterator])	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	集合の各要素に対して、最小値 (iterator が指定された場合は各要素に対して適用された際の返り値の最小値) を返す。
partition([iterator])	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	二つの配列を含む Array を返す。最初の配列は iterator 関数が true を返す要素すべてを含み、二番目の配列はそれ以外の要素を含む。 iterator が指定されない場合、最初の配列は true と解釈される要素を含み、二番目の配列はそうでないものを含む。
pluck(propertyName)	instance	propertyName: 各要素から読み込まれるプロパティの名前。要素の index でもよい	集合の各要素から、propertyName で指定されたプロパティの値を取得し、結果を Array オブジェクトとして返す。
reject(iterator)	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	集合の各要素に対して iterator 関数を呼び出し、iterator 関数がの返り値が false と解釈される要素すべてを Array として返す。この関数は findAll() と逆の機能を提供する。
select(iterator)	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	findAll() と同じ。
sortBy(iterator)	instance	iterator: Function(value, index) という型を満たす関数オブジェクト	iterator 関数の呼び出し結果に応じてソートされたすべての要素を Array として返す。
toArray()	instance	(なし)	集合のすべての要素を Array として返す。
zip(collection1[, collection2 [, ... collectionN [,transform]]])	instance	collection1 .. collectionN: enumerations that will be merged, transform: Function(value, index) という型を満たす関数オブジェクト	現在の集合に与えられた集合をマージする。このマージ操作は現在の集合と同じ要素数の新しい配列を返し、返される配列の各要素はマージされる集合の各々から同じ index のものを集めたものの配列 (以下 sub-array と表記) となる。 transform 関数が指定された場合、各 sub-array は返される前にその関数を使って変換される。例: [1,2,3].zip([4,5,6], [7,8,9]).inspect() は "[ [1,4,7],[2,5,8],[3,6,9] ]" を返す。

Hash オブジェクト

Hash オブジェクトはハッシュ構造を提供します。例: キー:値の組の集合

Hash オブジェクトの各要素は二つの要素を持つ配列です。最初がキーで、次が値です。各要素は二つのプロパティを持ちます。 key と value というわかりやすい名前となっています。

メソッド	種類	引数	説明
keys()	instance	(なし)	すべての要素のキーを Array として返す。
values()	instance	(なし)	すべての要素の値を Array として返す。
merge(otherHash)	instance	otherHash: Hash オブジェクト	渡されたハッシュと結合し、新しいハッシュを返す。
toQueryString()	instance	(なし)	ハッシュのすべての要素をクエリー文字列のように書式化された文字列として返す。例: 'key1=value1&key2=value2&key3=value3'
inspect()	instance	(なし)	ハッシュをキー:値の組として見やすくした文字列として返す。

ObjectRange クラス

Enumerable から継承

上限、下限を伴う値の範囲を表現します。

プロパティ	型	種類	説明
start	(any)	instance	範囲の下限。
end	(any)	instance	範囲の上限。
exclusive	Boolean	instance	範囲が境界値自身を含むかどうかを指定する(訳註:下限はこの値にかかわらずinclusive、上限のチェックがこの値に影響される)。

メソッド	種類	引数	説明
[ctor](start, end, exclusive)	constructor	start: 下限, end: 上限, exclusive: 境界値が範囲に含まれる？	start から end に広がる範囲オブジェクトを作成する。 start と end は同じ型のオブジェクトで、succ() メソッドを持たなければならないことに注意。
include(searchedValue)	instance	searchedValue: 探す値	指定された値が範囲に含まれているかどうかをチェックする。 true か false を返す。

Class オブジェクト

Class オブジェクトは、ライブラリ中で他のクラスを宣言するときに使われます。クラスを宣言する際にこのオブジェクトを用いると、コンストラクタとして振る舞う initialize() メソッドが定義されます。

下記の例を参照してください。

//declaring the class
var MySampleClass = Class.create();

//defining the rest of the class implementation
MySampleClass.prototype = {

   initialize: function(message) {
		this.message = message;
   },

   showMessage: function(ajaxResponse) {
      alert(this.message);
   }
};	

//now, let's instantiate and use one object
var myTalker = new MySampleClass('hi there.');
myTalker.showMessage(); //displays alert

メソッド	種類	引数	説明
create(*)	instance	(任意)	新しいクラスのためのコンストラクタを定義する。

Ajax オブジェクト

このオブジェクトは、AJAX 機能を提供する他のクラスの親クラス・名前空間として使われます。

プロパティ	型	種類	説明
activeRequestCount	Number	instance	現在処理中の AJAX リクエストの数。

メソッド	種類	引数	説明
getTransport()	instance	(なし)	新しい XMLHttpRequest オブジェクトを返す。

Ajax.Responders オブジェクト

Enumerable から継承

このオブジェクトは Ajax 関連のイベントが発生する際に呼び出されるオブジェクトのリストを管理します。例えば AJAX 操作のグローバルな例外ハンドラをフックするために用いることができます。

プロパティ	型	種類	説明
responders	Array	instance	AJAX イベント通知のために登録されたオブジェクトのリスト。

メソッド	種類	引数	説明
register(responderToAdd)	instance	responderToAdd: 呼び出されるメソッドを備えたオブジェクト。	responderToAdd 引数として渡されるオブジェクトは AJAX イベント (例: onCreate, onComplete, onException など) に即した名前のメソッドを持つ必要があります。対応するイベントが発生した際に、登録されたすべてのオブジェクトのうち、対応する名前のメソッドを持ったものに対して、そのメソッドが呼び出されます。
unregister(responderToRemove)	instance	responderToRemove: リストから取り除かれるオブジェクト。	responderToRemove 引数として渡されたオブジェクトは、登録されたオブジェクトのリストから取り除かれる。
dispatch(callback, request, transport, json)	instance	callback: 通知される AJAX イベントの名前, request: イベントに関連する Ajax.Request オブジェクト, transport: AJAX 呼び出しの実体となる XMLHttpRequest オブジェクト, json: (もし存在すれば) レスポンス中の X-JSON ヘッダ	登録されたオブジェクトのリストから、callback 引数で指定されたメソッドを持つものを探す。そして、見つかったメソッドは 3 つの引数を伴って呼び出される。 AJAX レスポンスが X-JSON HTTP ヘッダに JSON コンテンツを含んでいる場合、それが評価されて json 引数として渡される。イベントが onException の場合には、transport 引数には代わりに例外オブジェクトが渡され、json は渡されない。

Ajax.Base クラス

このクラスは、Ajax オブジェクトで定義されるほとんどの他のクラスにおいて、基底クラスとして使われます。

メソッド	種類	引数	説明
setOptions(options)	instance	options: AJAX options	AJAX 操作のための options を設定する。
responseIsSuccess()	instance	(なし)	AJAX 操作が成功すると true を、失敗すると false を返す。
responseIsFailure()	instance	(なし)	responseIsSuccess() の逆を返す。

Ajax.Request クラス

Ajax.Base から継承

AJAX 操作をカプセル化します。

プロパティ	型	種類	説明
Events	Array	static	AJAX 操作中に報告される可能性のあるイベント・ステータスのリスト。リストには 'Uninitialized', 'Loading', 'Loaded', 'Interactive', 'Complete' が含まれる。
transport	XMLHttpRequest	instance	AJAX 操作を担う XMLHttpRequest オブジェクト。
url	String	instance	リクエストで使われる URL。

メソッド	種類	引数	説明
[ctor](url, options)	constructor	url: 取得されるURL, options: AJAX options	指定された options を使って指定された url を呼び出す、このオブジェクトのインスタンスを作成する。 onCreate イベントは、このコンストラクタ呼び出しの最中に発生する。重要: 指定された URL はブラウザのセキュリティ設定に従うことに注意すること。多くの場合、ブラウザは現在のページと同じホスト(ドメイン)からでないとその URL を取得しない。ブラウザの設定変更を強要したり、ユーザーのブラウザーの選択肢を狭めたりしないためにも、ローカル URL のみを使う方がよい。 (Thanks Clay).
evalJSON()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはない。このメソッドは AJAX レスポンス中に X-JSON HTTP ヘッダが存在する場合に評価する際に内部的に呼び出される。
evalResponse()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはない。 AJAX レスポンスの Content-type ヘッダの値が text/javascript であった場合、レスポンス本体は評価(eval)される。その際にこのメソッドが用いられる。
header(name)	instance	name: HTTP ヘッダ名	AJAX レスポンスの任意の HTTP ヘッダの値を取得する。 AJAX 呼び出しが完了した後でのみ呼び出すことができる。
onStateChange()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはない。 AJAX 呼び出しのステータスが変更されたときにオブジェクト自身から呼び出される。
request(url)	instance	url: AJAX 呼び出しの URL	基本的にはこのメソッドは外部から呼ばれることはない。コンストラクタ呼び出しの際に既に呼ばれている。
respondToReadyState(readyState)	instance	readyState: 状態番号 (1 から 4)	基本的にはこのメソッドは外部から呼ばれることはない。 AJAX 呼び出しのステータスが変更されたときにオブジェクト自身から呼び出される。
setRequestHeaders()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはない。 HTTP リクエストを送信する際に、HTTP ヘッダを構築するために呼び出される。

options 引数オブジェクト

options 引数は、AJAX 操作において重要な役割を演じます。 options というクラスは存在しません。期待されるプロパティさえ持っていれば、どんなオブジェクトでも渡すことができます。 AJAX 呼び出しのために無名オブジェクトを作成するのが一般的です。

プロパティ	型	デフォルト値	説明
method	String	'post'	HTTP リクエストのメソッド。
parameters	String	''	リクエストに渡される URL エンコードされた値のリスト。
asynchronous	Boolean	true	AJAX 呼び出しが非同期かどうかを示す。
postBody	String	undefined	HTTP POST を使う際に、リクエストのボディとして渡される中身。
requestHeaders	Array	undefined	リクエストに渡される HTTP ヘッダのリスト。このリストは偶数個でなければならず、奇数番目はカスタムヘッダの名前、偶数番目はヘッダの値の文字列となる。例: ['my-header1', 'this is the value', 'my-other-header', 'another value']
onXXXXXXXX	Function(XMLHttpRequest, Object)	undefined	AJAX 呼び出しの際に、対応したイベント、ステータスに達した場合に呼び出されるカスタム関数。このオプションの "XXXXXXXX" の部分には、 Ajax.Request.Events のステータスや、 HTTP ステータスコードを入れることができる。例: var myOpts = {on403: notAllowed, onComplete: showResponse, onLoaded: registerLoaded};。使われる関数は、AJAX 操作を担う XMLHttpRequest オブジェクト、X-JSON HTTP レスポンスヘッダが評価(eval)されたもの、を引数として受け取る。
onSuccess	Function(XMLHttpRequest, Object)	undefined	AJAX 呼び出しが成功裡に完了した場合に呼び出されるカスタム関数。使われる関数は、AJAX 操作を担う XMLHttpRequest オブジェクト、X-JSON HTTP レスポンスヘッダが評価(eval)されたもの、を引数として受け取る。
onFailure	Function(XMLHttpRequest, Object)	undefined	AJAX 呼び出しが失敗した場合に呼び出されるカスタム関数。使われる関数は、AJAX 操作を担う XMLHttpRequest オブジェクト、X-JSON HTTP レスポンスヘッダが評価(eval)されたもの、を引数として受け取る。
onException	Function(Ajax.Request, exception)	undefined	AJAX 呼び出しにおいて、クライアント側で不正なレスポンスや不正な引数のような例外が発生した際に呼び出されるカスタム関数。この関数は AJAX 操作を担う Ajax.Request オブジェクトと、例外オブジェクト、という二つの引数を受け取る。
insertion	Insertion クラス	undefined	新しいコンテンツがどのように挿入されるかを決めるクラス。 Insertion.Before, Insertion.Top, Insertion.Bottom, Insertion.After のいずれかが指定できる。 Ajax.Updater オブジェクトのみに適用。
evalScripts	Boolean	undefined, false	レスポンスが返ってきた時に、その文字列をスクリプトとして評価 (eval) するかどうかを示す。 Ajax.Updater オブジェクトのみに適用。
decay	Number	undefined, 1	受け取ったレスポンスが以前のものと同じである際に、Ajax.PeriodicalUpdater オブジェクトのリフレッシュレートが遅くなる度合を示す。例えば、2 を指定すると、リフレッシュの結果が以前のものと同じだった場合に、オブジェクトは次のリフレッシュまで以前の 2倍待つ。さらにもう一度同じ結果が繰り返されると、オブジェクトは元の 4 倍待ち、という形になる。 undefined のままにしておくか、1 を指定することで遅くならないようにできる。
frequency	Number	undefined, 2	各リフレッシュ間の間隔 (周期ではない) を秒単位で指定する。 Ajax.PeriodicalUpdater オブジェクトにのみ適用される。

Ajax.Updater クラス

Ajax.Request から継承

リクエストした URL が、ページ内の特定の要素に直に流し込むことができる HTML を返す時に使います。また、このオブジェクトは URL が直接評価 (eval) することができる <script> ブロックを返す際にも利用できます。スクリプトとして使う場合には evalScripts オプションを指定してください。

プロパティ	型	種類	説明
containers	Object	instance	二つのプロパティを持つオブジェクト: containers.success は AJAX 呼び出しが成功した時に使われる関数。 containers.failure は失敗した時に使われる関数。

メソッド	種類	引数	説明
[ctor](container, url, options)	constructor	container: 要素の ID, 要素オブジェクトそのもの, もしくは以下のふたつのプロパティを持つオブジェクト - object.success AJAX呼び出しが成功した際に使われる要素(もしくはID), object.failure 失敗した際に使われる要素(もしくはID), url: 取得されるURL, options: AJAX options	指定された options を使って指定された url を呼び出す、このオブジェクトのインスタンスを作成する。
updateContent()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはない。レスポンスが届いた時にオブジェクト自身から呼び出される。この関数は適切な要素を HTML で更新するか、insertion オプションで指定された関数を呼び出す。関数は更新される要素オブジェクト、レスポンス文字列の二つの引数を伴って呼び出される。

Ajax.PeriodicalUpdater クラス

Ajax.Base から継承

このクラスは、ページ上の要素をリフレッシュするため、もしくは Ajax.Updater ができる他のタスクを実行するために、定期的に Ajax.Updater オブジェクトのインスタンスを作成し、利用します。詳しくは Ajax.Updater リファレンスを参照してください。

プロパティ	型	種類	説明
container	Object	instance	この値は Ajax.Updater のコンストラクタにそのまま渡される。
url	String	instance	この値は Ajax.Updater のコンストラクタにそのまま渡される。
frequency	Number	instance	リフレッシュ間隔(秒)。デフォルトは 2 秒。 Ajax.Updater オブジェクトが実行される際に、この数字に現在の decay を掛けたものが使われる。
decay	Number	instance	タスクを再度実行する際に適用される decay level の現在値。
updater	Ajax.Updater	instance	直前に実行された Ajax.Updater オブジェクト
timer	Object	instance	次のリフレッシュ時間をオブジェクトに知らせるための JavaScript タイマーへのハンドル。

メソッド	種類	引数	説明
[ctor](container, url, options)	constructor	container: 要素の ID, 要素オブジェクトそのもの, もしくは以下のふたつのプロパティを持つオブジェクト - object.success AJAX呼び出しが成功した際に使われる要素(もしくはID), object.failure 失敗した際に使われる要素(もしくはID), url: 取得されるURL, options: AJAX options	指定された options を使って指定された url を呼び出す、このオブジェクトのインスタンスを作成する。
start()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはない。定期的なタスクを開始する際にオブジェクト自身から呼ばれる。
stop()	instance	(なし)	そのオブジェクトの定期的なタスクを終了する。 onComplete オプションが指定されていた場合、終了後にそのコールバック関数を呼び出す。
updateComplete()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはない。リクエストが完了した後に現在使っている Ajax.Updater から呼ばれる。次のリフレッシュをスケジュールするために使われる。
onTimerEvent()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはない。次の更新のタイミングで内部で呼ばれる。

Element オブジェクト

このオブジェクトでは、DOM 内の要素を操作するのに便利な関数を提供します。

メソッド	種類	引数	説明
addClassName(element, className)	instance	element: 要素オブジェクトかID, className: CSS クラス名	指定されたクラス名を要素のクラス名に加える。
classNames(element)	instance	element: 要素オブジェクトかID	与えられた要素に関連する CSS クラス名を表す Element.ClassNames オブジェクトを返す。
cleanWhitespace(element)	instance	element: 要素オブジェクトかID	要素の子供のテキストノードから空白(white space)を取り除く。
empty(element)	instance	element: 要素オブジェクトかID	要素タグ(の innerHTML)が空 (もしくは空白のみ) かどうかを示す Boolean 値を返す。
getDimensions(element)	instance	element: 要素オブジェクトかID	要素の大きさを返す。返される値は height と width の二つのプロパティを持つオブジェクト。
getHeight(element)	instance	element: 要素オブジェクトかID	要素の offsetHeight を返す。
getStyle(element, cssProperty)	instance	element: 要素オブジェクトかID, cssProperty: CSS プロパティ名 ('prop-name', 'propName' のどちらの形式でもOK)	指定された要素の CSS プロパティの値を返す。存在しなければ null を返す。
hasClassName(element, className)	instance	element: 要素オブジェクトかID, className: CSS クラス名	指定されたクラス名が要素のクラス名に含まれている場合に true を返す。
hide(element)	instance	element: 要素オブジェクトかID	style.display を 'none' に設定し、要素を隠す。
makeClipping(element)	instance	element: 要素オブジェクトかID
makePositioned(element)	instance	element: 要素オブジェクトかID	要素の style.position を 'relative' に変更する。
remove(element)	instance	element: 要素オブジェクトかID	ドキュメントから要素を削除する。
removeClassName(element, className)	instance	element: 要素オブジェクトかID, className: CSS クラス名	要素のクラス名から指定されたクラス名を取り除く。
scrollTo(element)	instance	element: 要素オブジェクトかID	要素の位置までウィンドウをスクロールする。
setStyle(element, cssPropertyHash)	instance	element: 要素オブジェクトかID, cssPropertyHash: 適用される CSS プロパティハッシュ	指定された cssPropertyHash 引数の値から、要素の CSS プロパティを設定する。
show(element)	instance	element: 要素オブジェクトかID	style.display を '' に設定し、要素を表示する。
toggle(element)	instance	element: 要素オブジェクトかID	渡された要素の表示状態を反転する。
undoClipping(element)	instance	element: 要素オブジェクトかID
undoPositioned(element)	instance	element: 要素オブジェクトかID	要素の style.position を '' に変更する。
update(element, html)	instance	element: 要素オブジェクトかID, html: HTML コンテンツ	要素の innerHTML を渡された html 引数で置き換える。与えられた html が <script> ブロックを含む場合、そのまま代入されるのではなく評価(eval)される。
visible(element)	instance	element: 要素オブジェクトかID	要素が visible かどうかを示す Boolean を返す。

Element.ClassNames クラス

Enumerable から継承

要素に関連付けられた CSS クラス名の集合を表します。

メソッド	種類	引数	説明
[ctor](element)	constructor	element: 任意の DOM 要素オブジェクトかID	指定された要素の CSS クラス名を示す Element.ClassNames オブジェクトを作成する。
add(className)	instance	className: CSS クラス名	関連付けられた要素のクラス名リストに、指定された CSS クラス名を加える。
remove(className)	instance	className: CSS クラス名	関連付けられた要素のクラス名リストから、指定された CSS クラス名を取り除く。
set(className)	instance	className: CSS クラス名	関連付けられた要素のクラス名を、指定された CSS クラス名に設定する。要素に設定されている他のクラス名は予め削除される。

Abstract オブジェクト

このオブジェクトは、ライブラリ中の他のクラスの基底クラスとして使われます。このオブジェクト自体はプロパティ、メソッドは提供しません。このオブジェクトで定義されるクラスは典型的な抽象クラスとしても扱われます。

Abstract.Insertion クラス

このクラスは動的なテキスト挿入を提供する他のクラスの基底クラスとして使われます。このクラスは抽象クラスのように使われます。

メソッド	種類	引数	説明
[ctor](element, content)	constructor	element: 要素オブジェクトかID, content: 挿入されるHTML	動的なテキスト挿入を支援するオブジェクトを作成する。
contentFromAnonymousTable()	instance	(なし)

プロパティ	型	種類	説明
adjacency	String	static, parameter	テキストが挿入される、指定された要素からの相対的位置を指定するパラメータ。取りうる値: 'beforeBegin', 'afterBegin', 'beforeEnd', 'afterEnd'
element	Object	instance	挿入が行われる位置の基準となる要素。
content	String	instance	挿入される HTML。

Insertion オブジェクト

このオブジェクトはライブラリ中の他のクラスの基底クラスとして使われます。このオブジェクト自体はプロパティ、メソッドは提供しません。このオブジェクトで定義されるクラスは典型的な抽象クラスとしても扱われます。

Insertion.Before クラス

Abstract.Insertion から継承

要素の前に HTML を挿入します。

メソッド	種類	引数	説明
[ctor](element, content)	constructor	element: 要素オブジェクトかID, content: 挿入されるHTML	Abstract.Insertion から継承する。動的なテキスト挿入を支援するオブジェクトを作成する。

下記のコードは

< /br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>

<script> new Insertion.Before('person', 'Chief '); </script>

以下のような HTML に変更されます。


< /br>Hello, Chief <span id="person" style="color:red;">Wiggum. How's it going?</span>

Insertion.Top クラス

Abstract.Insertion から継承

要素下の最初の子供として HTML を挿入します。テキストは要素の開始タグの直後に挿入されます。

メソッド	種類	引数	説明
[ctor](element, content)	constructor	element: 要素オブジェクトかID, content: 挿入されるHTML	Abstract.Insertion から継承する。動的なテキストの挿入を支援するオブジェクトを作成する。

下記のコードは

< /br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>

<script> new Insertion.Top('person', 'Mr. '); </script>

以下のような HTML に変更されます。

< /br>Hello, <span id="person" style="color:red;">Mr. Wiggum. How's it going?</span>

Insertion.Bottom クラス

Abstract.Insertion から継承

要素下の最後の子供として HTML を挿入します。テキストは要素の終了タグの直前に挿入されます。

メソッド	種類	引数	説明
[ctor](element, content)	constructor	element: 要素オブジェクトかID, content: 挿入されるHTML	Abstract.Insertion から継承する。動的なテキスト挿入を支援するオブジェクトを作成する。

下記のコードは

< /br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>

<script> new Insertion.Bottom('person', " What's up?"); </script>

以下のような HTML に変更されます。

< /br>Hello, <span id="person" style="color:red;">Wiggum. How's it going? What's up?</span>

Insertion.After クラス

Abstract.Insertion から継承

要素の終了タグの直後に HTML を挿入します。

メソッド	種類	引数	説明
[ctor](element, content)	constructor	element: 要素オブジェクトかID, content: 挿入されるHTML	Abstract.Insertion から継承する。動的なテキスト挿入を支援するオブジェクトを作成する。

下記のコードは

< /br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>

<script> new Insertion.After('person', ' Are you there?'); </script>

以下のような HTML に変更されます。

< /br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> Are you there?

Field オブジェクト

このオブジェクトは、フォームの入力フィールドで使うと便利な関数を提供します。

メソッド	種類	引数	説明
clear(field1 [, field2 [, field3 [...]]])	instance	fieldN: フィールド要素オブジェクトかID	渡された各フォームフィールド要素の値をクリアする。
present(field1 [, field2 [, field3 [...]]])	instance	fieldN: フィールド要素オブジェクトかID	全てのフォームフィールドが空でない値を持っている場合にのみ true を返す。
focus(field)	instance	field: フィールド要素オブジェクトかID	与えられたフォームフィールドに入力フォーカスを移動する。
select(field)	instance	field: フィールド要素オブジェクトかID	テキストの選択をサポートするフィールドにおいて値を選択する。
activate(field)	instance	field: フィールド要素オブジェクトかID	フォーカスを移動し、テキストの選択をサポートしているフィールドでは値を選択する。

Form オブジェクト

このオブジェクトでは、データ入力フォームや入力フィールドで使うための関数を提供します。

メソッド	種類	引数	説明
serialize(form)	instance	form: フォーム要素オブジェクトかID	フィールド名とその値のリストを URL エンコードして返す。例: 'field1=value1&field2=value2&field3=value3'
findFirstElement(form)	instance	form: フォーム要素オブジェクトかID	フォーム中の最初の有効化(enabled)されているフィールド要素を返す。
getElements(form)	instance	form: フォーム要素オブジェクトかID	フォーム中の全ての入力フィールドを含む Array を返す。
getInputs(form [, typeName [, name]])	instance	form: フォーム要素オブジェクトかID, typeName: input 要素の type, name: input 要素の name	フォーム中の全ての <input> 要素を含む Array を返す。オプションとして、要素の type 属性や name でフィルタすることが可能。
disable(form)	instance	form: フォーム要素オブジェクトかID	フォーム中の全ての入力フィールドを無効化(disable)する。
enable(form)	instance	form: フォーム要素オブジェクトかID	フォーム中の全ての入力フィールドを有効化(enable)する。
focusFirstElement(form)	instance	form: フォーム要素オブジェクトかID	フォーム中の最初の表示されて(visible)、有効化(enable)されている入力フィールドを活性化(activate)する。
reset(form)	instance	form: フォーム要素オブジェクトかID	フォームをリセットする。フォームオブジェクトの reset() メソッドを呼び出すのと同じ。

Form.Element オブジェクト

このオブジェクトは、フォーム要素で使うことができる関数を提供します。

メソッド	種類	引数	説明
serialize(element)	instance	element: 要素オブジェクトかID	要素の name=value ペアを返す。例: 'elementName=elementValue'
getValue(element)	instance	element: 要素オブジェクトかID	要素の値を返す。

Form.Element.Serializers オブジェクト

このオブジェクトは、フォーム要素の現在値を取り出すために、ライブラリ内部で使われる関数を提供します。

メソッド	種類	引数	説明
inputSelector(element)	instance	element: ラジオボタンやチェックボックスのような, checked プロパティを持つフォーム要素のオブジェクトかID	要素の名前と値を Array として返す。例: ['elementName', 'elementValue']
textarea(element)	instance	element: テキストボックス, ボタン, パスワードフィールドのような, value プロパティを持つフォーム要素のオブジェクトかID	要素の名前と値を Array として返す。例: ['elementName', 'elementValue']
select(element)	instance	element: <select> 要素のオブジェクト	要素の名前と、選択された全てのオプションの値/テキストを Array として返す。例: ['elementName', 'selOpt1 selOpt4 selOpt9']

Abstract.TimedObserver クラス

このクラスは、ある要素の値(もしくは派生クラスが定義するプロパティ)が変更されるまでその要素を監視するような他のクラスの基底クラスとして使われます。このクラスは抽象クラスのように使われます。

要素の入力値、スタイルプロパティのうちのひとつ、テーブル内の行数、など変更を追跡したいと思うものを監視するためのサブクラスを作ることができます。

メソッド	種類	引数	説明
[ctor](element, frequency, callback)	constructor	element: 要素オブジェクトかID, frequency: 間隔(秒), 要素が変更された時に呼び出されるコールバック関数	要素を監視するオブジェクトを作成する。
getValue()	instance, abstract	(なし)	要素中で監視されている値の現在値を確認するために、派生クラスではこのメソッドを実装する必要がある。
registerCallback()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはない。要素の監視を開始するためにオブジェクト自身から呼び出される。
onTimerEvent()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはない。要素をチェックするために定期的にオブジェクト自身から呼び出される。

プロパティ	型	説明
element	Object	監視される要素オブジェクト。
frequency	Number	実際のチェック間隔(秒)。
callback	Function(Object, String)	要素が変更された時に呼び出される関数。関数には要素オブジェクトと新しい値が渡される。
lastValue	String	要素から最後に確認された値。

Form.Element.Observer クラス

Abstract.TimedObserver から継承

フォームの入力要素の値を監視する Abstract.TimedObserver の実装。値が変更されたことを報告するイベントを提供しない要素を監視する際にこのクラスを使います。イベントを発生させるような要素の場合には、代わりに Form.Element.EventObserver クラスを使うことができます。

メソッド	種類	引数	説明
[ctor](element, frequency, callback)	constructor	element: 要素オブジェクトかID, frequency: 間隔(秒), callback: 要素が変更された時に呼び出されるコールバック関数	Abstract.TimedObserver から継承。指定された要素の value プロパティを監視するオブジェクトを作成する。
getValue()	instance	(なし)	要素の値を返す。

Form.Observer クラス

Abstract.TimedObserver から継承

フォーム中の全てのデータ入力要素の値の変更を監視する Abstract.TimedObserver の実装。値が変更されたことを報告するイベントを提供しない要素を含むフォームを監視する際にこのクラスを使います。イベントを発生させない要素を含まない場合には、代わりに Form.EventObserver クラスを使うことができます。

メソッド	種類	引数	説明
[ctor](form, frequency, callback)	constructor	form: フォームオブジェクトかID, frequency: 間隔(秒), callback: フォーム中のデータ入力要素が変更された時に呼び出されるコールバック関数	Abstract.TimedObserver から継承。フォームの変更を監視するオブジェクトを作成する。
getValue()	instance	(なし)	フォームの全てのデータを文字列化(serialize)して返す。

Abstract.EventObserver クラス

このクラスは、要素に値が変更されるイベントが発生した時にコールバック関数が実行されるような他のクラスの基底クラスとして使われます。

複数の Abstract.EventObserver 型のオブジェクトを、互いに衝突することなく同一の要素に関連づけることができます。コールバック関数は、要素に割り当てられた順番で実行されます。

契機となるイベントは、ラジオボタンやチェックボックスの場合は onclick、テキストボックス全般やリストボックス、ドロップダウンの場合は onchange となります。

メソッド	種類	引数	説明
[ctor](element, callback)	constructor	element: 要素オブジェクトかID, callback: イベントが発生した際に呼び出されるコールバック関数	要素を監視するオブジェクトを作成する。
getValue()	instance, abstract	(なし)	要素中で監視されている値の現在値を確認するために、派生クラスではこのメソッドを実装する必要がある。
registerCallback()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはありません。要素のイベントにオブジェクト自身を関連づけるために、オブジェクトから呼び出されます。
registerFormCallbacks()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはありません。フォーム中の各データ入力要素のイベントにオブジェクト自身を関連づけるために、オブジェクトから呼び出されます。
onElementEvent()	instance	(なし)	基本的にはこのメソッドは外部から呼ばれることはありません。要素のイベントハンドラとして関連づけられ、コールバック関数が呼び出されます。

プロパティ	型	説明
element	Object	監視される要素オブジェクト。
callback	Function(Object, String)	要素が変更された時に呼び出される関数。要素オブジェクトと新しい値を引数として受け取る。
lastValue	String	要素から最後に確認された値。

Form.Element.EventObserver クラス

Abstract.EventObserver から継承

値の変更を検出するために、フォームのデータ入力要素の関連づけられたイベントに対してコールバック関数を実行する Abstract.EventObserver の実装。要素が変更を通知するイベントを発生しない場合には、Form.Element.Observer クラスを代わりに使うことができます。

メソッド	種類	引数	説明
[ctor](element, callback)	constructor	element: 要素オブジェクトかID,イベントが発生した時に呼び出されるコールバック関数	Abstract.EventObserver から継承。要素の value プロパティを監視するオブジェクトを作成する。
getValue()	instance	(なし)	要素の値を返す。

Form.EventObserver クラス

Abstract.EventObserver から継承

要素の値の変更を検出するのに要素のイベントを使い、フォーム中に含まれる全てのデータ入力要素の変更を監視する Abstract.EventObserver の実装。要素を含むフォームが変更を通知するイベントを発生しない場合には、Form.Observer クラスを代わりに使うことができます。

メソッド	種類	引数	説明
[ctor](form, callback)	constructor	form: フォームオブジェクトかID, callback: フォーム中のいずれかのデータ入力要素が変更された時に呼び出されるコールバック関数	Abstract.EventObserver から継承。フォームの変更を監視するオブジェクトを作成する。
getValue()	instance	(なし)	フォームの全てのデータを文字列化(serialize)して返す。

Position オブジェクト (仮ドキュメント)

このオブジェクトは、要素の座標配置の際に便利な関数を提供します。

メソッド	種類	引数	説明
prepare()	instance	(なし)	スクロール位置の変更がうまく働くように、 deltaX プロパティと deltaY プロパティを調整する。ページスクロールの後で withinIncludingScrolloffset を呼ぶ前に、このメソッドを呼び出すことを忘れないこと。
realOffset(element)	instance	element: オブジェクト	指定された要素の(影響を与えうる親要素の値を含む)修正済みのスクロールオフセットを Array で返す。返される配列は [total_scroll_left, total_scroll_top] のような形となる。
cumulativeOffset(element)	instance	element: オブジェクト	指定された要素の(親要素により影響を受けたものを含む)修正済みの位置オフセットを Array で返す。返される配列は [total_offset_left, total_offset_top] のような形となる。
within(element, x, y)	instance	element: オブジェクト, x と y: 点の座標	指定された点座標が、指定された要素の矩形内に含まれるかどうかをチェックする。
withinIncludingScrolloffsets(element, x, y)	instance	element: オブジェクト, x と y: 点の座標
overlap(mode, element)	instance	mode: 'vertical' か 'horizontal', element: オブジェクト	このメソッドを呼び出す直前に within() を呼び出す必要がある。このメソッドは、要素上に重なる座標の割合を示す 0.0 から 1.0 の間の 10 進数の値を返す。例えば、divSquare 要素が 100px 幅で (300, 300) に位置する矩形 DIV として、 within(divSquare, 330, 330); overlap('vertical', divSquare); は 0.70 を返す。これは (330, 330) の座標が DIV の下辺から 70% (100px - 30px = 70px) 離れている、ということを示す。これを理解するには、最初の矩形と重なり、左上の座標が指定された座標であるような矩形を考える。返される値は、二番目の矩形が十分大きいとして幅や高さが重なっている(最初の矩形からみた)割合となる。
clone(source, target)	instance	source: 要素オブジェクトかID, target: 要素オブジェクトかID	target 要素を source 要素と同じ大きさに変更し、同じ位置に移動する。

訳註: 翻訳上の勘違い、ミスなどの責任はにありますので、改善点などありましたらお知らせください。原文における問題点などは下記の通り Sergio に直接メールを送ってあげてください。

The documentation for v1.5.0 is still in progress. Stay tuned for updates in this document.
If you find errors, inaccurate or incomplete information, or flat-out nonsense, please and I'll try to fix it as soon as possible.

prototype.js の開発者向けメモ

バージョン 1.5.0 対応

目次

それは何？

関連資料

ユーティリティ関数

$() 関数を使う

$$() 関数を使う

$F() 関数を使う

$A() 関数を使う

$H() 関数を使う

$R() 関数を使う

Try.these() 関数を使う

文字列を操る

文字列の置換

文字列テンプレート

Ajax オブジェクト

Ajax.Request クラスを使う

Ajax.Updater クラスを使う

この "?" とか豆腐みたいなのとかは何なの？

数え上げ、列挙……まったくもう！

Ruby スタイルのループ

配列をパワーアップ！

お薦めの書籍

prototype.js リファレンス

JavaScript 基本クラスの拡張

Object クラスに対する拡張

Number クラスに対する拡張

Function クラスに対する拡張

String クラスに対する拡張

Array クラスに対する拡張

document DOM オブジェクトに対する拡張

Event オブジェクトに対する拡張

prototype.js によって新しく定義されたオブジェクトとクラス

PeriodicalExecuter オブジェクト

Prototype オブジェクト

Enumerable オブジェクト

Hash オブジェクト

ObjectRange クラス

Class オブジェクト

Ajax オブジェクト

Ajax.Responders オブジェクト

Ajax.Base クラス

Ajax.Request クラス

options 引数オブジェクト

Ajax.Updater クラス

Ajax.PeriodicalUpdater クラス

Element オブジェクト

Element.ClassNames クラス

Abstract オブジェクト

Abstract.Insertion クラス

Insertion オブジェクト

Insertion.Before クラス

Insertion.Top クラス

Insertion.Bottom クラス

Insertion.After クラス

Field オブジェクト

Form オブジェクト

Form.Element オブジェクト

Form.Element.Serializers オブジェクト

Abstract.TimedObserver クラス

Form.Element.Observer クラス

Form.Observer クラス

Abstract.EventObserver クラス

Form.Element.EventObserver クラス

Form.EventObserver クラス

Position オブジェクト (仮ドキュメント)