Screw-Axis /螺旋軸/

[jQuery] スピンボタンで数値入力補助

自作のjQueryプラグインを追加しました。
最近むしろあまり見なくなった(?)スピンボタンインターフェースをWebフォーム上に簡単に実装するためのプラグインです。

実はこちらのプラグインは新作ではなく、1年以上前からjQuery本家公式リポジトリとGoogle Codeで公開しています。
意外なことに地味に好評で(特に海外で)、ダウンロード数も確認できるだけで累計で2,000を超えていました。バグ報告や機能追加要望も幾つかもらっていたのですが、多忙を言い訳にひたすら放置してしまっていた可哀想な子です。
今回、利用している方からメールをいただいて急にやる気が出て、ついでにgithubにプロジェクトを作ったりしながら大幅にバージョンアップして、日本語のページも用意した次第です。
今まで不便をかけていた方には、本当に申し訳ありませんでした。

jQuery Spin

概要

jQuery Spinは、jQueryのプラグインとして動作します。
入力フォームで数値を扱うことがありますが、その際の入力補助用のインターフェースです。

動作

以下のフィールドに、数値を入力します。右側の上下のスピンボタンを使うと便利です。

マウスを押したままにすると、連続して値が変化します。

使い方

まずjQuery本体が必要になります。
jQueryそのものの導入については、別途ドキュメントなどを参照してください。

jQuery Spinは、Google Codeから入手してください。

まず最初にスクリプトの配置と共に、スピンボタンの表面画像を配置しなければなりません。
画像は「押されていない状態」「上が押された状態」「下が押された状態」の3枚が必要です。
サンプルとして、ダウンロードファイルにも画像が入っているので、参考にしながら独自の見た目を作ってください。

3枚の画像は、同じディレクトリに置かなければいけません。ここでは仮に、”/images/spin/”に配置したとします。

スピンボタンの設定は、spinメソッドを呼ぶだけで簡単に行うことが出来ます。
オプションには様々なものがありますが、画像の場所指定だけはきちんと行わないと、全く動作しなくなってしまいます。

$('input').spin({imageBasePath: '/images/spin/'});

画像の場所を示すimageBasePathオプションの初期値は”/img/spin/”です。この場所に置いた場合のみ、指定は省略できます。

しかし、ページに複数のスピンボタンを設置する場合など、毎回同じオプションを指定するのも馬鹿馬鹿しい場合があります。
そんな時は、$.spinオブジェクトに値を設定することで、すべての呼び出しの初期値を変えることができます。

$.spin.imageBasePath = '/images/spin/';
$('#sample1').spin();
$('#sample2').spin();
$('#sample3').spin();

この例では、3つのspinの呼び出し全てに”/images/spin/”が適用されます。

オプション

jQuery Spinは、多くのオプションで動作を指定することができます。
オプションは多くのプラグイン同様に、メソッドの引数としてオブジェクトを渡してやることで指定できます。
指定可能なオプションは、次の通りです。

imageBasePath

スピンボタンの表面画像の配置場所を示します。初期値は”/img/spin/”ですが、ここに運良く置けるのでない限り、必須指定項目lとなるでしょう。

spinBtnImage/spinUpImage/spinDownImage

順に、「通常時」「上を押した時」「下を押した時」の画像ファイル名です。通常は変える必要は無いはずです。

interval

値の増減幅です。例えばここに”3″と指定すれば、上下ボタンで3ずつ値が変化します。小数値を設定することも可能です。
初期値は1です。

max/min

入力可能な値の最大/最小値です。但し、直接入力の値を制限したりするものではないので、バリデーションには注意してください。値を設定しない場合、制限無しを意味します。

timeInterval

スピンボタンをマウスで押しっぱなしの状態にした際に、値の変化していく時間を決めます。小さな値を設定するほど、短い間隔で値が変化します。
初期値は500(ミリ秒)です。

timeBlink

見栄えとしての上が押された/下が押された状態の画像を表示する時間です。
初期値は200(ミリ秒)です。

btnClass

ボタン画像にあてられるクラス名です。

btnCss

ボタン画像にあてられるスタイルです。指定はCSSオブジェクトの形です。

txtCss

