From fc7eb82c44b23acd069bb2f8cdfe5465acdcb015 Mon Sep 17 00:00:00 2001 From: Nobuo Kihara Date: Sat, 20 Dec 2014 11:07:20 +0900 Subject: [PATCH] docs/guide-ja/output-client-scripts.md - added [ci skip] --- docs/guide-ja/README.md | 2 +- docs/guide-ja/output-client-scripts.md | 98 ++++++++++++++++++++++++++ 2 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 docs/guide-ja/output-client-scripts.md diff --git a/docs/guide-ja/README.md b/docs/guide-ja/README.md index 2db0229eb2..afde2a1f66 100644 --- a/docs/guide-ja/README.md +++ b/docs/guide-ja/README.md @@ -101,7 +101,7 @@ All Rights Reserved. * **TBD** [並べ替え](output-sorting.md) * [データプロバイダ](output-data-providers.md) * [データウィジェット](output-data-widgets.md) -* **翻訳中** [クライアントスクリプトを扱う](output-client-scripts.md) +* [クライアントスクリプトを扱う](output-client-scripts.md) * **翻訳中** [テーマ](output-theming.md) diff --git a/docs/guide-ja/output-client-scripts.md b/docs/guide-ja/output-client-scripts.md new file mode 100644 index 0000000000..b862c4b7dc --- /dev/null +++ b/docs/guide-ja/output-client-scripts.md @@ -0,0 +1,98 @@ +クライアントスクリプトを扱う +============================ + +> Note|注意: この節はまだ執筆中です。 + +### スクリプトを登録する + +[[yii\web\View]] オブジェクトに対してスクリプトを登録することが出来ます。 +このための専用のメソッドが二つあります。 +すなわち、インラインスクリプトのための [[yii\web\View::registerJs()|registerJs()]] と、外部スクリプトのための [[yii\web\View::registerJsFile()|registerJsFile()]] です。 +インラインスクリプトは、設定のためや、動的に生成されるコードのために有用なものです。 +次のようにして、これらを追加するメソッドを使うことが出来ます。 + +```php +$this->registerJs("var options = ".json_encode($options).";", View::POS_END, 'my-options'); +``` + +最初の引数は、ページに挿入したい実際の JS コードです。 +二番目の引数は、スクリプトがページのどの場所に挿入されるべきかを決定します。 +取りうる値は以下のとおりです。 + +- [[yii\web\View::POS_HEAD|View::POS_HEAD]] - head セクション。 +- [[yii\web\View::POS_BEGIN|View::POS_BEGIN]] - 開始の `` の直後。 +- [[yii\web\View::POS_END|View::POS_END]] - 終了の `` の直前。 +- [[yii\web\View::POS_READY|View::POS_READY]] - ドキュメントの `ready` イベントで実行するコード。これを指定すると、[[yii\web\JqueryAsset|jQuery]] が自動的に登録されます。 +- [[yii\web\View::POS_LOAD|View::POS_LOAD]] - ドキュメントの `load` イベントで実行するコード。これを指定すると、[[yii\web\JqueryAsset|jQuery]] が自動的に登録されます。 + +最後の引数は、スクリプトのユニークな ID です。これによってコードブロックを一意に特定し、同じ ID のスクリプトが既にある場合は、新しいものを追加するのでなく、それを置き換えます。 +ID を指定しない場合は、JS コードそれ自身が ID として扱われます。 + +外部スクリプトは次のようにして追加することが出来ます。 + +```php +$this->registerJsFile('http://example.com/js/main.js', ['depends' => [JqueryAsset::className()]]); +``` + +[[yii\web\View::registerJsFile()|registerJsFile()]] の引数は [[yii\web\View::registerCssFile()|registerCssFile()]] のそれと同じです。 +上記の例では、`main.js` ファイルを `JqueryAsset` に依存するものとして登録しています。 +これは、`main.js` ファイルが `jquery.js` の後に追加されるようになることを意味します。 +この依存関係を指定しない場合は、`main.js` と `jquery.js` の相対的な順序は未定義となります。 + +[[yii\web\View::registerCssFile()|registerCssFile()]] と同じように、外部 JS ファイルを登録するのに [[yii\web\View::registerJsFile()|registerJsFile()]] を使わずに、[アセットバンドル](structure-assets.md) を使うことが強く推奨されます。 + + +### アセットバンドルを登録する + +既に述べたように、CSS と JavaScript を直接に使う代りにアセットバンドルを使うことが望まれます。 +アセットバンドルを定義する方法の詳細は、ガイドの [アセットマネージャ](structure-assets.md) の節で知ることが出来ます。 +既に定義されているアセットバンドルを使うことについては、次のように非常に簡明です。 + +```php +\frontend\assets\AppAsset::register($this); +``` + + + +### CSS を登録する + +[[yii\web\View::registerCss()|registerCss()]] またはr [[yii\web\View::registerCssFile()|registerCssFile()]] を使って CSS を登録することが出来ます。 +前者は CSS のコードブロックを登録し、後者は外部 CSS ファイルを登録します。 +例えば、 + +```php +$this->registerCss("body { background: #f00; }"); +``` + +上記のコードは、以下の内容をページの head セクションに追加する結果となります。 + +```html + +``` + +`style` タグに追加のプロパティを指定したい場合は、三番目の引数として「名前-値」のペアの配列を渡します。 +`style` タグが一つだけになることを保証する必要がある場合は、メタタグの説明で言及したように、4番目の引数を使います。 + +```php +$this->registerCssFile("http://example.com/css/themes/black-and-white.css", [ + 'depends' => [BootstrapAsset::className()], + 'media' => 'print', +], 'css-print-theme'); +``` + +上記のコードは、ページの head セクションに CSS ファイルへのリンクを追加します。 + +* 最初の引数が登録されるべき CSS ファイルを指定します。 +* 二番目の引数は、結果として生成される `` タグの HTML 属性を指定するものです。 + ただし、`depends` オプションは特別な処理を受けます。 + このオプションは、この CSS ファイルが依存するアセットバンドルを指定するものです。 + この例では、依存するアセットバンドルは [[yii\bootstrap\BootstrapAsset|BootstrapAsset]] です。 + これは、この CSS ファイルが、[[yii\bootstrap\BootstrapAsset|BootstrapAsset]] に含まれる CSS ファイルの *後* に追加されることを意味します。 +* 最後の引数は、この CSS ファイルを特定するための ID を指定するものです。 + 指定されていない場合は、CSS ファイルの URL が代りに ID として使用されます。 + +外部 CSS ファイルを登録するためには、[[yii\web\View::registerCssFile()|registerCssFile()]] を使うのではなく、[アセットバンドル](structure-assets.md) を使うことが強く推奨されます。 +アセットバンドルを使うと、複数の CSS ファイルを結合して圧縮することが可能になります。 +トラフィックの多いウェブサイトではそうすることが望まれます。