jQuery AutoSmoothController

Wednesday August 27 2014

Category jQuery

6605 0

Documentation

jQuery AutoSmoothController.jsの使用方法と概要。

内訳

ダウンロードしたzipフォルダを解凍すると以下のファイルとフォルダが同梱されています。

jquery.autosmoothcontroller.js（jquery.autosmoothcontroller.min.js）
jquery.autosmoothcontroller.css
jquery.ui.touch-punch.min.js（※「soue」フォルダ内に入っています）
jquery.cookie.js（※「soue」フォルダ内に入っています）
「font」フォルダ
ライセンス.text（※使用しません・・でも目は通しておいて下さいね）
Readmeファイル（※使用しません）
jquery.autosmoothcontroller.pkd.js(※パッチとcookieを同梱したminファイル)

このうち上の4つのファイルとフォルダを使用します。
「font」フォルダはjquery.autosmoothcontroller.cssと同じ階層（同じディレクトリ内）にアップロードして下さい。

使い方

1. 準備

jQuery
jQueryUI（＋draggableモバイル用パッチ）
jQuery cookieプラグイン

を併用します。

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.11.1/jquery-ui.min.js"></script>
<script src="jquery.cookie.js"></script>
<script src="jquery.ui.touch-punch.min.js"></script>/*モバイル用draggableパッチ*/
<script src="jquery.autosmoothcontroller.js"></script>

jQuery,jQuery UI,jquery.cookie,jquery.ui.touch-punchAutoSmoothControllerの4つのスクリプトファイルを読み込ませます。
※php等が使用できる場合やモバイルとPCでファイルを出し分けている場合はモバイル時のみパッチファイルを読み込ませるようにもできます。（WordPressならwp_is_mobile()で出し分けて下さい）

<link rel="stylesheet" href="jquery.autosmoothcontroller.css">

付属のスタイルシートも読みこませて下さい。

次に任意の要素へAutoSmoothControllerを登録します。

$(window).load(function(){
  $('#element').autosmoothcontroller();
});

