HTML5 のカスタムデータ属性を jQuery プラグインのオプションとして使う

HTML5 ではマークアップに カスタムデータ属性 を埋め込むことができますが、これを jQuery プラグインのオプションとして利用する方法について考えてみました。なお、ここでやっていることと同様のことが『jQuery クックブック』の「レシピ 12.7」に書かれていたので参考にしています。

まず、従来の典型的な jQuery プラグインでのオプションの扱い方は、オプションをオブジェクトとして定義し、そこに適切な適当なデフォルト値を与え、メソッド呼び出しの際に必要に応じて上書きする、というものです:

(function ($) {

  $.fn.myPlugin = function (options) {
  
    // デフォルトのオプションをメソッド呼び出し時の指定で上書き
    var opts = $.extend({}, $.fn.myPlugin.defaults, options);
    
    return this.each(function () {
      // 関数の本体
    });
  
  };
  
  // デフォルトのオプションを設定
  $.fn.myPlugin.defaults = {
    width:  160,
    speed:  'fast',
    repeat: true
  };

  $(function () {
  
    // メソッドの呼び出し時にオプションのうち 1 つを上書き
    $('.myClass').myPlugin({
      width: 320
    });
  
  });

})(jQuery);

$.extend() を使って空のオブジェクト ({}) をデフォルトオプションのオブジェクト ($.fn.myPlugin.defaults) で上書き (拡張) し、さらにメソッドを呼び出す際に引数 (options) で上書きできるようにしています。こうすることで、メソッド呼び出し時に必要なオプションだけを指定してあとはデフォルトのまま、といったことが可能です。上記の例ではメソッド呼び出し時にオプション width を上書きしているので、関数の中で opts.width320 という値に書き替えられています。

こういったプラグインに HTML5 のカスタムデータ属性を絡めるにはどうするか。具体的には、メソッドに渡すオプションとして、デフォルトを継承しつつ、メソッド呼び出し時に指定でき、さらにマークアップのカスタムデータ属性で上書きできるようにするにはどうすればいいか。

例として、Twitter の API を使って複数のアカウントそれぞれの Tweet を数件ずつを出力するようなプラグインを考えてみます。それにはオプションとして Twitter のアカウント名や表示件数を指定できることが必要になりますが、アカウント名はマークアップにカスタムデータ属性として埋め込み、表示件数はメソッド呼び出し時に指定できるようにしてみます:

(function ($) {

  $.fn.loadTweets = function (options) {
    
    // デフォルトのオプションをメソッド呼び出し時のオプションで上書き *1
    options = $.extend({}, $.fn.loadTweets.defaults, options);
    
    return this.each(function () {
      var $this = $(this);
      
      // メソッドを呼び出す要素ごとにカスタムデータ属性の値を取得 *2
      var customData = {
        screen_name: $this.data('twitter-screen-name'),
        count:       $this.data('twitter-count'),
        include_rts: $this.data('twitter-include-rts')
      };
      
      // *1 を *2 で上書き
      var opts = $.extend({}, options, customData);
      
    });
  
  };
  
  // デフォルトのオプションを設定
  $.fn.loadTweets.defaults = {
    count:       10,
    include_rts: true
  };
  
  $(function () {
  
    // クラス .tweets を持つ要素ごとに loadTweets() メソッドを呼び出し
    $('.tweets').loadTweets({
      count: 4
    });
  
  });
  
})(jQuery);
<!-- 各要素のカスタムデータ属性にオプションを指定 -->
<div class="tweets" data-twitter-screen-name="BarackObama"></div>
<div class="tweets" data-twitter-screen-name="DalaiLama"></div>

まずデフォルトのオプションをメソッド呼び出し時の引数に上書きし、さらに要素ごとにカスタムデータ属性の値で上書きしています。つまり同じオプション項目について、マークアップのカスタムデータ属性 → メソッド呼び出し時の引数 → デフォルト、という優先順位になるわけです。またメソッド呼び出し時の引数同様、カスタムデータ属性は必要な項目のみ指定することができます。

なお、上記のようにカスタムデータ属性の値を data() メソッドで取得できるのは jQuery 1.4.3 以降です。それ以前のバージョンの場合は $this.attr('data-twitter-screen-name') などとする必要があります。