jQuery ColorBox を フォーム入力用にカスタマイズした Ex Colorbox Form
更新履歴
- 2011-10-20
- Ver 0.1.3
Ver 0.1.2の fastIframe パラメータ関連の不具合を修正しました。fastIframe パラメータ未定義の旧 colorbox にも対応してます。 - 2011-10-13
- Ver 0.1.2
ColorBox1.3.18に対応しました。 - 2011-10-08
- Ver 0.1.1
jQuery1.6.4に対応しました。
LightBox 系プラグイン の中でも人気の高い jQuery ColorBox をフォームの入力画面用にカスタマイズしてみました。仕事柄、画像の表示を主目的とする LightBox 系のプラグインを使用することはあまりないのですが、iframe に対応してるものも多く、登録系の画面が主となる業務アプリでも使えそうだなぁと思い ColorBox をベースにちょっと作ってみました。(ちなみにオリジナル の colorbox のソースはいじってません)
POST で画面を遷移してくような画面でのブクマを抑止でき、登録完了後の親画面へのコールバック処理等もできるので、手軽な割には結構便利かとな思ってます。
機能概要
jQuery ColorBox をフォームの入力画面向きに使用することができます。
使い方
jquery.js、colorbox.css、jquery.colorbox.js、jquery.excolorboxform.js を読み込みます。
<link rel="stylesheet" type="text/css" href="colorbox.css"/> <script type="text/javascript" src="../jquery.js"></script> <script type="text/javascript" src="../jquery.colorbox.js"></script> <script type="text/javascript" src="../jquery.excolorboxform.js"></script>
a、form、submit ボタンのいずれかに対し、exColorboxForm() メソッドを実行します。
jQuery(function($){ $('a').exColorboxForm(); //又は $('form').exColorboxForm(); //又は $('input[type=submit]').exColorboxForm(); });
ColorBox では5種類のデザインが用意されており、Ex Colorbox Form でもそれぞれに対応してます。
閉じるアイコンの位置
ColorBox の[A][D][E]デザインでは、閉じるアイコンがボックスの右下に配置されてますが、[A][D]についてのみ右上に配置されるよう調整されます。([E]はデザインが崩れてしまうのでそのままにしてます) これは Windows アプリケーションでは右上の閉じるアイコンが常識のため、右下に地味に配置されたアイコンが見つけずらいとの意見を受け、このようにしてます。
オリジナルのように右下に配置したい場合は、closeIconTopPosition パラメータに false を指定して実行します。
$('a').exColorboxForm({closeIconTopPosition:false});
フォーム画面内での閉じるボタン
通常、ウィンドウを閉じるには、前述の閉じるアイコンをクリックする必要がありますが、登録処理の完了後にウィンドウの画面内に閉じるボタンを配置したい場合があるかと思います。以下のように colorbox-close クラスを割り当てたボタンを配置することで、ウィンドウを閉じることができるようになります。
<button class="colorbox-close">閉じる</button>
closeButtonClass パラメータでクラス名を変更することができます。
ウィンドウ高さの伸縮
フォーム画面のコンテンツサイズに合わせウィンドウの高さが伸縮します。コンテンツサイズが親画面のウィンドウサイズを超える場合は、親画面のウィンドウと同じ高さになり、スクロールバーが表示されます。
fitContentsHeight パラメータに false を指定すると、サイズ調整は行われません。
閉じるアイコンクリック時の確認メッセージ
以下のように記述すると、閉じるアイコンクリックした際、実行確認メッセージを表示することができます。
$('a').exColorboxForm({ onLoad : function(api){ api.getCloseIcon().click(function(){ return confirm('画面を閉じてよろしいですか?'); }); } });
onLoad コールバックにて、API オブジェクトを受け取り、getCloseIcon() メソッドで取得した閉じるアイコンに対し、クリックイベントを割り当てています。クリックイベントの返却値を false にすることで、閉じる処理をキャンセルできます。
API オブジェクトは他のコールバック関数(onComplete や onClosed など)でも同様の方法で取得できます
上記の記述により、colorbox-close クラスを割り当てた閉じるボタンをクリックした場合も、同様に確認メッセージが表示されます。これを抑止した場合は、closeButtonSyncCloseIcon パラメータに false を指定します。
確認メッセージに jQuery Alert Dialogs を使用する
正確には jQuery Alert Dialogs をカスタマイズした Ex Alerts Dialogs を使用します。
$('a').exColorboxForm({ onLoad : function(api){ api.getCloseIcon().exJConfirm('画面を閉じてよろしいですか?','終了確認'); } });
先程と同様に、getCloseIcon() メソッドで取得した閉じるアイコンに exJConfirm() メソッドを割り当てます。
最後の画面では閉じる確認を表示しないようにする
入力途中で閉じようとした場合のみ確認メッセージを表示するようにしてみます。
var jconAPI; $('a').exColorboxForm({ onLoad : function(api){ jconAPI = api.getCloseIcon().exJConfirm('登録は完了してません。\n画面を閉じてよろしいですか?','終了確認',{ api : true }); }, onComplete : function(api){ var isLastPage = !!api.getContents().find('.colorbox-close').size(); jconAPI.disabled(isLastPage); } });
exJConfirm() メソッド実行時、api パラメータを true にし Alert Dialogs の API オブジェクトを取得しておき、Colorbox のフォームの表示が完了後に起動される onComplete コールバックにて、最終画面か否かを判断し(ここでは閉じるボタンの有無で判定)、Alert Dialogs の disabled() メソッドにて確認メッセージの表示を抑止しています。
ちなみに onComplete 内の getContents() メソッドでは iframe 内のドキュメントが取得できます。iframe 関係のアクセスについてはこちらを参照ください。
登録開始時に確認メッセージを表示する
登録を開始したタイミングでDBの更新処理を行うようなケースでは、登録開始の確認メッセージが必要になるかと思います。そのような場合は以下のように記述します。
var jconAPI; var option = { onLoad : function(api){ jconAPI = api.getCloseIcon().exJConfirm('登録は完了してません。\n画面を閉じてよろしいですか?','終了確認',{ api : true }); }, onComplete : function(api){ var isLastPage = !!api.getContents().find('.colorbox-close').size(); jconAPI.disabled(isLastPage); } } $('a').exJConfirm('登録を開始しますか?','開始確認') .exColorboxForm(option); $($('input[type=submit]').exJConfirm('登録を開始しますか?','開始確認').attr('form')) .exColorboxForm(option); $('form').exColorboxForm(option) .find('input[type=submit]').exJConfirm('登録を開始しますか?','開始確認');
これまでと異なり、プラグインを適用する要素の種類によって書き方が異なります。(exColorboxForm のパラメータ指定は別定義にしてますが、先程までの例と同じ内容です)
まず適用対象が a 要素の場合ですが、単純に exJConfirm() と exColorboxForm() をメソッドチェーンでつなげて実行すればOKです。
それ以外の場合は、ColorBox の呼び出しのトリガーとなるボタンに対し exJConfirm() メソッド、form に対し exColorboxForm() メソッドを適用する必要があります。
登録が完了したら親画面を更新する
登録が完了した事により、親画面に表示された情報を最新にするというケースはよくあると思います。単純な方法として location.reload() でページを更新しても良いですが、スクロールが発生する親画面などの場合は、Ajax で部分更新っていうのもありがちかと思います。ここでは単純に登録開始のボタンを登録完了メッセージに置換してみます。
var jconAPI,isLastPage = false; var option = { onLoad : function(api){ jconAPI = api.getCloseIcon().exJConfirm('登録は完了してません。\n画面を閉じてよろしいですか?','終了確認',{ api : true }); }, onComplete : function(api){ isLastPage = !!api.getContents().find('.colorbox-close').size(); jconAPI.disabled(isLastPage); }, onClosed : function(api){ if (isLastPage) { api.getTarget().replaceWith('<p>登録完了</p>'); } } }
プラグイン適用の記述は先程と同じなので省略しています。ColorBox が閉じた時に実行される onClosed コールバックにて最終ページに遷移した状態で画面を閉じたか判定します。この判定結果を保持するため isLastPage 変数の定義を外だしにしてます。
最終ページまで遷移されたと判定した場合は getTarget() メソッドにより exColorboxForm() メソッドを適用した要素を取得し、replaceWidth() にて登録完了メッセージに置換してます。
パラメータ
基本、ColorBox のパラメータを指定できますが、一部初期値を上書きし、独自パラメータも追加されてます。
- fitContentsHeight
- 初期値 : true
ColorBox 内のコンテンツがリロードされる度、ColorBox の高さを調整します。 - adjustContentsBackgroundColor
- 初期値 : #fff
デザイン[B][C]を適用した際、呼び出し先のコンテンツの背景色が transparent の場合、黒で塗りつぶされてしまうのを指定色で抑止します。 - contentsMargin
- 初期値 : 32
コンテンツに対する高さの margin を指定できます。 - closeIconTopPosition
- 初期値 : true
デザイン[B][D]において、閉じるアイコンを ColorBox の右上に配置します。 - closeIconTopMargin
- 初期値 : true
デザイン[B][D]において、closeIconTopPosition が true の場合、閉じるアイコンとコンテンツの間の margin を指定できます。 - closeButtonClass
- 初期値 : ".colorbox-close"
コンテンツ内に指定クラス名を割り振ったボタン要素を配置すると、ColorBox の閉じるボタンにすることができます。 - closeButtonSyncCloseIcon
- 初期値 : true
closeButtonClass パラメータで指定したクラス名を持つボタンをクリック時、閉じるアイコンのクリックイベントを起動します。 - close
- 初期値 : "[X]"
デザイン[D]の閉じるアイコンのテキストを指定できます。 - overlayClose
- 初期値 : false
true の場合、ColorBox 枠の外側をクリック時、ColorBox が閉じます。 - escKey
- 初期値 : false
true の場合、ESC キー入力時、ColorBox が閉じます。 - width
- 初期値 : "750px"
ColorBox の幅を指定できます。 - height
- 初期値 : "80%"
ColorBox の高さを指定できます。fitContentsHeight が true の場合はコンテンツロード時に調整されます。 - show
- 初期値 : false
プラグイン適用時に、ColorBox の表示を行います。
API
API オブジェクトを使用し、以下メソッドを使用することができます。API オブジェクトは onClosed 等のコールバック関数の第一引数に引き渡されます。
- getTarget()
- プラグインを適用した要素を取得できます。
- getContents()
- コンテンツを取得することができます。(iframe.contents())
- getCloseIcon()
- 閉じるアイコンを取得することができます。
- getFrame()
- コンテンツを表示してる iframe 要素を取得することができます。
- show()
- ColorBox を表示することができます。