Skip to content

Commit

Permalink
Edited and extended Guide section about client scripts
Browse files Browse the repository at this point in the history 
This section had the "under development note" for a long time and was
lacking a lot of information.
It should also contain info about `yii.js` but that is to be added in
another PR.
  • Loading branch information
@cebe
cebe committed Dec 12, 2016
1 parent 4fd7a9d commit b6e2508
Show file tree
Hide file tree
Showing 3 changed files with 154 additions and 39 deletions.
190 changes: 152 additions & 38 deletions docs/guide/output-client-scripts.md
View file
Original file line number Diff line number Diff line change
@@ -1,70 +1,83 @@
Working with Client Scripts
===========================

> Note: This section is under development.
Modern web applications usually not only contain static HTML pages that are
rendered and sent to the browser but also contain Javascript that is used
to modify the page in the browser by manipulating existing elements and also
loading new content via AJAX.
This section describes the methods provided by Yii for adding JavaScript and CSS to a website as well as dynamically adjusting these.

### Registering scripts
## Registering scripts <span id="register-scripts"></span>

With the [[yii\web\View]] object you can register scripts. There are two dedicated methods for it:
When working with the [[yii\web\View]] object you can dynamically register frontend scripts.
There are two dedicated methods for this:
[[yii\web\View::registerJs()|registerJs()]] for inline scripts and
[[yii\web\View::registerJsFile()|registerJsFile()]] for external scripts.
Inline scripts are useful for configuration and dynamically generated code.

### Registering inline scripts <span id="inline-scripts"></span>

Inline scripts are useful for configuration and dynamically generated code and also for small snippets created by reusable frontend code contained in [widgets](structure-widgets.md).
The method for adding these can be used as follows:

```php
$this->registerJs("var options = ".json_encode($options).";", View::POS_END, 'my-options');
$this->registerJs(
"$('#myButton').on('click', function() { alert('Button clicked!'); });",
View::POS_READY,
'my-button-handler'
);
```

The first argument is the actual JS code we want to insert into the page. The second argument
determines where script should be inserted into the page. Possible values are:
The first argument is the actual JS code we want to insert into the page.
It will be wrapped into a `<script>`-tag. The second argument
determines at which position the script should be inserted into the page. Possible values are:

- [[yii\web\View::POS_HEAD|View::POS_HEAD]] for head section.
- [[yii\web\View::POS_BEGIN|View::POS_BEGIN]] for right after opening `<body>`.
- [[yii\web\View::POS_END|View::POS_END]] for right before closing `</body>`.
- [[yii\web\View::POS_READY|View::POS_READY]] for executing code on document `ready` event. This will register [[yii\web\JqueryAsset|jQuery]] automatically.
- [[yii\web\View::POS_LOAD|View::POS_LOAD]] for executing code on document `load` event. This will register [[yii\web\JqueryAsset|jQuery]] automatically.

