Assets
======

Um asset no Yii é um arquivo que pode ser referenciado em uma página Web. Pode 
ser um arquivo CSS, JavaScript, imagem, vídeo, etc. Os assets estão localizados 
em um diretório acessível pela Web e estão diretamente disponibilizados por 
servidores Web.

Muitas vezes, é preferível gerenciá-los programaticamente. Por exemplo, quando 
você usar o widget [[yii\jui\DatePicker]] em uma página, será incluído 
automaticamente os arquivos CSS e JavaScript requeridos, ao invés de pedir para 
você encontrar estes arquivos e incluí-los manualmente. E quando você atualizar 
o widget para uma nova versão, automaticamente usará a nova versão dos arquivos 
de assets. Neste tutorial, iremos descrever esta poderosa capacidade de gerência 
de assets fornecidas pelo Yii.


## Asset Bundles <span id="asset-bundles"></span>

O Yii gerencia os assets na unidade de *asset bundle*. Um asset bundle é 
simplesmente uma coleção de assets localizados em um diretório. Quando você 
registrar um asset bundle em uma [view (visão)](structure-views.md), serão  
incluídos os arquivos CSS e JavaScript do bundle na página Web renderizada.


## Definindo os Asset Bundles <span id="defining-asset-bundles"></span>

Os asset bundles são especificados como classes PHP que estendem de 
[[yii\web\AssetBundle]]. O nome de um bundle corresponde simplesmente a um nome 
de classe PHP totalmente qualificada (sem a primeira barra invertida). Uma classe 
de asset bundle deve ser [autoloadable](concept-autoloading.md). Geralmente é 
especificado onde os asset estão localizados, quais arquivos CSS e JavaScript 
possuem e como o bundle depende de outro bundles.

O código a seguir define o asset bundle principal que é usado pelo 
[template básico de projetos](start-installation.md):

```php
<?php

namespace app\assets;

use yii\web\AssetBundle;

class AppAsset extends AssetBundle
{
    public $basePath = '@webroot';
    public $baseUrl = '@web';
    public $css = [
        'css/site.css',
    ];
    public $js = [
    ];
    public $depends = [
        'yii\web\YiiAsset',
        'yii\bootstrap\BootstrapAsset',
    ];
}
```

A classe `AppAsset` acima, especifica que os arquivos de assets estão localizadas 
sob o diretório `@webroot` que corresponde à URL `@web`;
O bundle contém um único arquivo CSS `css/site.css` e nenhum arquivo JavaScript;
O bundle depende de outros dois bundles: [[yii\web\YiiAsset]] e 
[[yii\bootstrap\BootstrapAsset]]. Mais detalhes sobre as propriedades do 
[[yii\web\AssetBundle]] serão encontradas a seguir:

* [[yii\web\AssetBundle::sourcePath|sourcePath]]: especifica o diretório que 
  contém os arquivos de assets neste bundle. Esta propriedade deve ser definida 
  se o diretório root não for acessível pela Web. Caso contrário, você deve definir 
  as propriedades [[yii\web\AssetBundle::basePath|basePath]] e 
  [[yii\web\AssetBundle::baseUrl|baseUrl]]. Os [alias de caminhos](concept-aliases.md) 
  podem ser usados nesta propriedade.
