If you are registering an asset bundle in other places, you should provide the needed view object. For example,
to register an asset bundle in a [widget](structure-widgets.md) class, you can get the view object by `$this->view`.
When an asset bundle is registered with a view, behind the scene Yii will register all its dependent asset bundles.
When an asset bundle is registered with a view, behind the scenes Yii will register all its dependent asset bundles.
And if an asset bundle is located in a directory inaccessible through the Web, it will be published to a Web directory.
Later when the view renders a page, it will generate `<link>` and `<script>` tags for the CSS and JavaScript files
Later, when the view renders a page, it will generate `<link>` and `<script>` tags for the CSS and JavaScript files
listed in the registered bundles. The order of these tags is determined by the dependencies among
the registered bundles and the order of the assets listed in the [[yii\web\AssetBundle::css]] and [[yii\web\AssetBundle::js]]
properties.
...
...
@@ -291,7 +291,7 @@ be the corresponding [configuration arrays](concept-configurations.md).
You can disable one or multiple asset bundles by associating `false` with the names of the asset bundles
that you want to disable. When you register a disabled asset bundle with a view, none of its dependent bundles
will be registered, and the view will also not include any of the assets in the bundle in the page it renders.
will be registered, and the view also will not include any of the assets in the bundle in the page it renders.
For example, to disable [[yii\web\JqueryAsset]], you can use the following configuration:
```php
...
...
@@ -312,8 +312,8 @@ You can also disable *all* asset bundles by setting [[yii\web\AssetManager::bund
### Asset Mapping <a name="asset-mapping"></a>
Sometimes you want to "fix" incorrect/incompatible asset file paths used in multiple asset bundles. For example,
bundle A uses `jquery.min.js`of version 1.11.1, and bundle B uses `jquery.js` of version 2.1.1. While you can
Sometimes you may want to "fix" incorrect/incompatible asset file paths used in multiple asset bundles. For example,
bundle A uses `jquery.min.js`version 1.11.1, and bundle B uses `jquery.js` version 2.1.1. While you can
fix the problem by customizing each bundle, an easier way is to use the *asset map* feature to map incorrect assets
to the desired ones. To do so, configure the [[yii\web\AssetManager::assetMap]] property like the following:
...
...
@@ -333,11 +333,11 @@ return [
The keys of [[yii\web\AssetManager::assetMap|assetMap]] are the asset names that you want to fix, and the values
are the desired asset paths. When you register an asset bundle with a view, each relative asset file in its
[[yii\web\AssetBundle::css|css]] and [[yii\web\AssetBundle::js|js]] arrays will be examined against this map.
If any of the keys is found to be the last part of an asset file (which is prefixed with [[yii\web\AssetBundle::sourcePath]]
If any of the keys are found to be the last part of an asset file (which is prefixed with [[yii\web\AssetBundle::sourcePath]]
if available), the corresponding value will replace the asset and be registered with the view.
For example, an asset file `my/path/to/jquery.js` matches a key `jquery.js`.
For example, the asset file `my/path/to/jquery.js` matches the key `jquery.js`.
> Note: Only assets specified using relative paths are subject to asset mapping. And the target asset paths
> Note: Only assets specified using relative paths are subject to asset mapping. Also, the target asset paths
should be either absolute URLs or paths relative to [[yii\web\AssetManager::basePath]].
...
...
@@ -377,7 +377,7 @@ be referenced in your application or extension code.
-[[yii\web\YiiAsset]]: It mainly includes the `yii.js` file which implements a mechanism of organizing JavaScript code
in modules. It also provides special support for `data-method` and `data-confirm` attributes and other useful features.
-[[yii\web\JqueryAsset]]: It includes the `jquery.js` file from the jQuery bower package.
-[[yii\web\JqueryAsset]]: It includes the `jquery.js` file from the jQuery Bower package.
-[[yii\bootstrap\BootstrapAsset]]: It includes the CSS file from the Twitter Bootstrap framework.
-[[yii\bootstrap\BootstrapPluginAsset]]: It includes the JavaScript file from the Twitter Bootstrap framework for
supporting Bootstrap JavaScript plugins.
...
...
@@ -394,8 +394,7 @@ Instead of directly writing CSS and/or JavaScript code, developers often write t
use special tools to convert it into CSS/JavaScript. For example, for CSS code you may use [LESS](http://lesscss.org/)
or [SCSS](http://sass-lang.com/); and for JavaScript you may use [TypeScript](http://www.typescriptlang.org/).
You can list the asset files in extended syntax in [[yii\web\AssetBundle::css|css]] and [[yii\web\AssetBundle::js|js]]
in an asset bundle. For example,
You can list the asset files in extended syntax in the [[yii\web\AssetBundle::css|css]] and [[yii\web\AssetBundle::js|js]] properties of an asset bundle. For example,
```php
classAppAssetextendsAssetBundle
...
...
@@ -451,7 +450,7 @@ return [
];
```
In the above we specify the supported extended syntax via the [[yii\web\AssetConverter::commands]] property.
In the above, we specify the supported extended syntax via the [[yii\web\AssetConverter::commands]] property.
The array keys are the file extension names (without leading dot), and the array values are the resulting
asset file extension names and the commands for performing the asset conversion. The tokens `{from}` and `{to}`
in the commands will be replaced with the source asset file paths and the target asset file paths.
...
...
@@ -469,12 +468,12 @@ download size of these files, a common practice is to combine and compress multi
one or very few files, and then include these compressed files instead of the original ones in the Web pages.
> Info: Combining and compressing assets is usually needed when an application is in production mode.
In development mode, using the original CSS/JavaScript files is often more convenient for debugging purpose.
In development mode, using the original CSS/JavaScript files is often more convenient for debugging purposes.
In the following, we introduce an approach to combine and compress asset files without the need of modifying
In the following, we introduce an approach to combine and compress asset files without the need to modify
your existing application code.
1. Find out all asset bundles in your application that you plan to combine and compress.
1. Find all the asset bundles in your application that you plan to combine and compress.
2. Divide these bundles into one or a few groups. Note that each bundle can only belong to a single group.
3. Combine/compress the CSS files in each group into a single file. Do this similarly for the JavaScript files.
4. Define a new asset bundle for each group:
...
...
@@ -493,7 +492,7 @@ asset files are included in the page, instead of the original ones.
Let's use an example to further explain the above approach.
Assume your application has two pages X and Y. Page X uses asset bundle A, B and C, while Page Y uses asset bundle B, C and D.
Assume your application has two pages, X and Y. Page X uses asset bundles A, B and C, while Page Y uses asset bundles B, C and D.
You have two ways to divide these asset bundles. One is to use a single group to include all asset bundles, the
other is to put A in Group X, D in Group Y, and (B, C) in Group S. Which one is better? It depends. The first way
...
...
@@ -513,7 +512,7 @@ from C and D, followed by B and finally A.
After combining and compressing, we get one CSS file and one JavaScript file. Assume they are named as
`all-xyz.css` and `all-xyz.js`, where `xyz` stands for a timestamp or a hash that is used to make the file name unique
to avoid HTTP caching problem.
to avoid HTTP caching problems.
We are at the last step now. Configure the [[yii\web\AssetManager|asset manager]] as follows in the application
configuration:
...
...
@@ -622,9 +621,9 @@ JavaScript files are combined, compressed and written to `js/all-{hash}.js` wher
the resulting file.
The `jsCompressor` and `cssCompressor` options specify the console commands or PHP callbacks for performing
JavaScript and CSS combining/compressing. By default Yii uses [Closure Compiler](https://developers.google.com/closure/compiler/)
JavaScript and CSS combining/compressing. By default, Yii uses [Closure Compiler](https://developers.google.com/closure/compiler/)
for combining JavaScript files and [YUI Compressor](https://github.com/yui/yuicompressor/) for combining CSS files.
You should install tools manually or adjust these options to use your favorite tools.
You should install those tools manually or adjust these options to use your favorite tools.
With the configuration file, you can run the `asset` command to combine and compress the asset files
