多機能で拡張性に優れたStar Rating Plugin

今回PukiWikiで5段階評価を付けるプラグインを作成するにあたり「jQuery Raty」を利用しました。

公式ページのドキュメントで丁寧に解説されています。しかし、英語のため細かい部分がわからず手こずりました。このページでは利用方法をまとめました。

---

jQuery Ratyの使い方

「jQuery Raty」は名前の通りjQueryを利用して動作するJavaScriptのライブラリです。

公式ページの解説が非常に丁寧なので、jQueryの一般的な書式で動作することがわかると思います。

1.jQuery Ratyをダウンロード

まずはjQuery Raty公式ページの右上にあるv2.7.0をクリックしてダウンロード、解凍します。
（2016年4月追記：公式ページにアクセスできない状態です。現在はGitHubのページで提供されています）

2.HTMLファイルを作成してjQueryを読込み、jquery.raty.jsへのパスを記述

とりあえずjQueryは、信頼と安心のGoogleのCDNが提供してくれているものを利用します。以下の記述だとjQueryの1.x系の最終バージョンが読み込まれます。

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"></script>
<script type="text/javascript" src="./jquery.raty.js"></script>

3.jquery.raty.js用の設定を記述

あとはjQueryの書式でDOM要素を指定するだけです。

<div></div>

<script type="text/javascript">
$('div').raty();
</script>

デモページ

とても簡単ですね。
これだけでは何なので、カスタマイズの要点を少し。

星の画像を置いてあるディレクトリを指定する

$.fn.raty.defaults.path = "./images";
$('div').raty();

デモページ

予めスコアを表示する（この例では3）

$(function raty() {
	$("div").raty({
		number: 5,
		score : 3
	});
});

デモページ

評価数を10段階にする

$(function raty() {
	$("div").raty({
		number: 10,
		score : 3
	});
});

デモページ

マウスオーバー時の表示（hint）を変更する

デフォルトはhints: [‘bad’, ‘poor’, ‘regular’, ‘good’, ‘gorgeous’]

$(function raty() {
	$("div").raty({
		hints: ['1', '2', '3', '4', '5']
	});
});

デモページ

クリックしたスコアやイベントを表示する

evtで何が取れるかはconsole.log(evt);で見てください。

$('div').raty({
	click: function(score, evt) {
		alert("score: " + score + "\nevent: " + evt.type);
	}
});

デモページ

スコアやイベントの情報を外部のPHPファイルへ渡す

$('div').raty({
	click: function(score, evt) {
		$.post('./raty.php',{score:score, url:evt.currentTarget.baseURI},
		function(data){
			location.href = './sample.txt';
		});
	}
});

渡される側のPHP（raty.php）

実際にはXSS対策やバリデーションを行ってください。

<?php
$score = $_POST['score'];
$url = $_POST['url'];
$raty = 'score:' . $score . ',url:' . $url . "\n";

$fp = fopen("sample.txt", "a");
fwrite($fp, $raty);
fclose($fp);
?>

デモページ

ここまでできれば後はMySQLに渡すなり、CSVファイルに書き出すなり自由に利用できます。

今回紹介した機能の他にも、星画像を1つ1つ変更する方法、3.5など小数点を切り捨てるか切り上げるかの指定、入力したスコアをキャンセルするボタンの設置など、便利な機能が用意されています。
詳しくは公式ページを参照してください。

今回PukiWikiのプラグインで使用したコード

一応サンプルとして残しておきます。
PukiWikiにはプラグインにGETでパラメータを渡すことができるので、スコアを渡してからURLを更新しています。

<script type="text/javascript">
$(function raty0() {
$.fn.raty.defaults.path = "./image";
$(".star0").raty({
number: 5,
score : 0,
click: function(score, evt) {
var url = "プラグインのURL" + score;
location.href=url;
}
});
});
</script>

---

以上、カスタマイズ次第で何にでも使える汎用性の高いプラグインjQuery Ratyのまとめでした。

次回はPukiWikiのプラグインに組み込んでみます。