Overlay (オーバーレイ)について

オーバーレイ(ライトボックス風)機能を実装するためのドキュメントです。

概要

一般的なセットアップの概要です

//jQueryセレクタにより任意の要素をトリガーとして選択
$(".my_overlay_trigger").overlay({
	// コンフィグ値を変更
	color: '#ccc',
	// 更にコンフィグ値を変更
	top: 50
});

トリガーをクリックした時、オーバーレイが開きrel属性に指定されていたターゲット要素を開きます。

コンフィグ値

コンフィグオプションで設定できる値です。

プロパティ デフォルト値 説明
close オーバーレイオブジェクト内の任意の画像やボタンに閉じる機能を実装できます。実装するためには任意のクラス名を指定します。
デフォルト値はnullです。nullが指定されているときはデフォルトの閉じるボタンが自動生成されます。
任意のクラス名が指定されているときは、自動生成されません。
closeOnClick true オーバーレイオブジェクトの外側をクリックしたときにオーバレイオブジェクトを閉じることを許可するか?を指定できます。
未許可にすることでモーダルなダイアログを作成したりすることも可能です。
closeOnEsc true キーボードの「ESC」ボタンで、オーバーレイオブジェクトを閉じるかの指定
effect 'default' オーバーレイが開く/閉じるときのエフェクト。プラグインの追加により新しいエフェクトを追加したり、自分好みにカスタマイズしたエフェクトを掛けることができます。 "default"ではシンプルな show/hide エフェクトのみです。
fixed true since 1.2.0
ページスクロールなどをしても、オーバーレイオブジェクトがページ内の同じポジションにとどまるようにします。
もしこの値をfalseにするとオーバーレイオブジェクトはドキュメントのその位置に留まりつづけます。
※IE6では、fixedの機能はサポートされません。
mask exposeと同じ機能を実装します。 オーバーレイではよく使われる、画面にマスクをかけ、オーバーレイオブジェクトのみに作業を集中させる機能です。
この項目のさらに詳細な内容は、「toolbox.expose」を参照してください
left "center" スクリーンの左端からの距離を設定します。centerの場合は画面の水平方向の中央に設定されます。
load false since 1.2.0
ページが読み込まれた直後にオーバーレイをしたい場合にtureを指定します。
oneInstance true trueの場合は、オーバレイオブジェクトを1つのみ許可します。複数存在するときは最後に呼ばれたもののみ残ります。
speed 'normal' オーバーレイがフェードイン/アウトするときの速度です。値はslowfast、または数値(ミリ秒)を指定します。
target トリガー要素に指定する属性値を変更できます。デフォルト値はrelになっています。
top '10%' スクリーンの上端からの距離を設定します。centerの場合は画面の垂直方向の中央に設定されます。

イベント

すべての第一引数にはイベントオブジェクトが入ります

イベント いつ動作するか?
onBeforeLoad overlayオブジェクト「が表示される前に動作します。overlayオブジェクトはすでに表示はされていませんが、表示のためのポジショニングを終えています。
onLoad overlayオブジェクトが完全に表示された時に
onBeforeClose overlayオブジェクトを閉じる前に
onClose overlayオブジェクトを閉じた後に

Scripting API

Method 返される型 説明
close() Overlay overlayオブジェクトを閉じる
getClosers() jQuery 閉じるボタン(要素)を取得します。
getConf() Object overlayオブジェクトのコンフィグレーションを取得します。
getOverlay() jQuery jQueryオブジェクトとして、オーバレイ要素を帰します。
getTrigger() jQuery jQueryオブジェクトとして、トリガーになる要素を返します。
isOpened() boolean overlayオブジェクトが開いていればtrueを返します。
load() Overlay overlayオブジェクトを開きます。

閉じるボタンのカスタム

標準の機能では、閉じるボタンは次のような形でコンテナ内に自動でHTMLが生成されます。

<!-- auto- generated close button -->
	<div class="close"></div>

cssのクラス名「close」を使うことで見た目や位置など自由にカスタマイズをすることができます。

もし、closeが既に定義されていた場合は、閉じるボタンは自動生成されません。

effectsのカスタマイズ

エフェクトをカスタマイズしたい時は、$.tools.overlay.addEffectメソッドを使います。
このメソッドを使うためには、overlay()よりも前に読み込まれている必要があります。

この第一引数はエフェクト名、第2引数には開くときの動作関数、第3引数には閉じる時の動作関数を指定します。

// カスタムエフェクト「 "myEffect"」を追加
$.tools.overlay.addEffect("myEffect", function(position, done) {
	/*
	 - フェードインするエフェクトのサンプルです
	*/
	this.getOverlay().css(position).fadeIn(this.getConf().speed, done);
},
// 閉じる時の動作
function(done) {
	// overlayをフェードアウトします
	this.getOverlay().fadeOut(this.getConf().closeSpeed, done);
}
);

※:jQuery animate/fadein/outメソッドを使うときは、 アニメーションの終了を管理するためdone.call() を最後の引数に指定します。