# Widgets ¶

Os widgets são blocos de construção reutilizáveis usados nas views (visões) para criar e configurar complexos elementos de interface do usuário sob uma modelagem orientada a objetos. Por exemplo, um widget datapicker pode gerar um calendário que permite aos usuários selecionarem uma data que desejam inserir em um formulário. Tudo o que você precisa fazer é apenas inserir um código na view (visão) conforme o seguinte:

    <?php
    use yii\jui\DatePicker;
    ?>
    <?= DatePicker::widget(['name' => 'date']) ?>

Existe uma quantidade considerável de widgets empacotados no Yii, como o active form, o menu, o jQuery UI widgets, o Twitter Bootstrap widgets, etc. A seguir, iremos introduzir os conhecimentos básicos sobre os widgets. Por favor, consulte a documentação de classes da API se você quiser saber mais sobre o uso de um determinado widget.

## Usando Widgets ¶

Os widgets são usados principalmente nas views (visões). Você pode chamar o método yii\base\Widget::widget() para usar um widget em uma view (visão). O método possui um array de configuração para inicializar o widget e retornar o resultado da renderização do widget. Por exemplo, o código a seguir insere um widget datapicker configurado para usar o idioma Russo e manter a data selecionada no atributo `from_date` do `$model`.

    <?php
    use yii\jui\DatePicker;
    ?>
    <?= DatePicker::widget([
        'model' => $model,
        'attribute' => 'from_date',
        'language' => 'ru',
        'clientOptions' => [
            'dateFormat' => 'yy-mm-dd',
        ],
    ]) ?>

Alguns widgets podem ter um bloco de conteúdo que deve ser colocado entre as chamadas dos métodos yii\base\Widget::begin() e yii\base\Widget::end(). Por exemplo, o código a seguir usa o widget yii\widgets\ActiveForm para gerar um formulário de login. O widget irá gerar as tags de abertura e de fechamento do `<form>` respectivamente nos lugares onde os métodos `begin()` e `end()` foram chamados. Qualquer conteúdo entre estes métodos serão renderizados entre as tags de abertura e de fechamento do `<form>`.

    <?php
    use yii\widgets\ActiveForm;
    use yii\helpers\Html;
    ?>

    <?php $form = ActiveForm::begin(['id' => 'login-form']); ?>

        <?= $form->field($model, 'username') ?>

        <?= $form->field($model, 'password')->passwordInput() ?>

        <div class="form-group">
            <?= Html::submitButton('Login') ?>
        </div>

    <?php ActiveForm::end(); ?>

Observe que ao contrário do yii\base\Widget::widget() que retorna a renderização de um widget, o método yii\base\Widget::begin() retorna uma instância do widget que pode ser usado para construir o seu conteúdo.

## Criando Widgets ¶

Para criar um widget, estenda a classe yii\base\Widget e sobrescreva os métodos yii\base\Widget::init() e/ou yii\base\Widget::run(). Normalmente, o método `init()` deve conter os códigos que normalizam as propriedade do widget, enquanto o método `run()` deve conter o código que gera o resultado da renderização do widget. O resultado da renderização pode ser feito diretamente dando "echo" ou pelo retorno de uma string no método `run()`.

No exemplo a seguir, o `HelloWidget` codifica o HTML e exibe o conteúdo atribuído à sua propriedade `message`. Se a propriedade não for definida, será exibido "Hello World" como padrão.

    namespace app\components;

    use yii\base\Widget;
    use yii\helpers\Html;

    class HelloWidget extends Widget
    {
        public $message;

        public function init()
        {
            parent::init();
            if ($this->message === null) {
                $this->message = 'Hello World';
            }
        }

        public function run()
        {
            return Html::encode($this->message);
        }
    }

Para usar este widget, simplesmente insira o código a seguir em uma view (visão):

    <?php
    use app\components\HelloWidget;
    ?>
    <?= HelloWidget::widget(['message' => 'Good morning']) ?>

O `HelloWidget` abaixo é uma variante que pega o conteúdo entre as chamadas de `begin()` e `end()`, codifica o HTML e em seguida os exibe.

    namespace app\components;

    use yii\base\Widget;
    use yii\helpers\Html;

    class HelloWidget extends Widget
    {
        public function init()
        {
            parent::init();
            ob_start();
        }

        public function run()
        {
            $content = ob_get_clean();
            return Html::encode($content);
        }
    }

Como você pode ver, o buffer de saída do PHP é iniciado no método `init()` para que qualquer conteúdo entre as chamadas de `init()` e `run()` possam ser capturadas, processadas e retornadas em `run()`.

> Informação: Ao chamar o yii\base\Widget::begin(), uma nova instância do widget será criada e o método `init()` será chamado logo ao final de seu construtor. Ao chamar o yii\base\Widget::end(), o método `run()` será chamado cujo o resultado da renderização será dado echo pelo `end()`.

O código a seguir mostra como você pode usar esta nova variante do `HelloWidget`:

    <?php
    use app\components\HelloWidget;
    ?>
    <?php HelloWidget::begin(); ?>

        um conteúdo qualquer...

    <?php HelloWidget::end(); ?>

Algumas vezes, um widget pode precisar renderizar um grande conteúdo. Enquanto você pode inserir todo este conteúdo no método `run()`, uma boa prática é colocá-lo em uma view (visão) e chamar o yii\base\Widget::render() para renderizá-lo. Por exemplo,

    public function run()
    {
        return $this->render('hello');
    }

Por padrão, as views (visões) para um widget devem ser armazenadas em arquivos sob o diretório `WidgetPath/views`, onde o `WidgetPath` significa o diretório que contém os arquivo da classe do widget. Portanto, o exemplo anterior irá renderizar o arquivo de view (visão) `@app/components/views/hello.php`, assumindo que a classe widget está localizada sob o diretório `@app/components`. Você pode sobrescrever o método yii\base\Widget::getViewPath() para personalizar o diretório que conterá os arquivos de views (visões) do widget.

## Boas Práticas ¶

Os widgets são uma maneira orientada a objetos de reutilizar códigos de view (visão).

Ao criar os widgets, você ainda deve seguir o padrão MVC. Em geral, você deve manter a lógica nas classes widgets e manter as apresentações nas views (visões).

Os widgets devem ser projetados para serem autossuficientes. Isto é, ao utilizar um widget, você deverá ser capaz de removê-lo de uma view (visão) sem fazer qualquer outra coisa. Isto pode ser complicado se um widget requerer recursos externos, tais como CSS, JavaScript, imagens, etc. Felizmente, o Yii fornece o suporte para asset bundles, que pode ser utilizado para resolver este problema.

Quando um widget contiver somente código de view (visão), será bem semelhante a uma view (visão). Na verdade, neste caso, a única diferença é que um widget é uma classe para ser redistribuída, enquanto uma view é apenas um simples script PHP que você preferirá manter em sua aplicação