• まとめ:ThickBox の使い方 (記述例&Tips)

    ThickBox は画像や動画など任意のコンテンツをポップアップ表示する jQuery プラグイン。LightboxfancyBox などと並ぶ代表的な人気スクリプトの一つ。すでに開発は終了しているが、その汎用性の高さやシンプルさから未だに多くの Web サイトで使われている。

    ThickBox 3.1

    そんな ThickBox の使い方 (記述例や Tips など) を体系的にまとめてみた。開発が終了して久しい ThickBox に関する説明ページを、今更ながらに作成した理由は主に次の 3 つ。

    • Auto ThickBox Plus を開発している関係で ThickBox の情報をまとめる必要がでてきた
    • “thickbox” を含む検索キーでこのサイトにたどり着いてしまう人が非常に多い
    • 未だに多くの Web サイトやソフトウェア (WordPress など) で採用されている

    ※ 注:このページのデモで使われている thickbox.js はオリジナルの ThickBox ではなく Auto ThickBox Plus に含まれている改良版 ThickBox。そのためオリジナルの ThickBox とは挙動やデザインが一部異なる。

    目次

    概要

    ThickBox は jQuery ライブラリを使用した UI ダイアログウィジェット。様々なコンテンツをページ上にポップアップ表示 (ページ遷移なしでオーバーレイ表示) することができる。単一/複数の画像、インラインコンテンツ、iFrame コンテンツ、AJAX コンテンツをサポートしている。

    サムネイル画像をオリジナルサイズで手軽にポップアップ表示、というのが典型的な使い方。画像ファイルにリンクしたサムネイル画像をクリックすると、リンク先の画像がページ上にシンプルかつ軽快な効果でポップアップ表示される。

    特徴

    • jQuery ライブラリを使用
    • ThickBox の JavaScript コード (+ CSS ファイル) はわずか 10 KB
    • 単一/複数の画像、インラインコンテンツ、iFrame コンテンツ、AJAX コンテンツをサポート
    • ブラウザーウィンドウより大きな画像は自動的にリサイズされる
    • ThickBox ウィンドウは (ページスクロールやブラウザーリサイズをしても) 常に中央に表示される
    • 画像や背景 (オーバーレイ領域)、Close リンクをクリックするか ESC キーを押すと ThickBox ウィンドウが閉じられる
    • Lightbox 派生のほかのスクリプトと比較するとポップアップ効果がシンプルで動作が軽快 (アニメーション効果や装飾的なデザインがない)
    • a 要素 (リンク) や input 要素 (ボタンなど)、area 要素 (イメージマップ) から呼び出せる

    ダウンロード

    ThickBox は以下の 4 つのファイルから構成される。

    thickbox.js (thickbox-compressed.js)
    JavaScript コード。改変やデバッグをしない場合は圧縮版の thickbox-compressed.js がおすすめ。
    thickbox.css
    CSS ファイル。圧縮されていないので必要があれば圧縮する。
    loadingAnimation.gif
    画像読み込み中に表示されるローディング画像。プログレスバーのアニメーション GIF。
    macFFBgHack.png
    MacOS & Firefox 環境で Flash を隠すハックに使う塗りつぶし画像

    jQuery のダウンロード

    ThickBox は jQuery プラグインなので ThickBox を利用するには jQuery ライブラリが必要。

    jquery.js (jquery.min.js)
    jQuery ライブラリ。通常は圧縮版の jquery.min.js を使用する。

    CDN 上の jQuery を利用する場合は jQuery のダウンロードは不要。過去のバージョンは jQuery CDN から入手可能。

    ファイル構成

    Web サイトのディレクトリ構成に応じて ThickBox 関連ファイルを配置する。このページでは次のようなファイル構成を前提に説明する。

    www/
     +- js/
     |   +- jquery.js (jquery.min.js をリネーム)
     |   +- thickbox.js (thickbox-compressed.js をリネーム)
     +- css/
     |   +- thickbox.css
     |   +- macFFBgHack.png
     +- images/
         +- loadingAnimation.gif
    

    使い方

    ※ WordPress で Auto ThickBox Plus を利用する場合は、ここの手順 (jQuery や ThickBox の読み込み) は不要。プラグインをインストールして有効にするだけで OK。

    head 要素内に次のような script 要素を記述して jQuery と ThickBox の JavaScript コードを読み込む。jQuery のコードを前に記述して先に読み込まれるようにする必要がある。

    <script type="text/javascript" src="js/jquery.js"></script>
    <script type="text/javascript" src="js/thickbox.js"></script>
    

    head 要素内に次のような link 要素を記述して ThickBox の CSS ファイルを読み込む。

    <link rel="stylesheet" href="css/thickbox.css" type="text/css" />
    

    ※ loadingAnimation.gif を別の場所に配置した場合は thickbox.js の以下のコードを修正する。

    var tb_pathToImage = "images/loadingAnimation.gif";
    

    ※ macFFBgHack.png を別の場所に配置した場合は thickbox.css の以下のコードを修正する。

    .TB_overlayMacFFBGHack {background: url(macFFBgHack.png) repeat;}
    

    CDN 上の jQuery を読み込む

    jQuery では次のような CDN サービスを利用することができる。CDN 上の jQuery を読み込むため jQuery をダウンロードして自分のサイトに配置する必要はない。CDN を利用するほかの Web サイトとスクリプトが共有されるため、パフォーマンス向上などのメリットがある。

    jQuery CDN
    <script type="text/javascript" src="http://code.jquery.com/jquery-1.7.2.min.js"></script>
    
    Google Libraries API
    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
    
    Microsoft Ajax CDN
    <script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js"></script>
    

    記述例

    基本的には ThickBox を適用したい要素に “thickbox” クラスを指定するだけ。具体的には以下の要素に class="thickbox" 属性を指定する。

    • a 要素 (リンク) – href 属性で URL を指定
    • input 要素 (ボタンなど) – alt 属性で URL を指定
    • area 要素 (イメージマップ) – href 属性で URL を指定

    Auto ThickBox Plus では次のようなリンクに自動的に ThickBox が適用される。明示的に class="thickbox" を記述する必要はない。詳しくは Auto ThickBox Plus の使い方を参照。

    • 画像ファイルへのリンク (WordPress ギャラリー含む)
    • “TB_iframe” や “#TB_inline” を含む URL へのリンク

    単一画像

    一番シンプルな ThickBox の使い方。

    ソースコード

    画像ファイルへのリンクを記述して “thickbox” クラス (class="thickbox") を指定する。

    <a href="image.jpg" class="thickbox">
        <img src="image_s.jpg" alt="Image" />
    </a>
    
    <a href="image.jpg" class="thickbox" title="Image">Image</a>
    

    ※ 画像のキャプションは a 要素の title 属性や img 要素の alt 属性で指定する。

    デモ

    Image
    Image

    ※ リンクをクリックすると、リンク先の画像が現在表示されているページ上にポップアップ表示される。ThickBox ウィンドウを閉じるには画像や背景、Close リンクをクリックするか ESC キーを押す。

    複数の関連する画像をまとめて表示したい場合に便利。

    ソースコード

    画像ファイルへの複数のリンクを記述して “thickbox” クラス (class="thickbox") を指定する。各 a 要素の rel 属性に共通の値 (ギャラリー ID) を指定する。

    <a href="image1.jpg" class="thickbox" rel="gallery-foo">
        <img src="image1_s.jpg" alt="Image1" />
    </a>
    <a href="image2.jpg" class="thickbox" rel="gallery-foo">
        <img src="image2_s.jpg" alt="Image2" />
    </a>
    
    <a href="image3.jpg" class="thickbox" rel="gallery-foo" title="Image3">Image3</a>,
    <a href="image4.jpg" class="thickbox" rel="gallery-foo" title="Image4">Image4</a>
    

    ※ 画像のキャプションは a 要素の title 属性や img 要素の alt 属性で指定する。ギャラリー画像ではナビゲーション機能により、ギャラリー内の前/次の画像に切り替えることができる。異なるギャラリー ID を指定すると別のギャラリーとして認識される。

    デモ

    Image1
    Image2
    Image3,
    Image4

    ※ Prev/Next リンクをクリックするか < / > キーを押すと前/次の画像に切り替わる。

    インラインコンテンツ

    ページ内のコンテンツ (インラインコンテンツ) を ThickBox ウィンドウ内に表示する。非表示コンテンツでも構わない。

    ソースコード

    ThickBox で表示するインラインコンテンツを記述してインライン ID (id 要素) を指定する。インラインコンテンツは非表示 (display:none or visibility:hidden) にしても構わない。

    <div id="foo" style="display:none">
        <p>Inline Contents</p>
    </div>
    

    インラインコンテンツへのページ内リンク (href="#TB_inline") を記述して “thickbox” クラス (class="thickbox") を指定する。URL の inlineId パラメータでインライン ID を指定する。

    <a href="#TB_inline?inlineId=foo" class="thickbox" title="bar">Inline</a>
    

    ※ ThickBox ウィンドウのタイトルは a 要素の title 属性で指定する。

    width/height パラメータで ThickBox ウィンドウのサイズを指定できる (デフォルトは 630×440)。十分なサイズがない場合はスクロールバーが表示される。modal=true を指定すると ThickBox ウィンドウがタイトルバーのないモーダルダイアログとなる。ウィンドウを閉じるには tb_remove() 関数を呼び出す必要がある。

    <a href="#TB_inline?inlineId=foo&width=600&height=400&modal=true" class="thickbox">Inline</a>
    

    ※ 注:インライン ID を指定した要素の子要素がインラインコンテンツとして認識される。従って次のようにコンテンツがほかの要素で囲まれていない場合は認識されない。

    <div id="foo">Inline Contents</div>
    
    デモ

    ※ 以下はデモから参照されるインラインコンテンツ。ThickBox でインラインコンテンツを表示している間、そのコンテンツはページ上から削除される

    p 要素で囲まれたテキスト

    要素で囲まれていないテキスト

    div 要素で囲まれたテキスト

    span 要素で囲まれたテキスト


    (非表示コンテンツ)


    (非表示コンテンツ)


    Sample Image

    Inline content on the page, either hidden or showing, can be placed in a ThickBox.


    iFrame コンテンツ

    内部/外部のコンテンツを ThickBox ウィンドウ内の iframe 要素内に開く。

    ソースコード

    内部/外部コンテンツへのリンクを記述して “thickbox” クラス (class="thickbox") を指定する。URL に TB_iframe パラメータを指定して iFrame コンテンツとして認識させる。

    <a href="http://example.com/?TB_iframe" class="thickbox" title="foo">iFrame</a>
    

    ※ ThickBox ウィンドウのタイトルは a 要素の title 属性で指定する。公式サイトなどでは TB_iframe=true が指定されているが実際には TB_iframe パラメータの値はチェックされない。従って TB_iframeTB_iframe=false なども iFrame コンテンツとして認識される。

    width/height パラメータで ThickBox ウィンドウのサイズを指定できる (デフォルトは 630×440)。十分なサイズがない場合はスクロールバーが表示される。modal=true を指定すると ThickBox ウィンドウがタイトルバーのないモーダルダイアログとなる。ウィンドウを閉じるには tb_remove() 関数 (iframe 内からは self.parent.tb_remove()) を呼び出す必要がある。

    <a href="http://example.com/?TB_iframe&width=600&height=400&modal=true" class="thickbox">iFrame</a>
    

    “TB_iframe” より前にあるパラメータはそのまま URL に渡される。例えば次のような URL の場合は “http://example.com/?KeepThis=true” が開かれる。

    <a href="http://example.com/?KeepThis=true&TB_iframe" class="thickbox">iFrame</a>
    

    ※ ThickBox を利用しているサイトで KeepThis=true を指定しているコードを見かけるが、これはサンプルパラメータなので実際に使用するものではない。KeepThis=true は「”TB_iframe” より前にあるこのパラメータは保持される」ということを示しているに過ぎない。

    デモ

    AJAX コンテンツ

    同じドメイン上のコンテンツ (内部コンテンツ) を ThickBox ウィンドウ内に表示する。

    ソースコード

    内部コンテンツへのリンクを記述して “thickbox” クラス (class="thickbox") を指定する。

    <a href="file.html" class="thickbox" title="foo">HTML</a>
    <a href="file.php?bar=baz" class="thickbox" title="foo">PHP</a>
    

    ※ ThickBox ウィンドウのタイトルは a 要素の title 属性で指定する。

    width/height パラメータで ThickBox ウィンドウのサイズを指定できる (デフォルトは 630×440)。十分なサイズがない場合はスクロールバーが表示される。modal=true を指定すると ThickBox ウィンドウがタイトルバーのないモーダルダイアログとなる。ウィンドウを閉じるには tb_remove() 関数を呼び出す必要がある。

    <a href="file.html?width=600&height=400&modal=true" class="thickbox">AJAX</a>
    

    ※ 注:AJAX コンテンツでは内部コンテンツが現在のページに挿入されるため、次の項目に注意する必要がある。

    • 内部コンテンツにおける相対パスの基点が変更される
    • 内部コンテンツのスタイル (CSS) が現在のページにも適用される

    ※ 内部コンテンツを AJAX コンテンツではなく iFrame コンテンツとして開きたい場合は TB_iframe パラメータを指定する。

    <a href="file.html?TB_iframe" class="thickbox" title="foo">HTML</a>
    <a href="file.php?bar=baz&TB_iframe" class="thickbox" title="foo">PHP</a>
    
    デモ

    Tips

    自動的に画像をリサイズしない

    ThickBox では Web ブラウザーのウィンドウサイズより大きな画像は自動的にリサイズされる。縦横比は維持されるため横長/縦長の画像であっても適切な幅/高さに調整される。

    ThickBox の自動リサイズ機能を無効にするには thickbox.js の以下のコード (赤い部分) を削除 (またはコメントアウト) する。

    // Resizing large images - orginal by Christian Montoya edited by me.
    - var pagesize = tb_getPageSize();
    - var x = pagesize[0] - 150;
    - var y = pagesize[1] - 150;
      var imageWidth = imgPreloader.width;
      var imageHeight = imgPreloader.height;
    - if (imageWidth > x) {
    - 	imageHeight = imageHeight * (x / imageWidth); 
    - 	imageWidth = x; 
    - 	if (imageHeight > y) { 
    - 		imageWidth = imageWidth * (y / imageHeight); 
    - 		imageHeight = y; 
    - 	}
    - } else if (imageHeight > y) { 
    - 	imageWidth = imageWidth * (y / imageHeight); 
    - 	imageHeight = y; 
    - 	if (imageWidth > x) { 
    - 		imageHeight = imageHeight * (x / imageWidth); 
    - 		imageWidth = x;
    - 	}
    - }
    // End Resizing
    

    Auto ThickBox Plus を利用している場合は [自動リサイズ – 有効] オプションのチェックを外す。thickbox.js のコード改変は不要。

    ボタンから ThickBox を呼び出す

    リンク (a 要素) だけでなくボタン (input 要素) やイメージマップ (area 要素) からも ThickBox を呼び出せる。URL は input 要素は alt 属性で、area 要素は href 属性で指定する。

    <input type="button" alt="image.jpg" class="thickbox" title="Image" value="Image" />
    

    ※ 画像のキャプションや ThickBox ウィンドウのタイトルは input/area 要素の title 属性で指定する。

    ThickBox から ThickBox を呼び出す

    インラインコンテンツや AJAX コンテンツでは ThickBox ウィンドウ内のコンテンツから ThickBox を呼び出せる。通常通り ThickBox を呼び出す場合と同様にコンテンツ内の要素に “thickbox” クラス (class="thickbox") を指定する。

    ※ ThickBox 呼び出し時に ThickBox ウィンドウのサイズが変わらないようにするには、同じ値の width/height パラメータを指定する必要がある。

    メディアファイルを表示する (PDF, Text, QuickTime, MPEG, Flash, Shockwave, etc.)

    メディアファイルは iFrame コンテンツとして表示できる。(TB_iframe パラメータを指定する)

    <a href="file.pdf?TB_iframe" class="thickbox">Adobe PDF</a>
    <a href="file.txt?TB_iframe" class="thickbox">Plain Text</a>
    <a href="file.mov?TB_iframe" class="thickbox">QuickTime Movie</a>
    <a href="file.mpg?TB_iframe" class="thickbox">MPEG</a>
    <a href="file.swf?TB_iframe" class="thickbox">Adobe Flash</a>
    <a href="file.dcr?TB_iframe" class="thickbox">Adobe Shockwave</a>
    

    ただし使用する OS や Web ブラウザーの種類、インストールされているアプリケーションやプラグインなどによって ThickBox でサポートされるファイル形式は異なる。

    ドキュメント
    動画
    アプリケーション

    ※ 例えば次のようなアプリケーション (プラグイン) をインストールすると、それに対応するファイル形式が ThickBox でサポートされるようになる。

    ※ ファイルを直接指定しても ThickBox で表示できない場合は object (applet/embed/video) タグでファイルをページに埋め込み、それをインライン/iFrame コンテンツとして開く必要がある。(FLV, ASF, AVI, WMV, RM, Silverlight, Java など)

    Web サービスを表示する (Google Maps, Google Docs, Evernote, Flickr, Picasa, SkyDrive, YouTube, ニコニコ動画, etc.)

    Web サービスは iFrame コンテンツとして表示できる。(TB_iframe パラメータを指定する)

    <a href="http://maps.google.com/maps?ll=51.477222,0&output=embed&TB_iframe" class="thickbox">Google Maps</a>
    <a href="https://docs.google.com/document/pub?id=XXX&embedded=true&TB_iframe" class="thickbox">Google Docs</a>
    <a href="https://docs.google.com/spreadsheet/pub?key=XXX&widget=true&TB_iframe" class="thickbox">Google Spreadsheets</a>
    <a href="https://www.evernote.com/shard/s23/sh/XXX/YYY?TB_iframe" class="thickbox">Evernote</a>
    <a href="http://farm5.staticflickr.com/4051/4386822005_c434921844.jpg" class="thickbox">Flickr (Image)</a>
    <a href="https://picasaweb.google.com/lh/photo/XXX?feat=embedwebsite&TB_iframe" class="thickbox">Picasa Web Albums</a>
    <a href="https://lh4.googleusercontent.com/XXX/YYY/ZZZ/image.png" class="thickbox">Picasa Web Albums (Image)</a>
    <a href="https://skydrive.live.com/embed?resid=XXX&TB_iframe" class="thickbox">SkyDrive</a>
    <a href="http://youtube.com/embed/K-Rs6YEZAt8?TB_iframe" class="thickbox">YouTube</a>
    <a href="http://player.vimeo.com/video/12297655?TB_iframe" class="thickbox">Vimeo</a>
    <a href="http://dailymotion.com/embed/video/xninjh?TB_iframe" class="thickbox">DailyMotion</a>
    

    Web サービスが提供する埋め込み URL を指定する。URL に既存のパラメータがある場合は ?TB_iframe ではなく &TB_iframe を付与する。Web サービス側が iframe 内の表示をサポート (許可) していない場合は利用不可。

    地図
    ドキュメント
    画像
    動画

    ※ ニコニコ動画は埋め込み URL ではなく埋め込みスクリプトを提供する。そのため埋め込みスクリプトで外部プレイヤーをページに埋め込み、それをインライン/iFrame コンテンツとして開く必要がある。

    短縮 URL を指定する

    Web サービスが生成する短縮 URL (http://g.co/maps/jks8u や http://youtu.be/K-Rs6YEZAt8 など) は埋め込み URL ではないため iFrame コンテンツとして表示できない。ThickBox で短縮 URL を指定する場合は bit.lygoo.gl などの URL 短縮サービスを利用して埋め込み URL を短縮する必要がある。

    Flash が最前面に表示される

    ページに設置されている Flash コンテンツが ThickBox ウィンドウより前面に表示されてしまう場合の対策。

    Flash コンテンツはデフォルトでは HTML 要素とは別の最前面のレイヤーに配置されるため HTML 要素の順序 (z-index) は無視される。Flash コンテンツを HTML 要素と同一のレイヤーに配置するには Flash コンテンツの背景を透明/不透明にする必要がある。

    Flash コンテンツを object タグで埋め込んでいる場合は object タグに wmode パラメータを、embed タグに wmode 属性を指定する (値は transparent または opaque)。その他の場合は URL や JavaScript で wmode パラメータを指定する。

    <object ...>
        <param name="wmode" value="transparent" />
        <embed src="..." wmode="transparent" />
    </object>
    

    ※ Flash コンテンツの背景を透明/不透明にすると、一部の環境で日本語入力ができなくなる問題がある。新しいバージョンの Web ブラウザーや Flash Player では改善されているが完全ではない。

    ページ URL に ‘?’ が含まれていると正しく動作しない

    ThickBox でインラインコンテンツを表示する際に、ページ URL に ‘?’ が含まれていると正しく動作しない。これは ‘?’ が 2 つ含まれている不正な URL となり最初のパラメータ (inlineId) が無視されるためである。

    • http://example.com/page.php?foo=bar#TB_inline?inlineId=id

    この問題を解決するには tb_parseQuery() 関数の先頭に次のようなコードを追加する。

    query = query.substring(query.indexOf('?') + 1);
    

    対応する画像形式を追加する (WebP, TIFF, etc.)

    ThickBox がサポートする画像形式は JPEG (.jpg, .jpeg), PNG (.png), GIF (.gif), BMP (.bmp) の 4 種類。新たな画像形式に対応させるには thickbox.js を修正する必要がある。例えば WebP 形式と TIFF 形式に対応させる場合は thickbox.js を次のように修正する。

    - var urlString = /\.jpg$|\.jpeg$|\.png$|\.gif$|\.bmp$/;
    + var urlString = /\.jpg$|\.jpeg$|\.png$|\.gif$|\.bmp$|\.webp$|\.tif$|\.tiff$/;
      var urlType = baseURL.toLowerCase().match(urlString);
      
    - if(urlType == '.jpg' || urlType == '.jpeg' || urlType == '.png' || urlType == '.gif' || urlType == '.bmp'){//code to show images
    + if(urlType == '.jpg' || urlType == '.jpeg' || urlType == '.png' || urlType == '.gif' || urlType == '.bmp' || urlType == '.webp' || urlType == '.tif' || urlType == '.tiff'){//code to show images
    

    JPEG/PNG/GIF 形式はほとんどの Web ブラウザーでネイティブサポートされているが、その他の画像形式は使用する OS や Web ブラウザーの種類、インストールされているアプリケーションやプラグインなどによって対応状況が異なる。

    • BMP (Windows 環境の Web ブラウザー)
    • WebP (Google Chrome, Opera)
    • TIFF (Internet Explorer 9 以降, Safari)
    Post Tagged with

One Responseso far.

コメントを残す

メールアドレスが公開されることはありません。