テキストエリアにあてられるスタイルです。

lock

テキストエリアへの直接入力を禁止したい場合にtrueにします。完璧に直接入力を防げるわけではなく、過信しすぎないよう注意してください。

decimal

小数点を”.”ではなくしたい場合に指定します。例えば”,”を指定すれば、”1.8″は”1,8″になります。

beforeChange

値がスピンボタンによって変更される前に呼ばれるコールバック関数です。
第一引数にこれから変更されようとしている新しい値、第二引数には現時点の値が渡されます。戻り値にfalseを返した場合、その変更はキャンセルされます。

changed

値が変更された後に呼び出されるコールバック関数です。

buttonUp/buttonDown

上下のスピンボタンが押された際に呼び出されるコールバック関数です。値が上限を超えているなどの理由で変更されない場合にも呼び出されます。

$.spinオブジェクトの値を変えることで、オプションの初期値を変えてしまうことも可能です。

ここでは、幾つかのオプションを組み合わせた例を見てみましょう。

$('#sample1').spin({
  imageBasePath: 'http://dev.screw-axis.com/jquery-spin/demo/img/spin2/',
  interval: 10,
  max: 300,
  min: 0,
  timeInterval: 250
});

[実行結果]

プロジェクトサイト

• 本家プラグインリポジトリ
• Google Code
• github

ライセンス

コードにも記載していますが、MITとGPLのデュアルライセンスとします。
全く自由に使っていただいて構いませんが、どこかで利用したり紹介していただいた際は、ご一報いただけると喜ぶと思います。

Jetpack APIリファレンス

« Jetpack

グローバル名前空間

Jetpack Featureのグローバル名前空間には、殆どの機能が含まれています。この名前空間は、ちょうどWebページのグローバル名前空間のように見えるように作られています。

XMLHttpRequest()

XMLHttpRequestは、URLベースでデータを取得する簡単な方法を提供します。詳細についてはリファレンスを参照してください。
WebでAjax通信などで使われる同名のXMLHttpRequestと異なり、このオブジェクトは異なったドメインへのアクセスも可能です。
Jetpackが標準で搭載しているjQueryを用いることで、更に非常にシンプルにXMLHttpRequestの機能をAPIとして使うことができます。これについてはjQueryのAjaxに関するドキュメント(本家[英語])を参照してください。

clearInterval

この関数は、通常のJavascriptにおけるwindow.clearIntervalと同様に動作します。

clearTimeout

この関数は、通常のJavascriptにおけるwindow.clearTimeoutと同様に動作します。

console

このオブジェクトは、デバッグのためにFirebugコンソールにメッセージを出力する目的で使われます。log, info, warn, errorといったメソッドを、メッセージの重要度の違いによって使い分けてください。これらの関数は全て、引数を幾つでも受け取り、全ての引数はログ出力されます。

次の例は、コンソールにログを出力させます。

console.log('Hello from the Jetpack feature', this);
console.info('情報');
console.warn('警告');
console.error('エラー');

jQuery

jQueryは軽量なJavascriptライブラリです。jQueryオブジェクトは簡単に $ 関数としても使うことができます。
全てのAjaxリクエストは、jQueryによって提供されているクロスサイトで利用可能なXMLHttpRequestオブジェクトで行われています。
より詳細な情報は、jQuery本家(英語)もしくは、非公式ですがjQuery日本語リファレンスなどを参照してください。

jetpack

名前空間 “jetpack” は全てのJetpack Featureで利用可能な、Firefoxの機能にアクセスする主要なポイントになるものです。このAPIは、Mozillaプラットフォームへの後方互換の軽量な受付口として設計されています。これは、Jetpackライブラリを用いてFeatureを書けば、Firefoxがバージョンアップしてもコードを書き換える必要が無いことを意味します。

jetpack.notifications.show({
         title: 'hai2u',
         body: 'o hai.',
         icon: 'http://www.mozilla.org/favicon.ico'
});

jetpack.future.import("slideBar");

jetpack.future.import("slideBar");
jetpack.slideBar.append({
  onSelect: function(slide) slide({ size: 100 }),
  onReady: function(slide) $(slide.doc).click(function() {
    slide({ size: 200, persist: true });
    slide.icon.src = "chrome://branding/content/icon48.png";
  })
});