The last argument is a unique script ID that is used to identify code block and replace existing one with the same ID
instead of adding a new one. If you don't provide it, the JS code itself will be used as the ID.
- [[yii\web\View::POS_READY|View::POS_READY]] for executing code on the [document `ready` event](http://learn.jquery.com/using-jquery-core/document-ready/).
This will automatically register [[yii\web\JqueryAsset|jQuery]] and wrap the code into the appropriate jQuery code. This is the default position.
- [[yii\web\View::POS_LOAD|View::POS_LOAD]] for executing code on the
[document `load` event](http://learn.jquery.com/using-jquery-core/document-ready/). Same as the above, this will also register [[yii\web\JqueryAsset|jQuery]] automatically.

An external script can be added like the following:
The last argument is a unique script ID that is used to identify the script code block and replace an existing one with the same ID
instead of adding a new one. If you don't provide it, the JS code itself will be used as the ID. It is used to avoid registration of the same code muliple times.

```php
$this->registerJsFile('http://example.com/js/main.js', ['depends' => [\yii\web\JqueryAsset::className()]]);
```
### Registering script files <span id="script-files"></span>

The arguments for [[yii\web\View::registerJsFile()|registerJsFile()]] are similar to those for
[[yii\web\View::registerCssFile()|registerCssFile()]]. In the above example,
we register the `main.js` file with the dependency on `JqueryAsset`. This means the `main.js` file
we register the `main.js` file with the dependency on the [[yii\web\JqueryAsset]]. This means the `main.js` file
will be added AFTER `jquery.js`. Without this dependency specification, the relative order between
`main.js` and `jquery.js` would be undefined.
`main.js` and `jquery.js` would be undefined and the code would not work.

Like for [[yii\web\View::registerCssFile()|registerCssFile()]], it is also highly recommended that you use
[asset bundles](structure-assets.md) to register external JS files rather than using [[yii\web\View::registerJsFile()|registerJsFile()]].


### Registering asset bundles

As was mentioned earlier it's preferred to use asset bundles instead of using CSS and JavaScript directly. You can get
details on how to define asset bundles in [asset manager](structure-assets.md) section of the guide. As for using already defined
asset bundle, it's very straightforward:
An external script can be added like the following:

```php
\frontend\assets\AppAsset::register($this);
$this->registerJsFile(
'@web/js/main.js',
['depends' => [\yii\web\JqueryAsset::className()]]
);
```

This will add a tag for the script `/js/main.js` located under the applications [base Url](concept-aliases.md#predefined-aliases).

It is highly recommended that you use [asset bundles](structure-assets.md) to register external JS files rather than using [[yii\web\View::registerJsFile()|registerJsFile()]] because these allow better flexibility and more granular configuration of dependencies. Also using asset bundles allows you to combine and compress
multiple JS files, which is desirable for high traffic websites.

### Registering CSS
## Registering CSS <span id="register-css"></span>

You can register CSS using [[yii\web\View::registerCss()|registerCss()]] or [[yii\web\View::registerCssFile()|registerCssFile()]].
The former registers a block of CSS code while the latter registers an external CSS file. For example,
Similar to Javascript, you can register CSS using
[[yii\web\View::registerCss()|registerCss()]] or
[[yii\web\View::registerCssFile()|registerCssFile()]].
The former registers a block of CSS code while the latter registers an external CSS file.

### Registering inline CSS <span id="inline-css"></span>

```php
$this->registerCss("body { background: #f00; }");
```

The code above will result in adding the following to the head section of the page:
The code above will result in adding the following to the `<head>` section of the page:

```html
<style>
Expand All @@ -73,26 +86,127 @@ body { background: #f00; }
```

If you want to specify additional properties of the style tag, pass an array of name-values to the second argument.
If you need to make sure there's only a single style tag use third argument as was mentioned in meta tags description.
The last argument is a unique ID that is used to identify the style block and make sure it is only added once in case the same style is registered from different places in the code.

### Registering CSS files <span id="css-files"></span>

A CSS file can be registered using the following:

```php
$this->registerCssFile("http://example.com/css/themes/black-and-white.css", [
'depends' => [BootstrapAsset::className()],
$this->registerCssFile("@web/css/themes/black-and-white.css", [
'depends' => [\yii\bootstrap\BootstrapAsset::className()],
'media' => 'print',
], 'css-print-theme');
```

The code above will add a link to CSS file to the head section of the page.
The above code will add a link to the `/css/themes/black-and-white.css` CSS file to the `<head>` section of the page.

* The first argument specifies the CSS file to be registered.
The `@web` in this example is an [alias for the applications base URL](concept-aliases.md#predefined-aliases).
* The second argument specifies the HTML attributes for the resulting `<link>` tag. The option `depends`
is specially handled. It specifies which asset bundles this CSS file depends on. In this case, the dependent
asset bundle is [[yii\bootstrap\BootstrapAsset|BootstrapAsset]]. This means the CSS file will be added
*after* the CSS files in [[yii\bootstrap\BootstrapAsset|BootstrapAsset]].
*after* the CSS files from [[yii\bootstrap\BootstrapAsset|BootstrapAsset]].
* The last argument specifies an ID identifying this CSS file. If it is not provided, the URL of the CSS file will be
used instead.


It is highly recommended that you use [asset bundles](structure-assets.md) to register external CSS files rather than
using [[yii\web\View::registerCssFile()|registerCssFile()]]. Using asset bundles allows you to combine and compress
multiple CSS files, which is desirable for high traffic websites.
It also provides more flexibility as all asset dependencies of your application are configured in one place.


## Registering asset bundles <span id="asset-bundles"></span>

As was mentioned earlier it's recommended to use asset bundles instead of registering CSS and JavaScript files directly.
You can get details on how to define asset bundles in the
["Assets" section](structure-assets.md).
As for using already defined asset bundles, it's very straightforward:

```php
\frontend\assets\AppAsset::register($this);
```

In the above code, in the context of a view file, the `AppAsset` bundle is registered on the current view (represented by `$this`).
When registering asset bundles from within a widget, you would pass the
[[yii\base\Widget::$view|$view]] of the widget instead (`$this->view`).


## Generating Dynamic Javascript <span id="dynamic-js"></span>

In view files often the HTML code is not written out directly but generated
by some PHP code dependent on the variables of the view.
In order for the generated HTML to be manipulated with Javascript, the JS code has to contain dynamic parts too, for example the ids of the jQuery selectors.

To insert PHP variables into JS code, their values have to be
escaped properly. Especially when the JS code is inserted into
HTML instead of residing in a dedicated JS file.
Yii provides the [[yii\helpers\Json::htmlEncode()|htmlEncode()]] method of the [[yii\helpers\Json|Json]]-helper for this purpose. Its usage will be shown in the following examples.

### Registering a global Javascript configuration <span id="js-configuration"></span>

In this example we use an array to pass global configuration parameters from
the PHP part of the application to the JS frontend code.

```php
$options = [
'appName' => Yii::$app->name,
'baseUrl' => Yii::$app->request->baseUrl,
'language' => Yii::$app->language,
// ...
];
$this->registerJs(
"var yiiOptions = ".\yii\helpers\Json::htmlEncode($options).";",
View::POS_HEAD,
'yiiOptions'
);
```

The above code will register a `<script>`-tag containing the JavaScript
variable definition, e.g.:

```javascript
var yiiOptions = {"appName":"My Yii Application","baseUrl":"/basic/web","language":"en"};
```

In your Javascript code you can now access these like `yiiOptions.baseUrl` or `yiiOptions.language`.

### Passing translated messages <span id="translated-messages"></span>

You may encounter a case where your Javascript needs to print a message reacting to some event. In an application that works with multiple languages this string has to be translated to the current application language.
One way to achieve this is to use the
[message translation feature](tutorial-i18n.md#message-translation) provided by Yii and passing the result to the JavaScript code.

```php
$message = \yii\helpers\Json::htmlEncode(
\Yii::t('app', 'Button clicked!')
);
$this->registerJs(<<<JS
$('#myButton').on('click', function() { alert( $message ); });",
JS
);
```
The above example code uses PHP
[Heredoc](http://php.net/manual/de/language.types.string.php#language.types.string.syntax.heredoc) syntax for better readability. This also enables better syntax highlighting in most IDEs so it is the
preferred way of writing inline Javascript, especially useful for code that is longer than a single line. The variable `$message` is created in PHP and
thanks to [[yii\helpers\Json::htmlEncode|Json::htmlEncode]] it contains the
string in valid JS syntax, which can be inserted into the Javascript code to place the dynamic string in the function call to `alert()`.
> Note: When using Heredoc, be careful with variable naming in JS code
> as variables beginning with `$` may be interpreted as PHP variables which
> will be replaced by their content.
> The jQuery function in form of `$(` or `$.` is not interpreted
> as a PHP variable and can safely be used.
## The `yii.js` script <span id="yii.js"></span>
> Note: This section has not been written yet. It should contain explanation of the functionality provided by `yii.js`:
>
> - Yii JavaScript Modules
> - CSRF param handling
> - `data-confirm` handler
> - `data-method` handler
> - script filtering
> - redirect handling
2 changes: 1 addition & 1 deletion docs/guide/runtime-responses.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,7 @@ redirect the browser accordingly.
> Info: Yii comes with a `yii.js` JavaScript file which provides a set of commonly used JavaScript utilities,
including browser redirection based on the `X-Redirect` header. Therefore, if you are using this JavaScript file
(by registering the [[yii\web\YiiAsset]] asset bundle), you do not need to write anything to support AJAX redirection.

More information about `yii.js` can be found in the [Client Scripts Section](output-client-scripts.md#yii.js).

## Sending Files <span id="sending-files"></span>

Expand Down
1 change: 1 addition & 0 deletions docs/guide/structure-assets.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -490,6 +490,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.
More information about `yii.js` can be found in the [Client Scripts Section](output-client-scripts.md#yii.js).
- [[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
Expand Down

0 comments on commit b6e2508

Please sign in to comment.