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
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
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
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
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
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
```
Para envolver as tags links do CSS dentro do `