jetpack.statusBar.append({
  html: '',
  width: 16,
  onReady: function(doc) {
    $(doc).find("img").click(function() {
      jetpack.notifications.show("hai2u");
      });
  }});

jetpack.storage.live.myData = {hello: "world"};
console.log( jetpack.storage.live.myData );

jetpack.future.import("storage.simple");
jetpack.storage.simple.set( "4ever", {hello:"world"} );
jetpack.storage.simple.get( "4ever", function(data, value){
  console.log( data, value );
});

jetpack.notifications.show(jetpack.tabs.focused.url);

jetpack.tabs.onFocus(function() {
  jetpack.notifications.show("You selected " + this.url);
  });

jetpack.tabs.onReady(function onNextPage(doc) {
  if (!doc.defaultView.frameElement) {
    jetpack.notifications.show("Loaded " + doc.location.href);
    jetpack.tabs.onReady.unbind(onNextPage);
  }});

location

この文字列は、機能のコードを示すURLになります。

以下の例は、現在のロケーションをコンソールに表示させます。

console.log(location);

setInterval

この関数は、window.setIntervalと同様に動作します。

setTimeout

この関数は、window.setTimeoutと同様に動作します。

Tabオブジェクト

Tabは、ブラウザのタブに関する機能を提供します。

close()

タブを閉じます。既にタブが閉じられている場合は、何もしません。

contentDocument

タブが現在表示しているHTMLドキュメント。タブが閉じられている場合、値はnullになります。

contentWindow

現在タブが表示しているWindow。(タブ内のWebページにとっては、これがウインドウとして認識されています)　タブが閉じている場合、値はnullになります。

favicon

タブが表示しているfaviconのURL文字列。タブがfaviconを持っていない場合や閉じられている場合、値はnullになります。

focus()

タブを選択状態にします。

isClosed

タブが閉じられているかどうかを示すbool値。これは例えば、タブオブジェクトを変数に入れて保持しておき、後でその値を利用する際に既に閉じられていないかを確認するような場合に使えます。

onFocus(callback)

Tabオブジェクトが選択状態になった際に、常に呼び出されるライブイベントをバインドします。
このバインダー関数は、Tabオブジェクトやjetpack.tabs配列上で利用できます。
ここでバインドされた関数は、現時点では引数を何も取りません。呼び出された際は、this変数で引き金になったTabオブジェクトにアクセスできます。
次のサンプルはjetpack.tabs.onFocusハンドラを使い、タブを切り替えた際には常に通知メッセージを表示するようにしています。

jetpack.tabs.onFocus(function() {
  jetpack.notifications.show("You selected " + this.url);
  });

onReady(callback)

“live event binder”は、タブオブジェクトのHTML文書もしくは、それが含むサブドキュメント（例えばiframeのような）のひとつのロードが終わった際に、このイベントを実行します。純粋に技術的な見地で言えば、このイベントはターゲットとなるドキュメントの DOMContentLoaded イベントにより実行されます。

このバインド用メソッドは、タブオブジェクトとjetpack.tabs配列で利用可能です。

次のサンプルコードはjetpack.tabs.onReadyハンドラを用いて、ユーザがページへ再訪した際に通知メッセージを表示できるようにしています。

jetpack.tabs.onReady(function onNextPage(doc) {
  if (!doc.defaultView.frameElement) {
    jetpack.notifications.show("Loaded " + doc.location.href);
    jetpack.tabs.onReady.unbind(onNextPage);
  }});

raw

XULのTabオブジェクトに直接アクセスします。このオブジェクトはMozillaプラットフォームでの変更を受けやすいので、アクセスは最終手段として極力使わないようにしてください。
タブが閉じている場合、値はnullになります。

url

タブが現在表示しているURL文字列。タブが閉じている場合、値はnullになります。

« Jetpack

[Jetpack] インストールと開発環境構築準備

mozilla labsから公開された、jQueryでFirefoxのExtensionを作れる拡張機能 “Jetpack” をいじってみる。