* [[yii\web\AssetBundle::basePath|basePath]]: especifica um diretório acessível 
  pela Web que contém os arquivos de assets neste bundle. Quando você especificar 
  a propriedade [[yii\web\AssetBundle::sourcePath|sourcePath]], o 
  [gerenciador de asset](#asset-manager) publicará os assets deste bundle para um 
  diretório acessível pela Web e sobrescreverá a propriedade `basePath` para ficar 
  em conformidade. Você deve definir esta propriedade caso os seus arquivos de 
  asset já estejam em um diretório acessível pela Web e não precisam ser publicados.  
  As [alias de caminhos](concept-aliases.md) podem ser usados aqui.
* [[yii\web\AssetBundle::baseUrl|baseUrl]]: especifica a URL correspondente ao 
  diretório [[yii\web\AssetBundle::basePath|basePath]]. Assim como a propriedade 
  [[yii\web\AssetBundle::basePath|basePath]], se você especificar a propriedade 
  [[yii\web\AssetBundle::sourcePath|sourcePath]], o 
  [gerenciador de asset](#asset-manager) publicará os assets e sobrescreverá esta 
  propriedade para entrar em conformidade. Os [alias de caminhos](concept-aliases.md) 
  podem ser usados aqui.
* [[yii\web\AssetBundle::js|js]]: um array listando os arquivos JavaScript contidos 
  neste bundle. Observe que apenas a barra "/" pode ser usada como separadores de 
  diretórios. Cada arquivo JavaScript deve ser especificado em um dos dois seguintes 
  formatos:
  - um caminho relativo representando um local do arquivo JavaScript (por exemplo,  
    `js/main.js`). O caminho real do arquivo pode ser determinado pela precedência 
    do [[yii\web\AssetManager::basePath]] no caminho relativo e a URL real do 
    arquivo pode ser determinado pela precedência do [[yii\web\AssetManager::baseUrl]] 
    no caminho relativo.
  - uma URL absoluta representando um arquivo JavaScript externo. Por exemplo, 
    `http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js` ou 
    `//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js`.
* [[yii\web\AssetBundle::css|css]]: uma array listando os arquivos CSS contidos 
  neste bundle. O formato deste array é igual ao que foi mencionado no 
  [[yii\web\AssetBundle::js|js]].
* [[yii\web\AssetBundle::depends|depends]]: um array listando os nomes dos asset 
  bundles que este bundle depende (será explicado em breve).
* [[yii\web\AssetBundle::jsOptions|jsOptions]]: especifica as opções que serão 
  passadas para o método [[yii\web\View::registerJsFile()]] quando for chamado 
  para registrar *cada* arquivo JavaScript neste bundle.
* [[yii\web\AssetBundle::cssOptions|cssOptions]]: especifica as opções que serão 
  passadas para o método [[yii\web\View::registerCssFile()]] quando for chamado 
  para registrar *cada* arquivo CSS neste bundle.
* [[yii\web\AssetBundle::publishOptions|publishOptions]]: especifica as opções 
  que serão passadas para o método [[yii\web\AssetManager::publish()]] quando for 
  chamado para publicar os arquivos de asset para um diretório Web. Este é usado 
  apenas se você especificar a propriedade [[yii\web\AssetBundle::sourcePath|sourcePath]].


### Localização dos Assets <span id="asset-locations"></span>

Os assets, com base em sua localização, podem ser classificados como:

* assets fonte: os arquivos de asset estão localizados juntos ao código fonte 
  PHP que não podem ser acessados diretamente na Web. Para utilizar os assets 
  fonte em uma página, devem ser copiados para um diretório Web a fim de 
  torna-los como os chamados assets publicados. Este processo é chamado de 
  *publicação de asset* que será descrito em detalhes ainda nesta seção.
* assets publicados: os arquivos de asset estão localizados em um diretório Web 
  e podendo, assim, serem acessados diretamente na Web.
* assets externos: os arquivos de asset estão localizados em um servidor Web 
  diferente do que a aplicação está hospedada. 

Ao definir uma classe de asset bundle e especificar a propriedade 
[[yii\web\AssetBundle::sourcePath|sourcePath]], significará que quaisquer assets 
listados usando caminhos relativos serão considerados como assets fonte. Se você 
não especificar esta propriedade, significará que estes assets serão assets 
publicados (portanto, você deve especificar as propriedades 
[[yii\web\AssetBundle::basePath|basePath]] e [[yii\web\AssetBundle::baseUrl|baseUrl]] 
para deixar o Yii saber onde eles estão localizados).

É recomendado que você coloque os assets da aplicação em um diretório Web para 
evitar o processo de publicação de assets desnecessários. É por isso que o 
`AppAsset` do exemplo anterior especifica a propriedade 
[[yii\web\AssetBundle::basePath|basePath]] ao invés da propriedade 
[[yii\web\AssetBundle::sourcePath|sourcePath]].

Para as [extensões](structure-extensions.md), por seus assets estarem localizados 
juntamente com seus códigos fonte em um diretório não acessível pela Web, você 
terá que especificar a propriedade [[yii\web\AssetBundle::sourcePath|sourcePath]] 
ao definir as classes de asset bundle.

> Observação: Não use o `@webroot/assets` como o [[yii\web\AssetBundle::sourcePath|caminho da fonte]]. 
  Este diretório é usado por padrão pelo [[yii\web\AssetManager|gerenciador de asset]] 
  para salvar os arquivos de asset publicados a partir de seu local de origem. 
  Qualquer conteúdo deste diretório será considerado como temporário e podem 
  estar sujeitos a serem deletados.


### Dependências de Assets <span id="asset-dependencies"></span>

Ao incluir vários arquivos CSS ou JavaScript em uma página Web, devem seguir uma 
determinada ordem para evitar problemas de sobrescritas. Por exemplo, se você 
estiver usando um widget JQuery UI em um página, você deve garantir que o arquivo 
JavaScript do JQuery esteja incluído antes que o arquivo JavaScript do JQuery UI. 
Chamamos esta tal ordenação de dependência entre os assets.

A dependência de assets são especificados principalmente através da propriedade 
[[yii\web\AssetBundle::depends]]. No exemplo do `AppAsset`, o asset bundle depende 
de outros dois asset bundles: [[yii\web\YiiAsset]] e [[yii\bootstrap\BootstrapAsset]], 
o que significa que os arquivos CSS e JavaScript do `AppAsset` serão incluídos 
*após* a inclusão dos arquivos dos dois bundles dependentes.

As dependências de assets são transitivas. Isto significa que se um asset bundle 
A depende de B e que o B depende de C, o A também dependerá de C.


### Opções do Asset <span id="asset-options"></span>

Você pode especificar as propriedades [[yii\web\AssetBundle::cssOptions|cssOptions]] 
e [[yii\web\AssetBundle::jsOptions|jsOptions]] para personalizar o modo que os 
arquivos CSS e JavaScript serão incluídos em uma página. Os valores destas propriedades 
serão passadas respectivamente para os métodos [[yii\web\View::registerCssFile()]] 
e [[yii\web\View::registerJsFile()]], quando forem chamados pela 
[view (visão)](structure-views.md) para incluir os arquivos CSS e JavaScript.

> Observação: As opções definidas em uma classe bundle aplicam-se para *todos* 
os arquivos CSS/JavaScript de um bundle. Se você quiser usar opções diferentes 
para arquivos diferentes, você deve criar asset bundles separados e usar um 
conjunto de opções para cada bundle.

Por exemplo, para incluir condicionalmente um arquivo CSS para navegadores IE9 
ou mais antigo, você pode usar a seguinte opção:

```php
public $cssOptions = ['condition' => 'lte IE9'];
```

Isto fara com que um arquivo CSS do bundle seja incluído usando as seguintes tags 
HTML:

```html
<!--[if lte IE9]>
<link rel="stylesheet" href="path/to/foo.css">
<![endif]-->
```

Para envolver as tags links do CSS dentro do `<noscript>`, você poderá configurar 
o `cssOptions` da seguinte forma,

```php
public $cssOptions = ['noscript' => true];
```

Para incluir um arquivo JavaScript na seção `<head>` de uma página (por padrão, 
os arquivos JavaScript são incluídos no final da seção `<body>`, use a seguinte 
opção:

```php
public $jsOptions = ['position' => \yii\web\View::POS_HEAD];
```

Por padrão, quando um asset bundle está sendo publicado, todo o conteúdo do 
diretório especificado pela propriedade [[yii\web\AssetBundle::sourcePath]] serão 
publicados. Para você personalizar este comportamento configurando a propriedade 
[[yii\web\AssetBundle::publishOptions|publishOptions]]. Por exemplo, para publicar 
apenas um ou alguns subdiretórios do [[yii\web\AssetBundle::sourcePath]], você 
pode fazer a seguinte classe de asset bundle.

```php
<?php
namespace app\assets;

use yii\web\AssetBundle;

class FontAwesomeAsset extends AssetBundle 
{
    public $sourcePath = '@bower/font-awesome'; 
    public $css = [ 
        'css/font-awesome.min.css', 
    ]; 
    
    public function init()
    {
        parent::init();
        $this->publishOptions['beforeCopy'] = function ($from, $to) {
            $dirname = basename(dirname($from));
            return $dirname === 'fonts' || $dirname === 'css';
        };
    }
}  
```

O exemplo anterior define um asset bundle para o 
[pacode de "fontawesome"](http://fontawesome.io/). Ao especificar a opção de 
publicação `beforeCopy`, apenas os subdiretórios `fonts` e `css` serão publicados.


### Assets do Bower e NPM<span id="bower-npm-assets"></span>

A maioria dos pacotes JavaScript/CSS são gerenciados pelo [Bower](http://bower.io/) 
e/ou [NPM](https://www.npmjs.org/).
Se sua aplicação ou extensão estiver usando um destes pacotes, é recomendado que 
você siga os passos a seguir para gerenciar os assets na biblioteca:

1. Modifique o arquivo de sua aplicação ou extensão e informe os pacotes na 
   entrada `require`. Você deve usar `bower-asset/PackageName` (para pacotes Bower) 
   ou `npm-asset/PackageName` (para pacotes NPM) para referenciar à biblioteca.
2. Crie uma classe asset bundle e informe os arquivos JavaScript/CSS que você 
   pretende usar em sua aplicação ou extensão. Você deve especificar a propriedade 
   [[yii\web\AssetBundle::sourcePath|sourcePath]] como `@bower/PackageName` ou 
   `@npm/PackageName`. Isto porque o Composer irá instalar os pacotes Bower ou 
   NPM no diretório correspondente a estas alias.

> Observação: Alguns pacotes podem colocar todos os seus arquivos distribuídos 
  em um subdiretório. Se este for o caso, você deve especificar o subdiretório 
  como o valor da propriedade [[yii\web\AssetBundle::sourcePath|sourcePath]]. 
  Por exemplo, o [[yii\web\JqueryAsset]] usa `@bower/jquery/dist` ao invés de 
  `@bower/jquery`.


## Usando Asset Bundles <span id="using-asset-bundles"></span>

Para usar um asset bundle, registre uma [view (visão)](structure-views.md) 
chamando o método [[yii\web\AssetBundle::register()]]. Por exemplo, no template 
da view (visão) você pode registrar um asset bundle conforme o exemplo a seguir:

```php
use app\assets\AppAsset;
AppAsset::register($this);  // $this representa o objeto da view (visão)
```

> Informação: O método [[yii\web\AssetBundle::register()]] retorna um objeto 
  asset bundle contendo informações sobre os assets publicados, tais como o 
  [[yii\web\AssetBundle::basePath|basePath]] ou [[yii\web\AssetBundle::baseUrl|baseUrl]].

Se você estiver registrando um asset bundle em outros lugares, você deve fornecer 
o objeto da view (visão) necessário. Por exemplo, para registrar um asset bundle 
em uma classe [widget](structure-widgets.md), você pode obter o objeto da view 
(visão) pelo `$this->view`.

Quando um asset bundle for registrado em um view (visão), o Yii registrará todos 
os seus asset bundles dependentes. E, se um asset bundle estiver localizado em 
um diretório inacessível pela Web, será publicado em um diretório Web.
Em seguida, quando a view (visão) renderizar uma página, será gerado as tags 
`<link>` e `<script>` para os arquivos CSS e JavaScript informados nos bundles 
registrados. A ordem destas tags são determinados pelas dependências dos bundles 
registrados e pela ordem dos assets informados nas propriedades 
[[yii\web\AssetBundle::css]] e [[yii\web\AssetBundle::js]].


### Personalizando os Asset Bundles <span id="customizing-asset-bundles"></span>

O Yii gerencia os asset bundles através do componente de aplicação chamado 
`assetManager` que é implementado pelo [[yii\web\AssetManager]]. 
Ao configurar a propriedade [[yii\web\AssetManager::bundles]], é possível 
personalizar o comportamento de um asset bundle.
Por exemplo, o asset bundle padrão [[yii\web\JqueryAsset]] usa o arquivo 
`jquery.js` do pacote JQuery instalado pelo Bower. Para melhorar a disponibilidade 
e o desempenho, você pode querer usar uma versão hospedada pelo Google. 
Isto pode ser feito configurando o `assetManager` na configuração da aplicação 
conforme o exemplo a seguir:

```php
return [
    // ...
    'components' => [
        'assetManager' => [
            'bundles' => [
                'yii\web\JqueryAsset' => [
                    'sourcePath' => null,   // do not publish the bundle
                    'js' => [
                        '//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js',
                    ]
                ],
            ],
        ],
    ],
];
```

Você pode configurar diversos asset bundles de forma semelhante através da 
propriedade [[yii\web\AssetManager::bundles]]. As chaves do array devem ser os 
nomes das classes (sem a barra invertida) dos asset bundles e os valores do 
array devem corresponder aos [arrays de configuração](concept-configurations.md).

> Dica: Você pode, de forma condicional, escolher os assets que queira usar em 
> um asset bundle. O exemplo a seguir mostra como usar o `jquery.js` no ambiente 
> de desenvolvimento e o `jquery.min.js` em outra situação:
>
> ```php
> 'yii\web\JqueryAsset' => [
>     'js' => [
>         YII_ENV_DEV ? 'jquery.js' : 'jquery.min.js'
>     ]
> ],
> ```

Você pode desabilitar um ou vários asset bundles, associando `false` aos nomes 
dos asset bundles que queira ser desabilitado. Ao registrar um asset bundle 
desabilitado em um view (visão), nenhuma das suas dependências serão registradas 
e a view (visão) também não incluirá quaisquer assets do bundle na página renderizada.
Por exemplo, para desabilitar o [[yii\web\JqueryAsset]], você pode usando a 
seguinte configuração.

```php
return [
    // ...
    'components' => [
        'assetManager' => [
            'bundles' => [
                'yii\web\JqueryAsset' => false,
            ],
        ],
    ],
];
```

Você também pode desabilitar *todos* os asset bundles definindo o 
[[yii\web\AssetManager::bundles]] como `false`.


### Mapeando Asset <span id="asset-mapping"></span>

Às vezes, você pode querer "corrigir" os caminhos dos arquivos de asset 
incorretos/incompatíveis em vários asset bundles. Por exemplo, o bundle A usa o 
`jquery.min.js` com a versão 1.11.1 e o bundle B usa o `jquery.js` com a versão 
2.1.1. Embora você possa corrigir o problema personalizando cada bundle, existe 
um modo mais simples usando o recurso de *mapeamento de asset* para mapear todos 
os assets incorretos para os assets desejados de uma vez. Para fazer isso, 
configure a propriedade [[yii\web\AssetManager::assetMap]] conforme o exemplo a 
seguir:

```php
return [
    // ...
    'components' => [
        'assetManager' => [
            'assetMap' => [
                'jquery.js' => '//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js',
            ],
        ],
    ],
];
```

As chaves do array [[yii\web\AssetManager::assetMap|assetMap]] são os nomes dos 
assets que você deseja corrigir e o valor são os caminhos dos assets desejados. 
Ao registrar um asset bundle em uma view (visão), cada arquivo de asset relativo 
aos arrays [[yii\web\AssetBundle::css|css]] e [[yii\web\AssetBundle::js|js]] 
serão examinados a partir deste mapeamento.
Se qualquer uma das chaves forem encontradas para serem a última parte de um 
arquivo de asset (que é prefixado com o [[yii\web\AssetBundle::sourcePath]] se 
disponível), o valor correspondente substituirá o asset a ser registrado na view 
(visão). Por exemplo, o arquivo de asset `my/path/to/jquery.js` corresponde a 
chave a chave `jquery.js`.

> Observação: Apenas os assets especificados usando caminhos relativos estão  
  sujeitos ao mapeamento de assets. O caminho dos assets devem ser URLs absolutas 
   ou caminhos relativos ao caminho da propriedade [[yii\web\AssetManager::basePath]].


### Publicação de Asset <span id="asset-publishing"></span>

Como mencionado anteriormente, se um asset bundle for localizado em um diretório
 que não é acessível pela Web, os seus assets serão copiados para um diretório 
Web quando o bundle estiver sendo registrado na view (visão). Este processo é 
chamado de *publicação de asset* e é feito automaticamente pelo 
[[yii\web\AssetManager|gerenciador de asset]].

Por padrão, os assets são publicados para o diretório `@webroot/assets` que 
corresponde a URL `@web/assets`. Você pode personalizar este local configurando 
as propriedades [[yii\web\AssetManager::basePath|basePath]] e 
[[yii\web\AssetManager::baseUrl|baseUrl]].

Ao invés de publicar os assets pela cópia de arquivos, você pode considerar o uso 
de links simbólicos, caso o seu sistema operacional e o servidor Web permita-os. 
Este recurso pode ser habilitado definindo o 
[[yii\web\AssetManager::linkAssets|linkAssets]] como true.

```php
return [
    // ...
    'components' => [
        'assetManager' => [
            'linkAssets' => true,
        ],
    ],
];
```

Com a configuração acima, o gerenciador de asset irá criar um link simbólico para 
o caminho fonte de um asset bundle quando estiver sendo publicado. Isto é mais 
rápido que a cópia de arquivos e também pode garantir que os assets publicados 
estejam sempre atualizados.

### Cache Busting <span id="cache-busting"></span>

Para aplicações Web que estam rodando no modo produção, é uma prática comum habilitar
o cache HTTP paraassets e outros recursos estáticos. A desvantagem desta prática é que 
sempre que você modificar um asset e implantá-lo em produção, um cliente pode ainda
estar usando a versão antiga, devido ao cache HTTP. Para superar esta desvantagem, 
você pode utilizar o recurso cache busting, que foi implementado na versão 2.0.3, 
configurando o [[yii\web\AssetManager]] como mostrado a seguir:
  
```php
return [
    // ...
    'components' => [
        'assetManager' => [
            'appendTimestamp' => true,
        ],
    ],
];
```

Ao fazer isto, a URL de cada asset publicado será anexada ao seu último horário de 
modificação. Por exemplo, a URL do `yii.js` pode parecer com `/assets/5515a87c/yii.js?v=1423448645"`,
onde o parâmetro `V` representa o último horário de modificação do arquivo `yii.js`.
Agora se você modificar um asset, a sua URL será alterada, fazendo com que o cliente
busque a versão mais recente do asset.

## Asset Bundles de Uso Comum <span id="common-asset-bundles"></span>

O código nativo do Yii definiu vários asset bundles. Entre eles, os bundles a 
seguir são de uso comum e podem ser referenciados em sua aplicação ou no código 
de extensão.

- [[yii\web\YiiAsset]]: Inclui principalmente o arquivo `yii.js` que implementa 
  um mecanismo para organizar os códigos JavaScript em módulos. Ele também fornece 
  um suporte especial para os atributos `data-method` e `data-confirm` e outros 
  recursos úteis.
- [[yii\web\JqueryAsset]]: Inclui o arquivo `jquery.js` do pacote jQuery do Bower.
- [[yii\bootstrap\BootstrapAsset]]: Inclui o arquivo CSS do framework Twitter 
  Bootstrap.
- [[yii\bootstrap\BootstrapPluginAsset]]: Inclui o arquivo JavaScript do framework 
  Twitter Bootstrap para dar suporte aos plug-ins JavaScript do Bootstrap.
- [[yii\jui\JuiAsset]]: Inclui os arquivos CSS e JavaScript do biblioteca jQuery UI.

Se o seu código depende do jQuery, jQuery UI ou Bootstrap, você deve usar estes 
asset bundles predefinidos ao invés de criar suas próprias versões. Se a definição 
padrão destes bundles não satisfazer o que precisa, você pode personaliza-los 
conforme descrito na subseção [Personalizando os Asset Bundles](#customizing-asset-bundles). 


## Conversão de Assets <span id="asset-conversion"></span>

Ao invés de escrever diretamente códigos CSS e/ou JavaScript, os desenvolvedores 
geralmente os escrevem em alguma sintaxe estendida e usam ferramentas especiais 
para converte-los em CSS/JavaScript. Por exemplo, para o código CSS você pode 
usar [LESS](http://lesscss.org/) ou [SCSS](http://sass-lang.com/); e para o 
JavaScript você pode usar o [TypeScript](http://www.typescriptlang.org/).

Você pode listar os arquivos de asset em sintaxe estendida nas propriedades 
[[yii\web\AssetBundle::css|css]] e [[yii\web\AssetBundle::js|js]] de um asset 
bundle. Por exemplo, 

```php
class AppAsset extends AssetBundle
{
    public $basePath = '@webroot';
    public $baseUrl = '@web';
    public $css = [
        'css/site.less',
    ];
    public $js = [
        'js/site.ts',
    ];
    public $depends = [
        'yii\web\YiiAsset',
        'yii\bootstrap\BootstrapAsset',
    ];
}
```

Ao registrar um determinado asset bundle em uma view (visão), o 
[[yii\web\AssetManager|gerenciador de asset]] automaticamente rodará as 
ferramentas de pré-processamento para converter os assets de sintaxe estendida 
em CSS/JavaScript. Quando a view (visão) finalmente renderizar uma página, será 
incluído os arquivos CSS/JavaScript convertidos ao invés dos arquivos de assets 
originais em sintaxe estendida.

O Yii usa as extensões dos nomes de arquivos para identificar se é um asset com 
sintaxe estendida. Por padrão, o Yii reconhecerá as seguintes sintaxes e extensões 
de arquivos:

- [LESS](http://lesscss.org/): `.less`
- [SCSS](http://sass-lang.com/): `.scss`
- [Stylus](http://learnboost.github.io/stylus/): `.styl`
- [CoffeeScript](http://coffeescript.org/): `.coffee`
- [TypeScript](http://www.typescriptlang.org/): `.ts`

O Yii conta com ferramentas de pré-processamento instalados para converter os 
assets. Por exemplo, para usar o [LESS](http://lesscss.org/) você deve instalar 
o comando de pré-processamento `lessc`.

Você pode personalizar os comandos de pré-processamento e o da sintaxe estendida 
suportada configurando o [[yii\web\AssetManager::converter]] conforme o exemplo 
a seguir:

```php
return [
    'components' => [
        'assetManager' => [
            'converter' => [
                'class' => 'yii\web\AssetConverter',
                'commands' => [
                    'less' => ['css', 'lessc {from} {to} --no-color'],
                    'ts' => ['js', 'tsc --out {to} {from}'],
                ],
            ],
        ],
    ],
];
```

No exemplo acima, especificamos a sintaxe estendida suportada pela propriedade 
[[yii\web\AssetConverter::commands]]. As chaves do array correspondem a extensão 
dos arquivos (sem o ponto a esquerda) e o valor do array possui a extensão do 
arquivo de asset resultante e o comando para executar a conversão do asset. Os 
tokens `{from}` e `{to}` nos comandos serão substituídos pelo caminho do arquivo 
de asset fonte e pelo caminho do arquivo de asset de destino.

> Informação: Existem outros modos de trabalhar com assets em sintaxe estendida, 
  além do descrito acima. Por exemplo, você pode usar ferramentas de compilação 
  tais como o [grunt](http://gruntjs.com/) para monitorar e automatizar a conversão 
  de assets em sintaxe estendidas. Neste caso, você deve listar os arquivos de 
  CSS/JavaScript resultantes nos asset bundles ao invés dos arquivos originais.


## Combinando e Comprimindo Assets <span id="combining-compressing-assets"></span>

Uma página Web pode incluir muitos arquivos CSS e/ou JavaScript. Para reduzir o 
número de requisições HTTP e o tamanho total de downloads destes arquivos, uma 
prática comum é combinar e comprimir vários arquivos CSS/JavaScript em um ou em 
poucos arquivos e em seguida incluir estes arquivos comprimidos nas páginas Web 
ao invés dos originais.

> Informação: A combinação e compressão de assets normalmente são necessárias 
  quando uma aplicação está em modo de produção. No modo de desenvolvimento, 
  usar os arquivos CSS/JavaScript originais muitas vezes são mais convenientes 
  para depuração.

A seguir, apresentaremos uma abordagem para combinar e comprimir arquivos de 
assets sem precisar modificar o código da aplicação existente.

1. Localize todos os asset bundles em sua aplicação que você deseja combinar e 
   comprimir.
2. Divida estes bundles em um ou alguns grupos. Observe que cada bundle pode 
   apenas pertencer a um único grupo.
3. Combinar/Comprimir os arquivos CSS de cada grupo em um único arquivo. Faça 
   isto de forma semelhante para os arquivos JavaScript.
4. Defina um novo asset bundle para cada grupo:
   * Defina as propriedade [[yii\web\AssetBundle::css|css]] e 
     [[yii\web\AssetBundle::js|js]] com os arquivos CSS e JavaScript combinados, 
     respectivamente.
   * Personalize os asset bundles de cada grupo definindo as suas propriedades 
     [[yii\web\AssetBundle::css|css]] e [[yii\web\AssetBundle::js|js]] como vazias 
     e definindo a sua propriedade [[yii\web\AssetBundle::depends|depends]] para 
     ser o novo asset bundle criado para o grupo.

Usando esta abordagem, quando você registrar um asset bundle em uma view (visão), 
fará com que registre automaticamente o novo asset bundle do grupo que o bundle 
original pertence. E, como resultado, os arquivos de asset combinados/comprimidos 
serão incluídos na página, ao invés dos originais.


### Um Exemplo <span id="example"></span>

Vamos usar um exemplo para explicar melhor o exemplo acima: 

Assuma que sua aplicação possua duas páginas, X e Y. A página X usa os asset 
bundles A, B e C, enquanto a página Y usa os asset bundles B, C e D. 

Você tem duas maneiras de dividir estes asset bundles. Uma delas é a utilização 
de um único grupo para incluir todos os asset bundles e a outra é colocar o A no 
Grupo X, o D no Grupo Y e (B, C) no Grupo S. Qual deles é o melhor? Isto depende. 
A primeira maneira tem a vantagem de ambas as páginas compartilharem os mesmos 
arquivos CSS e JavaScript combinados, o que torna o cache HTTP mais eficaz. Por 
outro lado, pelo fato de um único grupo conter todos os bundles, o tamanho dos 
arquivos CSS e JavaScript combinados será maior e, assim, aumentará o tempo de 
carregamento inicial. Para simplificar este exemplo, vamos usar a primeira 
maneira, ou seja, usaremos um único grupo para conter todos os bundles.

> Informação: Dividir os asset bundles em grupos não é uma tarefa trivial. 
Geralmente requer que análise sobre o real trafego de dados de diversos assets 
em páginas diferentes. Para começar, você pode usar um único grupo para simplificar.

Use as ferramentas existentes (por exemplo, 
[Closure Compiler](https://developers.google.com/closure/compiler/), 
[YUI Compressor](https://github.com/yui/yuicompressor/)) para combinar e 
comprimir os arquivos CSS e JavaScript em todos os bundles. Observer que os 
arquivos devem ser combinados na ordem que satisfaça as dependências entre os 
bundles. Por exemplo, se o bundle A depende do B e que dependa tanto do C quanto 
do D, você deve listar os arquivos de asset a partir do C e D, em seguida pelo B 
e finalmente pelo A.

Depois de combinar e comprimir, obteremos um arquivo CSS e um arquivo JavaScript. 
Suponha que os arquivos serão chamados de `all-xyz.css` e `all-xyz.js`, onde o 
`xyz` significa um timestamp ou um hash que é usado para criar um nome de arquivo 
único para evitar problemas de cache HTTP.

Nós estamos na última etapa agora. Configure o 
[[yii\web\AssetManager|gerenciador de asset]] como o seguinte na configuração da 
aplicação:

```php
return [
    'components' => [
        'assetManager' => [
            'bundles' => [
                'all' => [
                    'class' => 'yii\web\AssetBundle',
                    'basePath' => '@webroot/assets',
                    'baseUrl' => '@web/assets',
                    'css' => ['all-xyz.css'],
                    'js' => ['all-xyz.js'],
                ],
                'A' => ['css' => [], 'js' => [], 'depends' => ['all']],
                'B' => ['css' => [], 'js' => [], 'depends' => ['all']],
                'C' => ['css' => [], 'js' => [], 'depends' => ['all']],
                'D' => ['css' => [], 'js' => [], 'depends' => ['all']],
            ],
        ],
    ],
];
```

Como foi explicado na subseção [Personalizando os Asset Bundles](#customizing-asset-bundles), 
a configuração acima altera o comportamento padrão de cada bundle. Em particular, 
os bundles A, B, C e D não precisam mais de arquivos de asset.
Agora todos dependem do bundle `all` que contém os arquivos `all-xyz.css` e 
`all-xyz.js` combinados. Consequentemente, para a página X, ao invés de incluir 
os arquivos fontes originais dos bundles A, B e C, apenas estes dois arquivos 
combinados serão incluídos; a mesma coisa acontece com a página Y.

Existe um truque final para fazer o trabalho da abordagem acima de forma mais 
simples. Ao invés de modificar diretamente o arquivo de configuração da aplicação, 
você pode colocar o array de personalização do bundle em um arquivo separado e 
condicionalmente incluir este arquivo na configuração da aplicação. Por exemplo, 

```php
return [
    'components' => [
        'assetManager' => [
            'bundles' => require(__DIR__ . '/' . (YII_ENV_PROD ? 'assets-prod.php' : 'assets-dev.php')),  
        ],
    ],
];
```

Ou seja, o array de configuração do asset bundle será salvo no arquivo 
`assets-prod.php` quando estiver em modo de produção e o arquivo `assets-dev.php` 
quando não estiver em produção.


### Usando o Comando `asset` <span id="using-asset-command"></span>

O Yii fornece um comando console chamado `asset` para automatizar a abordagem que 
acabamos de descrever.

Para usar este comando, você deve primeiro criar um arquivo de configuração para 
descrever quais asset bundles devem ser combinados e como devem ser agrupados. 
Você pode usar o subcomando `asset/template` para gerar um template para que 
possa modificá-lo para atender as suas necessidades.

```
yii asset/template assets.php
```

O comando gera um arquivo chamado `assets.php` no diretório onde foi executado. 
O conteúdo deste arquivo assemelha-se ao seguinte:

```php
<?php
/**
 * Arquivo de configuração para o comando console "yii asset".
 * Observer que no ambiente de console, alguns caminhos de alias como '@webroot' e o '@web' podem não existir.
 * Por favor, defina os caminhos de alias inexistentes.
 */
return [
    // Ajuste do comando/call-back para a compressão os arquivos JavaScript:
    'jsCompressor' => 'java -jar compiler.jar --js {from} --js_output_file {to}',
    // Ajuste de comando/callback para a compressão dos arquivos CSS:
    'cssCompressor' => 'java -jar yuicompressor.jar --type css {from} -o {to}',
    // A lista de asset bundles que serão comprimidos:
    'bundles' => [
        // 'yii\web\YiiAsset',
        // 'yii\web\JqueryAsset',
    ],
    // Asset bundle do resultado da compressão:
    'targets' => [
        'all' => [
            'class' => 'yii\web\AssetBundle',
            'basePath' => '@webroot/assets',
            'baseUrl' => '@web/assets',
            'js' => 'js/all-{hash}.js',
            'css' => 'css/all-{hash}.css',
        ],
    ],
    // Configuração do gerenciados de asset:
    'assetManager' => [
    ],
];
```

Você deve modificar este arquivo e especificar quais bundles você deseja combinar 
na opção `bundles`. Na opção `targets` você deve especificar como os bundles 
devem ser divididos em grupos. Você pode especificar um ou vários grupos, como 
mencionado anteriormente.

> Observação: Como as alias `@webroot` e `@web` não estão disponíveis na aplicação 
  console, você deve defini-los explicitamente na configuração.

Os arquivos JavaScript são combinados, comprimidos e escritos no arquivo 
`js/all-{hash}.js` onde {hash} será substituído pelo hash do arquivo resultante.

As opções `jsCompressor` e `cssCompressor` especificam os comando ou callbacks 
PHP para realizar a combinação/compressão do JavaScript e do CSS. Por padrão, o 
Yii usa o [Closure Compiler](https://developers.google.com/closure/compiler/) 
para combinar os arquivos JavaScript e o 
[YUI Compressor](https://github.com/yui/yuicompressor/) para combinar os arquivos CSS.
Você deve instalar estas ferramentas manualmente ou ajustar estas opções para 
usar as suas ferramentas favoritas.

Com o arquivo de configuração, você pode executar o comando `asset` para combinar
e comprimir os arquivos de asset e em seguida gerar um novo arquivo de configuração 
de asset bundle `assets-prod.php`:

```
yii asset assets.php config/assets-prod.php
```

O arquivo de configuração gerado pode ser incluído na configuração da aplicação, 
conforme descrito na última subseção.


> Informação: O uso do comando `asset` não é a única opção para automatizar o 
  processo de combinação e compressão de asset. Você pode usar a excelente 
  ferramenta chamada [grunt](http://gruntjs.com/) para atingir o mesmo objetivo.

### Agrupando Asset Bundles <span id="grouping-asset-bundles"></span>

Na última subseção, nós explicamos como combinar todos os asset bundles em um
único bundle, a fim de minimizar as requisições HTTP de arquivos de asset referenciados
em uma aplicação. Porém, isto nem sempre é desejável na prática. Por exemplo, imagine 
que sua aplicação possua um "front end", bem como um "back end", cada um possuindo um 
conjunto diferente de JavaScript e CSS. Neste caso, combinando todos os asset bundles
de ambas as extremidades em um único bundle não faz sentido, porque os asset bundles 
pata o "front end" não são utilizados pelo "back end" e seria um desperdício de uso 
de banda de rede para enviar os assets do "back end" quando uma página de "front end"
for solicitada.

Para resolver este problema, você pode dividir asset bundles e, grupos e combinar 
asset bundles para cada grupo. A configuração a seguir mostra como pode agrupar 
os asset bundles:

```php
return [
    ...
    // Especifique o bundle de saída com os grupos:
    'targets' => [
        'allShared' => [
            'js' => 'js/all-shared-{hash}.js',
            'css' => 'css/all-shared-{hash}.css',
            'depends' => [
                // Inclua todos os asset que serão compartilhados entre o 'backend' e o 'frontend'
                'yii\web\YiiAsset',
                'app\assets\SharedAsset',
            ],
        ],
        'allBackEnd' => [
            'js' => 'js/all-{hash}.js',
            'css' => 'css/all-{hash}.css',
            'depends' => [
                // Inclua apenas os assets do 'backend':
                'app\assets\AdminAsset'
            ],
        ],
        'allFrontEnd' => [
            'js' => 'js/all-{hash}.js',
            'css' => 'css/all-{hash}.css',
            'depends' => [], // Inclua todos os asset restantes
        ],
    ],
    ...
];
```

Como você pode ver, os asset bundles são divididos em três grupos: `allShared`, `allBackEnd` e `allFrontEnd`.
Cada um deles dependem de um conjunto de asset bundles. Por exemplo, o `allBackEnd` depende de `app\assets\AdminAsset`.
Ao executar o comando `asset` com essa configuração, será combinado os asset bundles de acordo com as especificações acima.

> Informação: Voce pode deixar a configuração `depends` em branco para um determinado bundle.
Ao fazer isso, esse asset bundle dependerá de todos os asset bundles restantes que outros
determinados bundles não dependam.