グローバル設定

jQuery Mobileにおける自動初期化処理

jQueryやjQuery UIのような他のjQueryプロジェクトと異なり、jQuery Mobileはロードされると同時(document.readyイベントが発生するよりもずっと前)に沢山のマークアップ操作を行います。これらの埋め込みは、jQuery Mobileが用意している一般的なデザインにあわせた初期設定値に従うことになります。しかし、それはあなたの要望通りで無い部分もあるでしょう。幸いにして、そうした初期値は簡単に再設定することができます。

mobileinit イベント

jQuery Mobileが実行されると、まず document オブジェクトの mobileinit イベントが呼び出されます。ここで、jQuery Mobileの初期設置値を上書きすることが出来ます。

$(document).bind("mobileinit", function(){
  // 初期値の上書き
});

jQuery Mobileがロードされた直後にこのハンドラはバインドされる必要があるため、この mobileinit イベントは実行された直後に呼び出されます。そのため、JavaScriptファイルの取り込みは次のような順番で行うことをお勧めします。

<script src="jquery.js"></script>
<script src="custom-scripting.js"></script>
<script src="jquery-mobile.js"></script>

このイベント中で、初期値を次のいずれかの方法で設定できます。
まず $.mobile オブジェクトをjQueryの $.extend メソッドを使って拡張する方法があります。

$(document).bind("mobileinit", function(){
  $.extend( $.mobile, {
    foo:bar
  });
});

あるいは、各設定値をそれぞれ変えることも出来ます。

$(document).bind("mobileinit", function(){
  $.mobile.foo = bar;
});

グローバル設定変更による簡単なプレビューを見るには、この グローバル設定テスト を試してください。

設定可能オプション

以下の設定は $.mobile オブジェクトにより設定可能です。

activeBtnClass string, default: "ui-btn-active"

CSSフレームワーク向けの、ボタンがアクティブ状態になった際に適用されるクラスです。

activePageClass string, default: "ui-page-active"

ページ遷移によりアクティブになったページに適用されるクラスです。

ajaxEnabled boolean, default: true

jQuery Mobileは自動的にリンクのクリックやフォームのサブミット処理をAjaxで制御するようになります。ここに false を指定すると、その制御を止めます。結果、URLはハッシュベースではなく通常のHTTPリクエストによるものになります。

allowCrossDomainPages boolean, default: false

jQuery Mobileが外部ページをロードしようとする場合、リクエストは $.mobile.loadPage() を通じて行われます。この時、この $.moible.allowCrossDomainPages に true が指定されている場合に限り、クロスドメインでのリクエストが許可されます。なぜならjQuery Mobileは閲覧中のページをブラウザのロケーションハッシュを使って操作しており、クロスドメインURLによりXSS攻撃の対象になる危険性を孕んでいるためです。そのため $.mobile.allowCrossDomainPages の初期設定は false になっています。PhoneGapアプリの場合、必ず "phone home" がロード時に必要になるため、 $.support.cors と $.mobile.allowCrossDomainPages は、共に true に設定しなければなりません。

autoInitializePage boolean, default: true

DOMの準備が整うと、フレームワークは自動的に $.mobile.initializePage を呼び出します。この値が false の場合、ページは初期化を行いません。そして手動で $.mobile.initializePage メソッドが呼ばれるまで、ページには何も表示されません。

buttonMarkup.hoverDelay integer, default: 200

タッチデバイスで hover 状態を表現することが出来るようになります。このディレイを減らすことによって、より反応の良いUIにすることが出来ますが、ページをスクロールさせようとした際にもボタンが押されてしまうなどの事故も起きやすくなります。

defaultDialogTransition string, default: 'pop'

Ajaxによるダイアログ表示時のデフォルト効果を指定します。ここに "none" を指定すると、デフォルトで何も効果が無い状態になります。

defaultPageTransition string, default: 'slide'

Ajaxによるページ遷移時のデフォルト効果を指定します。ここに "none" を指定すると、デフォルトで何も効果が無い状態になります。

gradeA function that returns a boolean, default: a function returning the value of $.support.mediaquery

グレードAの機能をサポートしているかどうかを返します。

hashListeningEnabled boolean, default: true

jQuery Mobileは自動的に location.hash の変更を見張り、制御します。この値を false にすると、jQuery Mobileはハッシュ変更時の制御を止めます。それにより、制御を自分自身で行ったり、あるいはディープリンクをそのままにして指定したIDへ自動スクロールさせるようなことが出来ます。

linkBindingEnabled boolean, default: true

jQuery Mobileは、自動的にアンカー要素のクリックイベントをバインドします。このオプションに false を指定すると、こうしたバインドを全て止めます。これには、ボタンにアクティブな状態を与えるような処理も全て含みます。これを false にするのは、アンカーのクリックを他のライブラリなどで独自に制御したいような場合に限るでしょう。

loadingMessage string, default: "loading"

ページ読み込み時に表示されるローディングメッセージの文字列を設定します。ここに false を指定すると、メッセージ自体が表示されなくなります。

loadingMessageTextVisible boolean, default: false

ローディングメッセージ表示時に、テキストを表示するかどうかを指定します。エラー時は、常にテキストは表示されます。

loadingMessageTheme string, default: "a"

ローディングメッセージに適用されるテーマを指定します。

minScrollBack string, default: 150

ページを「戻る」などで戻った時に、元のスクロール位置を覚えておくかどうかの閾値です。このピクセル数以上スクロールすると、その位置を復元するようになります。

ns string, default: ""

名前空間は、たとえば data-role のような data- で始まる属性に用いられます。ブランクの指定も可能で、それが初期値になっています。値を設定する場合、末尾にダッシュ(-)を付けるのが良いでしょう。たとえば "mynamespace-" を指定すれば、data-fooという属性は次のようになります。 data-mynamespace-foo="...".

注意:この名前空間を使う場合、テーマのCSSを手動で修正する必要があります。たとえば次のように、セレクタを指定した名前空間を付加したものにしてください。

.ui-mobile [data-mynamespace-role=page], .ui-mobile [data-mynamespace-role=dialog], .ui-page { ...  

pageLoadErrorMessage string, default: "Error Loading Page"

ページ読み込み失敗時に表示されるエラーメッセージの文字列を設定します。

pageLoadErrorMessageTheme string, default: "e"

エラーメッセージボックスの使うテーマを指定します。

pushStateEnabled boolean, default: true

history.replaceState をサポートしているブラウザでは、AjaxによるハッシュベースのURLを通常のドキュメントパスに変換するこの機能が有効になります。もしAjaxによる遷移機能を使わない、あるいはサイトの大部分が外部へのリンクであるような場合、この機能をオフにすることをお勧めします。

subPageUrlKey string, default: "ui-page"

ウィジェットがサブページを生成するような場合(たとえば階層化リストビュー)の、パラメータを指定します。デフォルトで example.html&ui-page=subpageIdentifier のようになっている部分を、任意のキーに変更できます。

touchOverflowEnabled boolean, default: false

ブラウザが overflow: と overflow-scrolling: touch; をサポートしている場合、よりスムーズなページ遷移効果と本当の意味での固定ツールバーが実装されます。注意： バージョン1.1.0で廃止されました