今まで、ちょっとしたExtensionを作るのもxulでやるのは良いとして、debugが非常にやりにくいのが難点でした。
その点、Jetpackは

• 書きなれたJavascript+jQueryで記述できる
• インラインで実行確認できるツールがある
• Firebugとの組み合わせでデバッグしやすい

ということで、ちょっと覚えておこうという気に。
まずは開発準備に環境を整えましょう。
Continue reading…

jQuery 自作プラグイン3 “Type-Writing Hint”

続けて3本目。jQuery Type-Writing Hintです。

こちらも、作者の方で紹介ページなど作る前にskuare.net様でご紹介いただいており、大変ありがたいのですが。

「ちょっとうざい」

ええ、自覚しておりますとも。
ちょっと新しいかなと思って作ってみたのですが、正直言って、スパム広告の一部みたいに見えたりします。
おかげさまでGoogleで「jQuery ちょっとうざい」と検索すれば一番に出てくるようになりました。
ま、それも味かなと思って、とりあえず並べておきます。

それなりに工夫している点もありまして、最たるものは、普通にJavascriptを操作しても入力ヒントが文字列とみなされないこと。
何も考えずにこのテのものを作ると、例えば

alert(text.value);

のように書いても、実際はユーザは何も入力していないのにヒント文字列が表示されてしまったりすることがあります。
# WordPressの管理画面にある「新規タグの追加」なんかもそうですね。黙って「追加」を押すと、「新規タグの追加」というタグが出来ます。
それがコイツは、ちゃんとヒント文は空文字として、手で入力した文字はそれとして、認識されます。
このプラグインを見たカナダの会社から仕事のオファーをいただいたり、なかなか頑張ってくれた子です。

jQuery 自作プラグイン2 “Spectrum”

その2といっても昔作ったものを持ってきている順番ってだけなんで、実際は何作目だったか。
しかしSpectrumは、その中でも割と気に入っているものです。

これは、ある要素から他の要素に向かってスペクトラム光線を飛ばすという…見てもらった方が早いと思います。
以前、このプラグインをtwitterで紹介してくれている人が居たのですが、彼曰く “kewl, but hard to explain” っちゅーことで。

この動きには元ネタがあり、実のところ昔からお気に入りのTiddlyWikiのインターフェースを再現したくて作ったものでした。
現在はバージョンアップしてこの動作も見られなくなってしまいましたが、昔の方がカッコよかったなと思います。
とはいえ、大筋のデザインはリリース当初と殆ど変わっていません。未だに風化した感じはせず、やはりセンスの良いデザインだなと。

ところでこのプラグイン、私の周囲では「スペクトラム」が呼びにくいのか、「シュパ」で通っています。
極めて個人的には何かシックリ来ないのですが、いかがでしょ。

jQuery Puffyの日本語ページ作成

オリジナルのjQueryプラグイン、「jQuery Puffy」の日本語ページを作ってみました。

パフッと画像が広がって見える、エフェクト系のプラグインです。

実は公開したのは4月で、githubが半自動で作ってくれるショボい英語ページは置いておいたのですが、やはり折角なので体裁を整えておこうかなと。

そうこうしているうちに、気がついたらskuare.netさんで先んじて紹介いただいていました。認知経路としては本家のプラグインリポジトリかgithubしか無いはずなんですが、目ざとい人が居るものですね。ありがとうございます。

このプラグインはjQuery UIが元々持っている「Puff」を使ったものだけに非常に簡単で、総制作時間は1時間もかかっていないと思います。
このページを作るほうがよっぽど大変でしたが、何かのお役にたてば。

他にも幾つか作ったもの/作りかけているもの/作ろうとしているものがあるので、今後はこのサイトを中心に公開していければと思っています。

偏頭痛で会社を休んでいる間の、ちょっとした作業でした。

Development

自作コード置き場。

jQuery Plugins

jQuery Puffy

パフッと画像が広がるjQueryプラグイン。

jQuery Effect Spectrum

要素から他の要素へ残像をシュパッと飛ばす。

jQuery Type-Writing Hint

タイプライター式にカタカタッと入力ヒントを表示する。

jQuery Spin

クリクリっと数値の変更がマウスで出来るスピンボタン入力インターフェース。