<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.layout.quickstart">
    <title>Guia Rápido Zend_Layout</title>

    <para>
        Há dois casos de uso primários para <classname>Zend_Layout</classname>: com o
        <acronym>MVC</acronym> do Zend Framework, e sem.
    </para>

    <sect2 id="zend.layout.quickstart.layouts">
        <title>Scripts de Layout</title>

        <para>
            Em ambos os casos, entretanto, você precisará criar um script de layout.
            Scripts de layout simplesmente utilizam <classname>Zend_View</classname> (ou
            qualquer outra implementação de view que você esteja usando). Variáveis de layout são
            registradas com um <link linkend="zend.view.helpers.initial.placeholder">marcador</link>
            <classname>Zend_Layout</classname>, e podem ser acessadas via helper de marcador
            ou buscando-as como propriedades de objeto do objeto layout via helper de layout.
        </para>

        <para>
            Como um exemplo:
        </para>

        <programlisting language="php"><![CDATA[
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Meu Site</title>
</head>
<body>
<?php
    // busca a chave 'content' usando um helper de layout:
    echo $this->layout()->content;

    // busca a chave 'foo' usando um helper marcador:
    echo $this->placeholder('Zend_Layout')->foo;

    // busca o objeto de layout e recupera várias chaves dele:
    $layout = $this->layout();
    echo $layout->bar;
    echo $layout->baz;
?>
</body>
</html>
]]></programlisting>

        <para>
            Como <classname>Zend_Layout</classname> utiliza <classname>Zend_View</classname> para
            renderização, Você pode também usar quaisquer helpers de view registradas, e também
            ter acesso a quaisquer variáveis de view associadas. Particularmente útil são os
            vários <link linkend="zend.view.helpers.initial.placeholder">helpers marcadores</link>,
            que permitem a você recuperar conteúdo para áreas tais como a seção &lt;head&gt;,
            navegação, etc.:
        </para>

        <programlisting language="php"><![CDATA[
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <?php echo $this->headTitle() ?>
    <?php echo $this->headScript() ?>
    <?php echo $this->headStyle() ?>
</head>
<body>
    <?php echo $this->render('header.phtml') ?>

    <div id="nav"><?php echo $this->placeholder('nav') ?></div>

    <div id="content"><?php echo $this->layout()->content ?></div>

    <?php echo $this->render('footer.phtml') ?>
</body>
</html>
]]></programlisting>
    </sect2>

    <sect2 id="zend.layout.quickstart.mvc">
        <title>Usando Zend_Layout com o MVC do Zend Framework</title>

        <para>
            <classname>Zend_Controller</classname> oferece um rico conjunto de funcionalidades
            para extensão por meio de seus <link
            linkend="zend.controller.plugins">front controller plugins</link> e <link
            linkend="zend.controller.actionhelpers">action controller helpers</link>.
            <classname>Zend_View</classname> também tem <link
            linkend="zend.view.helpers">helpers</link>. <classname>Zend_Layout</classname>
            toma vantagem desses diversos pontos de extensão quando usado com os
            componentes <acronym>MVC</acronym>.
        </para>

        <para>
            <methodname>Zend_Layout::startMvc()</methodname> cria uma instância de
            <classname>Zend_Layout</classname> com qualquer configuração opcional que
            você fornecer. Ele registra então um front controller plugin que renderiza o
            layout com qualquer conteúdo de aplicação uma vez que o laço de despacho foi feito,
            e registra um action helper para permitir o acesso ao objeto layout a partir de seus
            action controllers. Adicionalmente, você pode a qualquer tempo pegar a instância de
            dentro de um view script usando o view helper <classname>Layout</classname>.
        </para>

        <para>
            Primeiro, dê uma olhada em como inicializar <classname>Zend_Layout</classname>
            para uso com o <acronym>MVC</acronym>:
        </para>

        <programlisting language="php"><![CDATA[
// Em seu bootstrap:
Zend_Layout::startMvc();
]]></programlisting>

        <para>
            <methodname>startMvc()</methodname> pode tomar uma matriz opcional de opções ou
            um objeto <classname>Zend_Config</classname> para customizar a instância; essas
            opções são detalhadas <link linkend="zend.layout.options">nesta seção</link>.
        </para>

        <para>
            Em um action controller, você pode então acessar a instância de layout como um action
            helper:
        </para>

        <programlisting language="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
    public function barAction()
    {
        // desabilita layouts para este action:
        $this->_helper->layout->disableLayout();
    }

    public function bazAction()
    {
        // usa um script de layout diferente com este action:
        $this->_helper->layout->setLayout('foobaz');
    };
}
]]></programlisting>

        <para>
            Em seus view scripts, você pode então acessar o objeto de layout via view helper
            <classname>Layout</classname>. Esse view helper é levemente diferente dos outros
            no que toca a não tomar argumentos, e retornar um objeto ao invés de um valor
            string. Isso permite que você imediatamente chame métodos no objeto de layout:
        </para>

        <programlisting language="php"><![CDATA[
<?php $this->layout()->setLayout('foo'); // configura layout alternativo ?>
]]></programlisting>

        <para>
            A qualquer tempo, você pode buscar a instância de <classname>Zend_Layout</classname>
            registrada com <acronym>MVC</acronym> via método estático
            <methodname>getMvcInstance()</methodname>:
        </para>

        <programlisting language="php"><![CDATA[
// Retorna null se startMvc() não foi o primeiro a ser chamado
$layout = Zend_Layout::getMvcInstance();
]]></programlisting>

        <para>
            Finalmente, o front controller plugin de <classname>Zend_Layout</classname> tem
            uma importante característica em adição a renderização do layout: ele recupera
            todos os segmentos nomeados do objeto de resposta e associa variáveis,
            associando o segmento 'default' a variável 'content'. Isso permite a você acessar
            o conteúdo de sua aplicação e renderizá-lo em seus view scripts.
        </para>

        <para>
            Como um exemplo, diremos que seu código primeiro ativa
            <methodname>FooController::indexAction()</methodname>, que renderiza algum
            conteúdo para o segmento de resposta padrão, e então prossegue para
            <methodname>NavController::menuAction()</methodname>, que renderiza conteúdo
            para o segmento de resposta 'nav'. Finalmente, você prossegue para
            <methodname>CommentController::fetchAction()</methodname> e busca alguns comentários,
            mas renderizar isso para o segmento de resposta é bom (o que adiciona conteúdo
            aquele segmento). Seu view script poderia então renderizar cada um separadamente:
        </para>

        <programlisting language="php"><![CDATA[
<body>
    <!-- renders /nav/menu -->
    <div id="nav"><?php echo $this->layout()->nav ?></div>

    <!-- renders /foo/index + /comment/fetch -->
    <div id="content"><?php echo $this->layout()->content ?></div>
</body>
]]></programlisting>

        <para>
            Essa característica é particularmente útil quando usada em conjunção com o
            <link linkend="zend.controller.actionhelpers.actionstack">action helper</link> e
            <link linkend="zend.controller.plugins.standard.actionstack">plugin</link>
            ActionStack, o qual você pode usar para configurar uma pilha de ações através da
            qual itertamos, e então criamos páginas widgetizadas.
        </para>
    </sect2>

    <sect2 id="zend.layout.quickstart.standalone">
        <title>Usando Zend_Layout como um Componente</title>

        <para>
            Como um componente autônomo, <classname>Zend_Layout</classname> não oferece tantas
            características ou tanta conveniência como quanto é usado com o
            <acronym>MVC</acronym>. Entretanto, ele ainda tem dois benefícios a destacar:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Escopo de variáveis de layout.
                </para>
            </listitem>

            <listitem>
                <para>
                    Isolamento do view script de layout de outros scripts view.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Quando usado como um componente autônomo, simplesmente inicie o objeto layout,
            use os vários acessores para configurar estado, configure variáveis como
            propriedades de objeto, e renderize o layout:
        </para>

        <programlisting language="php"><![CDATA[
$layout = new Zend_Layout();

// Configura um caminho de script de layout:
$layout->setLayoutPath('/path/to/layouts');

// Configura algumas variáveis:
$layout->content = $content;
$layout->nav     = $nav;

// Escolhe um script de layout diferente:
$layout->setLayout('foo');

// Renderiza o layout final
echo $layout->render();
]]></programlisting>
    </sect2>

    <sect2 id="zend.layout.quickstart.example">
        <title>Exemplo de Layout</title>

        <para>
            Algumas vezes uma imagem vale mais que mil palavras. A seguir temos
            um exemplo de um script de layout.
        </para>

        <para>
            <inlinegraphic align="center" valign="middle"
                fileref="figures/zend.layout.quickstart.example.png" format="PNG" />
        </para>

        <para>
            A ordem real dos elementos pode variar, dependendo do <acronym>CSS</acronym> que
            você tenha configurado; por exemplo, se você está usando posicionamento absoluto,
            você pode ser capaz de ter a navegação exibida mais tarde no documento, mas ainda
            mostrar-se no topo; o mesmo poderia ser dito para a barra lateral ou o cabeçalho.
            A mecânica real de puxar o conteúdo permanece a mesma, entretanto.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->
