boarspring
/
repo_zf1
mirror de https://github.com/bluescreen/zf1-php7.2.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281
							<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.layout.quickstart">
    <title>Zend_Layout Quick Start</title>

    <para>
        There are two primary use cases for <classname>Zend_Layout</classname>: with the
        Zend Framework <acronym>MVC</acronym>, and without.
    </para>

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

        <para>
            In both cases, however, you'll need to create a layout script. Layout scripts simply
            utilize <classname>Zend_View</classname> (or whatever view implementation you are
            using). Layout variables are registered with a <classname>Zend_Layout</classname> <link
                linkend="zend.view.helpers.initial.placeholder">placeholder</link>,
            and may be accessed via the placeholder helper or by fetching them
            as object properties of the layout object via the layout helper.
        </para>

        <para>
            As an example:
        </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>My Site</title>
</head>
<body>
<?php
    // fetch 'content' key using layout helper:
    echo $this->layout()->content;

    // fetch 'foo' key using placeholder helper:
    echo $this->placeholder('Zend_Layout')->foo;

    // fetch layout object and retrieve various keys from it:
    $layout = $this->layout();
    echo $layout->bar;
    echo $layout->baz;
?>
</body>
</html>
]]></programlisting>

        <para>
            Because <classname>Zend_Layout</classname> utilizes <classname>Zend_View</classname> for
            rendering, you can also use any view helpers registered, and also
            have access to any previously assigned view variables. Particularly
            useful are the various <link
                linkend="zend.view.helpers.initial.placeholder">placeholder
                helpers</link>, as they allow you to
            retrieve content for areas such as the &lt;head&gt; section,
            navigation, 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>Using Zend_Layout with the Zend Framework MVC</title>

        <para>
            <classname>Zend_Controller</classname> offers a rich set of functionality for
            extension via its <link linkend="zend.controller.plugins">front
            controller plugins</link> and <link
            linkend="zend.controller.actionhelpers">action controller
            helpers</link>. <classname>Zend_View</classname> also has <link
            linkend="zend.view.helpers">helpers</link>. <classname>Zend_Layout</classname>
            takes advantage of these various extension points when used with the
            <acronym>MVC</acronym> components.
        </para>

        <para>
            <methodname>Zend_Layout::startMvc()</methodname> creates an instance of
            <classname>Zend_Layout</classname> with any optional configuration you provide
            it. It then registers a front controller plugin that renders the
            layout with any application content once the dispatch loop is done,
            and registers an action helper to allow access to the layout object
            from your action controllers. Additionally, you may at any time grab
            the layout instance from within a view script using the
            <classname>Layout</classname> view helper.
        </para>

        <para>
            First, let's look at how to initialize <classname>Zend_Layout</classname> for use with
            the <acronym>MVC</acronym>:
        </para>

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

        <para>
            <methodname>startMvc()</methodname> can take an optional array of options or
            <classname>Zend_Config</classname> object to customize the instance; these
            options are detailed in <link linkend="zend.layout.options">this section</link>.
        </para>

        <para>
            In an action controller, you may then access the layout instance as
            an action helper:
        </para>

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

    public function bazAction()
    {
        // use different layout script with this action:
        $this->_helper->layout->setLayout('foobaz');
    };
}
]]></programlisting>

        <para>
            In your view scripts, you can then access the layout object via the
            <classname>Layout</classname> view helper. This view helper is slightly
            different than others in that it takes no arguments, and returns an
            object instead of a string value. This allows you to immediately
            call methods on the layout object:
        </para>

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

        <para>
            At any time, you can fetch the <classname>Zend_Layout</classname> instance
            registered with the <acronym>MVC</acronym> via the
            <methodname>getMvcInstance()</methodname> static method:
        </para>

        <programlisting language="php"><![CDATA[
// Returns null if startMvc() has not first been called
$layout = Zend_Layout::getMvcInstance();
]]></programlisting>

        <para>
            Finally, <classname>Zend_Layout</classname>'s front controller plugin has one
            important feature in addition to rendering the layout: it retrieves
            all named segments from the response object and assigns them as
            layout variables, assigning the 'default' segment to the variable
            'content'. This allows you to access your application content and
            render it in your view scripts.
        </para>

        <para>
            As an example, let's say your code first hits
            <methodname>FooController::indexAction()</methodname>, which renders some
            content to the default response segment, and then forwards to
            <methodname>NavController::menuAction()</methodname>, which renders content to
            the 'nav' response segment. Finally, you forward to
            <methodname>CommentController::fetchAction()</methodname> and fetch some
            comments, but render those to the default response segment as well
            (which appends content to that segment). Your view script could then
            render each separately:
        </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>
            This feature is particularly useful when used in conjunction with
            the ActionStack <link linkend="zend.controller.actionhelpers.actionstack">action
            helper</link> and <link
            linkend="zend.controller.plugins.standard.actionstack">plugin</link>,
            which you can use to setup a stack of actions through
            which to loop, and thus create widgetized pages.
        </para>
    </sect2>

    <sect2 id="zend.layout.quickstart.standalone">
        <title>Using Zend_Layout as a Standalone Component</title>

        <para>
            As a standalone component, <classname>Zend_Layout</classname> does not offer nearly as
            many features or as much convenience as when used with the <acronym>MVC</acronym>.
            However, it still has two chief benefits:
        </para>

        <itemizedlist>
            <listitem><para>Scoping of layout variables.</para></listitem>

            <listitem>
               <para>Isolation of layout view script from other view scripts.</para>
            </listitem>
        </itemizedlist>

        <para>
            When used as a standalone component, simply instantiate the layout
            object, use the various accessors to set state, set variables as
            object properties, and render the layout:
        </para>

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

// Set a layout script path:
$layout->setLayoutPath('/path/to/layouts');

// set some variables:
$layout->content = $content;
$layout->nav     = $nav;

// choose a different layout script:
$layout->setLayout('foo');

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

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

        <para>
            Sometimes a picture is worth a thousand words. The following is a
            sample layout script showing how it might all come together.
        </para>

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

        <para>
            The actual order of elements may vary, depending on the <acronym>CSS</acronym> you've
            setup; for instance, if you're using absolute positioning, you may
            be able to have the navigation displayed later in the document, but
            still show up at the top; the same could be said for the sidebar or
            header. The actual mechanics of pulling the content remain the same,
            however.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->