セレクタは何でもOKですが、グローバルナビなどを指定するのがいいかなと思います。
※head内で記述する際は上記のように書きますが、スクリプトを多用しているサイトではbody最後で$(function(){…で記述するほうが若干早く起動します。

2. アンカーを設定

任意のhtmlエレメントにクラス（.section）を記述して下さい。

「jQuery AutoSmoothController」はページ内にアンカー（スクロールしていく目標点）を設置するとそのアンカーをすべて取得し、アンカーへいつでも自由にスクロールしていけるようになります。

上記を設定したすべての要素がスクロールポイントになります。基本的にアンカーとなるtarget（※オプション参照）に指定したセレクタであればどこに設置してもすべて取得しますが、各セクションのタイトル（orその親要素）にスクロールポイントを指定するのが基本の使い方と考えられます。

Example

<h2 class="section">

3.Tipsの表示をカスタマイズ

jQuery AutoSmoothControllerはデフォルトではアンカー要素内のテキストを自動取得しTipsへ表示します。

この表示をカスタマイズしたい際はアンカーに「data-asc」属性を付与し、任意の文字列を記入すると、このdata属性の文字列がTipsに反映されます。
data属性に指定した文字列はautoStringsで自動取得されたテキストより優先され、またmaxStringsの最大文字数を超えても表示されます。

Example2

<section class="section"><!--Tipsには「セクション1のタイトル」と表示される-->
<h2>セクション1のタイトル</h2>

  <!-- コンテンツの内容 -->

</section>
<section class="section" data-asc="Section2:Title"><!--Tipsには「Section2:Title」と表示される-->
<h2>セクション2のタイトル</h2>

  <!-- コンテンツの内容 -->

</section>

Tipsが利用するdata属性はデフォルトでは「asc」ですが、他でこの属性名を使っている場合はオプションの「dataname」を使って任意の文字列に変更することができます。
また、autoStringsをfalse（テキスト自動取得を行わない）かつdata属性を指定しなかった場合にTipsに表示されるテキストもオプションの「message」を使うことで任意の文字列に変更できます。（Ex. Section1,2,3… => 段落1,2,3）

設定は以上です。あとはすべて自動で出力します。

オプション

jQuery AutoSmoothControllerはブログという筆者によって書き方も十人十色なプラットフォーム上での使用を想定している為、プラットフォーも適切に対応可能な々な条件下での使用にも対応豊富なオプションを用意しそれに対応しています。

Options
Name	Default	Value	Description
target	.section	’selector’（任意のセレクタ	ここで指定したセレクタがアンカー（スクロールする位置）になります。※必ずclassで指定して下さい。
speed	1200	Number	アンカーまでのスクロールスピード。単位はミリ秒。
distance	true	true/false	アンカーのoffsetTopから指定pxスクロール位置をずらします。固定ヘッダーなどを使用されている際にご使用下さい。
stick	[false,’outer’]	[false/’selector’, ‘outer/inner’]	第一引数に指定した要素にコントローラーを吸着させます。第二引数でコントローラーの位置を吸着要素の外側/内側を指定します。※必ず配列で指定して下さい。次項の「setX」と「setY」を指定すると吸着位置を左右上下切り替えられます。
setX	‘right’	‘right’/’left’	コントローラーの初期位置を画面左右切り替えます。（初期位置は右）※前項の「stick」使用時は要素の左右
setY	‘top’	‘top’/’bottom’	コントローラーのY初期位置を指定します。後述の「manualY」指定時に影響します。
manualX	0	‘Number + px’	コントローラーの初期位置をX方向へ指定pxずらします。前述の「stick」を設定しているとこの項目は動作しません。
manualY	null	‘Number + px’	コントローラーの初期位置をY方向へ指定pxずらします。この値を入力すると前述の「placement」は自動的にfalseになります。
addLast	true	true/false	コントローラーの最後のリンクのスタイルを変更します。ページのFooterエリアへスクロールポイントを置かない場合はfalseに。
easing	swing	swing/liner（※）	イージングの設定（※jQuery Easing Pluginを併用することができます）

Tips Options
autoStrings	true	true/false	アンカー要素内のテキストを自動取得します。
maxStrings	15	Number	Tipsに表示するautoStringsで取得したテキストの最大文字数。
autoReverse	true	true/false	コントローラーのリンクにカーソルオン時表示されるTipsが画面右側ではコントローラーの左に、画面左側ではコントローラーの右に自動で切り替わるようになります。（※ドラッグ移動終了後に切り替わります）
dataname	asc	‘String’	Tipsに表示するdata属性名を変更します。（data-任意の文字列）
message	null	‘String’	ポイントへカーソルオンした際に出るTipsのデフォルト表示を「Section(n)」から「任意の文字列（n）」へ変更します。

Draggable Options
draggable	true	true/false	コントローラーのドラッグ移動の可/不可を切り替えます。移動後の位置はCookieに保存され、ページ移動後や次回閲覧時も反映されます。
axis	false	false/x/y	jQuery UI draggableのaxisと同様。xを指定すると横方向にのみ移動可、yを指定すると縦方向にのみ移動可になります。前項のdraggableがtrueの時のみ動作します。

Cookie Option
period	14	Number	Cookieの保存期間を指定できます。（※単位は日数）

Custom Class
customClass	default	default smart tab none	カスタムclassを付与します。特定のページのみコントローラーのグラフィックを変更した際などにご使用下さい。

オプションはこのように指定できます。

$(window).load(function(){
  $('#element').autosmoothcontroller({
    option1:'value',
    option2:'value',
    option3:'value'
  });
});

オプションの項目が多く、干渉し合うものもある為少し複雑に感じるかもしれません。
リアルタイムでオプションを切り替え、反映させられるデモページを作成してあります。それぞれがどのように働くかは下記デモページから確認してご参考下さい。

jQuery AutoSmoothController DEMO

応用と仕様上の注意点

ビジュアル

cssでスタイルを指定しているだけなので、お好みでご自由に変更下さい。

プラグイン内にアイコンフォントを同梱していますが、テーマで使っているものしか入れていない為、すでにお使いのアイコンフォントがあればそちらと差し替えて下さい。（※当ブログでも元々使っているアイコンフォントに差し替えて使っています。）

Lazy Load Pluginとの相性があまり良くありません

当ブログでも「Lazy Load Plugin」を愛用していますが、Lazy Load Pluginの発動タイミングがAutoSmoothControllerのアンカー位置取得より後に発動するため、「スクロール位置がアンカーからずれる」という症状が出るケースがあります。（AutoSmoothControllerのアンカー位置取得は「コントローラークリック時」。Lazy Load Pluginの発動は画像の指定px前）

Lazy Load Pluginで仮表示している画像の高さと元画像の高さが違うケースでは必ずこの症状が出ます。対策としては元画像の高さと仮表示する画像の高さ（縦横比）を同じにしていただくことで解消できます。