Merge pull request #6729 from davidsonalencar/master

docs/guide-pt-BR/structure-widgets.md

+Widgets
+=======
+
+Os widgets são blocos de construção reutilizáveis usados nas 
+[views (visões)](structure-views.md) 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
+<?php
+use yii\jui\DatePicker;
+?>
+<?= DatePicker::widget(['name' => 'date']) ?>
+```
+
+Existe uma quantidade considerável de widgets empacotados no Yii, como o 
+[[yii\widgets\ActiveForm|active form]], o [[yii\widgets\Menu|menu]], o 
+[jQuery UI widgets](widget-jui.md), o [Twitter Bootstrap widgets](widget-bootstrap.md), 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 <a name="using-widgets"></a>
+
+Os widgets são usados principalmente nas [views (visões)](structure-views.md). 
+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](concept-configurations.md) 
+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
+<?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
+<?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 <a name="creating-widgets"></a>
+
+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.
+
+```php
+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
+<?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.
+
+```php
+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
+<?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)](structure-views.md) e chamar o 
+[[yii\base\Widget::render()]] para renderizá-lo. Por exemplo,
+
+```php
+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 <a name="best-practices"></a>
+
+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)](structure-views.md).
+
+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](structure-assets.md), 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)](structure-views.md). 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