|
| 1 | +Working with Client Scripts |
| 2 | +=========================== |
| 3 | + |
| 4 | +> Note: This section is under development. |
| 5 | +
|
| 6 | +### Registering scripts |
| 7 | + |
| 8 | +With the [[yii\web\View]] object you can register scripts. There are two dedicated methods for it: |
| 9 | +[[yii\web\View::registerJs()|registerJs()]] for inline scripts and |
| 10 | +[[yii\web\View::registerJsFile()|registerJsFile()]] for external scripts. |
| 11 | +Inline scripts are useful for configuration and dynamically generated code. |
| 12 | +The method for adding these can be used as follows: |
| 13 | + |
| 14 | +```php |
| 15 | +$this->registerJs("var options = ".json_encode($options).";", View::POS_END, 'my-options'); |
| 16 | +``` |
| 17 | + |
| 18 | +The first argument is the actual JS code we want to insert into the page. The second argument |
| 19 | +determines where script should be inserted into the page. Possible values are: |
| 20 | + |
| 21 | +- [[yii\web\View::POS_HEAD|View::POS_HEAD]] for head section. |
| 22 | +- [[yii\web\View::POS_BEGIN|View::POS_BEGIN]] for right after opening `<body>`. |
| 23 | +- [[yii\web\View::POS_END|View::POS_END]] for right before closing `</body>`. |
| 24 | +- [[yii\web\View::POS_READY|View::POS_READY]] for executing code on document `ready` event. This will register [[yii\web\JqueryAsset|jQuery]] automatically. |
| 25 | +- [[yii\web\View::POS_LOAD|View::POS_LOAD]] for executing code on document `load` event. This will register [[yii\web\JqueryAsset|jQuery]] automatically. |
| 26 | + |
| 27 | +The last argument is a unique script ID that is used to identify code block and replace existing one with the same ID |
| 28 | +instead of adding a new one. If you don't provide it, the JS code itself will be used as the ID. |
| 29 | + |
| 30 | +An external script can be added like the following: |
| 31 | + |
| 32 | +```php |
| 33 | +$this->registerJsFile('http://example.com/js/main.js', [JqueryAsset::className()]); |
| 34 | +``` |
| 35 | + |
| 36 | +The arguments for [[yii\web\View::registerJsFile()|registerJsFile()]] are similar to those for |
| 37 | +[[yii\web\View::registerCssFile()|registerCssFile()]]. In the above example, |
| 38 | +we register the `main.js` file with the dependency on `JqueryAsset`. This means the `main.js` file |
| 39 | +will be added AFTER `jquery.js`. Without this dependency specification, the relative order between |
| 40 | +`main.js` and `jquery.js` would be undefined. |
| 41 | + |
| 42 | +Like for [[yii\web\View::registerCssFile()|registerCssFile()]], it is also highly recommended that you use |
| 43 | +[asset bundles](assets.md) to register external JS files rather than using [[yii\web\View::registerJsFile()|registerJsFile()]]. |
| 44 | + |
| 45 | + |
| 46 | +### Registering asset bundles |
| 47 | + |
| 48 | +As was mentioned earlier it's preferred to use asset bundles instead of using CSS and JavaScript directly. You can get |
| 49 | +details on how to define asset bundles in [asset manager](assets.md) section of the guide. As for using already defined |
| 50 | +asset bundle, it's very straightforward: |
| 51 | + |
| 52 | +```php |
| 53 | +\frontend\assets\AppAsset::register($this); |
| 54 | +``` |
| 55 | + |
| 56 | + |
| 57 | + |
| 58 | +### Registering CSS |
| 59 | + |
| 60 | +You can register CSS using [[yii\web\View::registerCss()|registerCss()]] or [[yii\web\View::registerCssFile()|registerCssFile()]]. |
| 61 | +The former registers a block of CSS code while the latter registers an external CSS file. For example, |
| 62 | + |
| 63 | +```php |
| 64 | +$this->registerCss("body { background: #f00; }"); |
| 65 | +``` |
| 66 | + |
| 67 | +The code above will result in adding the following to the head section of the page: |
| 68 | + |
| 69 | +```html |
| 70 | +<style> |
| 71 | +body { background: #f00; } |
| 72 | +</style> |
| 73 | +``` |
| 74 | + |
| 75 | +If you want to specify additional properties of the style tag, pass an array of name-values to the third argument. |
| 76 | +If you need to make sure there's only a single style tag use fourth argument as was mentioned in meta tags description. |
| 77 | + |
| 78 | +```php |
| 79 | +$this->registerCssFile("http://example.com/css/themes/black-and-white.css", [BootstrapAsset::className()], ['media' => 'print'], 'css-print-theme'); |
| 80 | +``` |
| 81 | + |
| 82 | +The code above will add a link to CSS file to the head section of the page. |
| 83 | + |
| 84 | +* The first argument specifies the CSS file to be registered. |
| 85 | +* The second argument specifies that this CSS file depends on [[yii\bootstrap\BootstrapAsset|BootstrapAsset]], meaning it will be added |
| 86 | + AFTER the CSS files in [[yii\bootstrap\BootstrapAsset|BootstrapAsset]]. Without this dependency specification, the relative order |
| 87 | + between this CSS file and the [[yii\bootstrap\BootstrapAsset|BootstrapAsset]] CSS files would be undefined. |
| 88 | +* The third argument specifies the attributes for the resulting `<link>` tag. |
| 89 | +* The last argument specifies an ID identifying this CSS file. If it is not provided, the URL of the CSS file will be |
| 90 | + used instead. |
| 91 | + |
| 92 | + |
| 93 | +It is highly recommended that you use [asset bundles](assets.md) to register external CSS files rather than |
| 94 | +using [[yii\web\View::registerCssFile()|registerCssFile()]]. Using asset bundles allows you to combine and compress |
| 95 | +multiple CSS files, which is desirable for high traffic websites. |
0 commit comments