repo_zf1/documentation/manual/es/module_specs/Zend_Controller-ActionController.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 18556 -->
<!-- Reviewed: no -->
<sect1 id="zend.controller.action">
    <title>Controladores de Acción</title>

    <sect2 id="zend.controller.action.introduction">
        <title>Introducción</title>
        <para>
            <classname>Zend_Controller_Action</classname> es una clase abstracta
            que puede utilizar para implementar controladores de acción
            (Action Controllers) para usar con el Front Controller al crear un
            un sitio basado en el patrón Modelo-Vista-Controlador (<acronym>MVC</acronym>).
        </para>

        <para>
            Para usar <classname>Zend_Controller_Action</classname>, necesitará
            hacerla una subclase en sus clases actuales de controladores de
            acción (o hacerla una subclase para crear su propia clase base de
            acción de controladores).
            La operación más elemental es hacerla una subclase, y crear métodos
            de acción que corresponden a las diversas acciones que desee que el
            contralor maneje para su sitio.
            El manejo del ruteo y envío de
            <classname>Zend_Controller</classname> descubrirá por sí mismo
            cualquier método que termine en 'Action' en su clase, como posibles
            acciones del controlador.
        </para>

        <para>
            Por ejemplo, digamos que su clase se define como sigue:
        </para>

         <programlisting language="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
    public function barAction()
    {
        // hacer algo
    }

    public function bazAction()
    {
        // hacer algo
    }
}
]]></programlisting>

        <para>
            La clase de arriba <emphasis>FooController</emphasis> (el controlador
            <emphasis>foo</emphasis>) define dos acciones, <emphasis>bar</emphasis> y
           <emphasis>baz</emphasis>.
        </para>

        <para>
            Se pueden lograr muchas cosas más, tales como personalizar
            la inicialización de acciones, las acciones a llamar por defecto no
            deberían especificar ninguna acción (o una acción inválida),
            ganchos de pre y post despacho, y una variedad de métodos ayudantes.
            Este capítulo sirve como panorama de la funcionalidad del
            controlador de acciones.
        </para>

        <note>
            <title>Comportamiento por Defecto</title>

            <para>
                Por defecto, el <link linkend="zend.controller.front">front
                controller</link> habilita al ayudante de acción <link
                linkend="zend.controller.actionhelpers.viewrenderer">ViewRenderer</link>.
                Este ayudante toma a su cargo la inyección del objeto "view"
                en el contralor, así como compatibilizar automáticamente las
                vistas. Usted podrá desactivarlo dentro de su contralor de
                acción por uno de los métodos siguientes:
            </para>

             <programlisting language="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
    public function init()
    {
        // Local a este controlador únicamente; afecta a todas las acciones
        // al cargarse en init:
        $this->_helper->viewRenderer->setNoRender(true);

        // Globalmente:
        $this->_helper->removeHelper('viewRenderer');

        // También globalmente, pero tendría que ser en conjunción con la
        // versión local con el fin de propagarlo para este controlador:
        Zend_Controller_Front::getInstance()
            ->setParam('noViewRenderer', true);
    }
}
]]></programlisting>

            <para>
                <methodname>initView()</methodname>, <methodname>getViewScript()</methodname>,
                <methodname>render()</methodname>, y <methodname>renderScript()</methodname> cada
                proxy al <emphasis>ViewRenderer</emphasis> a menos que el ayudante no
                esté como ayudante intermediario o no se haya establecido el
                flag de <emphasis>noViewRenderer</emphasis>.
            </para>

            <para>
                También puede simplemente desactivarse para una prestación
                individual ajustando el flag <emphasis>noRender</emphasis> de
                <emphasis>ViewRenderer</emphasis>:
            </para>

             <programlisting language="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
    public function barAction()
    {
        // deshabilitar el autorendering para esta acción solamente:
        $this->_helper->viewRenderer->setNoRender();
    }
}
]]></programlisting>

            <para>
                Las principales razones para desactivar
                <emphasis>ViewRenderer</emphasis> son si usted simplemente no necesita
                una objeto "view" o si no está mostrándolos via view scripts
                (por ejemplo, cuando se utiliza un controlador de acción
                para alimentar a los protocolos de un servicio web como <acronym>SOAP</acronym>,
                <acronym>XML-RPC</acronym>, o <acronym>REST</acronym>). En muchos casos, nunca necesitará desactivar
                a <emphasis>ViewRenderer</emphasis> globalmente, sólo selectivamente
                dentro de los distintos controladores o acciones.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.controller.action.initialization">
        <title>Inicialización de Objectos</title>

        <para>
            Si bien siempre puede anular el contolador de acción del
            constructor, no lo recomendamos.
            <classname>Zend_Controller_Action::__construct()</classname>
            realiza algunas tareas importantes, tales como registrar los
            objetos de solicitud y respuesta, así como los argumentos de
            cualquier invocación personalizada pasados desde el front
            controller. Si debe anular el constructor, asegúrese de llamar a
            <methodname>parent::__construct($request, $response, $invokeArgs)</methodname>.
        </para>

        <para>
            La manera más apropiada de personalizar la instanciación es
            utilizar el método <methodname>init()</methodname>, el cual es llamado como la
            última tarea de <methodname>__construct()</methodname>.
            Por ejemplo, si se quiere conectar a una base de datos en la
            instanciación:
        </para>

         <programlisting language="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
    public function init()
    {
        $this->db = Zend_Db::factory('Pdo_Mysql', array(
            'host'     => 'myhost',
            'username' => 'user',
            'password' => 'XXXXXXX',
            'dbname'   => 'website'
        ));
    }
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.controller.action.prepostdispatch">
        <title>Ganchos de Pre- and Post-Despacho</title>

        <para>
            <classname>Zend_Controller_Action</classname> especifica dos
            métodos que pueden ser llamados para marcar una solicitud de acción,
            <methodname>preDispatch()</methodname> y <methodname>postDispatch()</methodname>.
            Estas pueden ser útiles de varias maneras: verificar la
            autenticación y <acronym>ACL</acronym>s antes de ejecutar una acción (llamando a
            <methodname>_forward()</methodname> en <methodname>preDispatch()</methodname>, se saltará
            la acción), por ejemplo, o colocando contenido generado en una
            plantilla general del sitio (<methodname>postDispatch()</methodname>).
        </para>
		
		        <note>
            <title>Usage of init() vs. preDispatch()</title>

            <para>
                In the <link linkend="zend.controller.action.initialization">previous
                    section</link>, we introduced the <methodname>init()</methodname> method, and
                in this section, the <methodname>preDispatch()</methodname> method. What is the
                difference between them, and what actions would you take in each?
            </para>

            <para>
                The <methodname>init()</methodname> method is primarily intended for extending the
                constructor. Typically, your constructor should simply set object state, and not
                perform much logic. This might include initializing resources used in the controller
                (such as models, configuration objects, etc.), or assigning values retrieved from
                the front controller, bootstrap, or a registry.
            </para>

            <para>
                The <methodname>preDispatch()</methodname> method can also be used to set object
                or environmental (e.g., view, action helper, etc.) state, but its primary purpose
                is to make decisions about whether or not the requested action should be dispatched.
                If not, you should then <methodname>_forward()</methodname> to another action, or
                throw an exception.
            </para>

            <para>
                Note: <methodname>_forward()</methodname> actually will not work correctly when
                executed from <methodname>init()</methodname>, which is a formalization of the
                intentions of the two methods.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.controller.action.accessors">
        <title>Accessors (Accededores)</title>

        <para>
            Con el objeto, se registran una serie de objetos y variables,
            y cada uno tiene métodos de acceso.
        </para>

        <itemizedlist>
            <listitem><para>
                <emphasis>Objecto Requerimiento</emphasis>: <methodname>getRequest()</methodname>
                puede ser utilizado para recuperar el objeto solicitud
                utilizado para llamar a la acción.
            </para></listitem>

            <listitem>
                <para>
                    <emphasis>Objecto Respuesta</emphasis>:
                    <methodname>getResponse()</methodname> puede ser utilizado para
                    recuperar el objeto respuesta agregando la respuesta final.
                    Algunas llamadas típicas podrían ser:
                </para>

                 <programlisting language="php"><![CDATA[
$this->getResponse()->setHeader('Content-Type', 'text/xml');
$this->getResponse()->appendBody($content);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Argumentos de Invocación</emphasis>: el front
                    controller puede empujar parámetros al router, al
                    despachador, y al controlador de acción. Para recuperarlos,
                    use <methodname>getInvokeArg($key)</methodname>; por otra parte, se
                    puede traer toda la lista utilizando
                    <methodname>getInvokeArgs()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Parámetros de Requerimientos</emphasis>:
                    La objeto solicitud agrega parámetros de solicitud,
                    como cualquiera de los parámetros <constant>_GET</constant> o <constant>_POST</constant>,
                    o parámetros del usuario especificados en la información
                    del path de la <acronym>URL</acronym>. Para recuperarlos, use
                    <methodname>_getParam($key)</methodname> o <methodname>_getAllParams()</methodname>.
                    También se pueden establecer parámetros de solicitud usando
                    <methodname>_setParam()</methodname>; lo que es útil cuando se reenvían
                    a acciones adicionales.
                </para>

                <para>
                    Para probar si un parámetro existe o no (muy útil para
                    bifurcaciones lógicas), use <methodname>_hasParam($key)</methodname>.
                </para>

                <note>
                    <para>
                        <methodname>_getParam()</methodname> puede tomar opcionalmente un
                        segundo argumento que contiene un valor por defecto a
                        utilizar si el parámetro no está establecido o está
                        vacío.  Usándolo elimina la necesidad de llamar
                        previamente a <methodname>_hasParam()</methodname> para
                        recuperar un valor:
                    </para>

                     <programlisting language="php"><![CDATA[
// Usar por defecto el valor 1 si el id no está establecido
$id = $this->_getParam('id', 1);

// En lugar de:
if ($this->_hasParam('id') {
    $id = $this->_getParam('id');
} else {
    $id = 1;
}
]]></programlisting>
                </note>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.controller.action.viewintegration">
        <title>Integración de Vistas</title>

        <note id="zend.controller.action.viewintegration.viewrenderer">
            <title>Integración de la Vista por Defecto via ViewRenderer</title>

            <para>
                El contenido de esta sección sólo es válida cuando usted tiene
                explícitamente deshabilitado a
                <link linkend="zend.controller.actionhelpers.viewrenderer">ViewRenderer</link>.
                De lo contrario, puede saltarse esta sección.
            </para>
        </note>

        <para>
            <classname>Zend_Controller_Action</classname> proporciona un
            mecanismo rudimentario y flexible para ver la integración.
            Hay dos métodos para lograrlo, <methodname>initView()</methodname> y
            <methodname>render()</methodname>; el anterior método <varname>$view</varname>
            carga la propiedad pública, y este último muestra una vista en
            base a la acción requerida actual, utilizando la jerarquía del
            directorio para determinar el path del script.
        </para>

        <sect3 id="zend.controller.action.viewintegration.initview">
            <title>Inicialización de la Vista</title>

            <para>
                <methodname>initView()</methodname> inicializa el objeto vista.
                <methodname>render()</methodname> llama a <methodname>initView()</methodname>
                con el fin de recuperar el objeto vista, pero puede ser
                iniciada en cualquier momento; por defecto introduce
                información a la propiedad de <varname>$view</varname> con un objeto
                <classname>Zend_View</classname>, pero se puede usar cualquier
                clase que implemente <classname>Zend_View_Interface</classname>.
                Si <varname>$view</varname> ya ha sido inicializada, simplemente
                devuelve esa propiedad.
            </para>

            <para>
                La implementación por defecto hace la siguiente hipótesis de la
                estructura del directorio:
            </para>

             <programlisting language="php"><![CDATA[
applicationOrModule/
    controllers/
        IndexController.php
    views/
        scripts/
            index/
                index.phtml
        helpers/
        filters/
]]></programlisting>

            <para>
                En otras palabras, los scripts de vista se supone están en el
                subdirectorio <filename>/views/scripts/</filename>, y en el subdirectorio
                <filename>/views/</filename> se supone que contiene funcionalidades
                hermanas (ayudantes, filtros). Al determinar el nombre y el
                path del script, el directorio <filename>views/scripts/</filename>
                será utilizado como el path base, con directorios nombrados
                después que los controladores individuales proporcionen una
                jerarquía a los scripts de vista.
            </para>
        </sect3>

        <sect3 id="zend.controller.action.viewintegration.render">
            <title>Suministrando las Vistas</title>

            <para>
                <methodname>render()</methodname> tiene la siguiente firma:
            </para>

             <programlisting language="php"><![CDATA[
string render(string $action = null,
              string $name = null,
              bool $noController = false);
]]></programlisting>

            <para>
                <methodname>render()</methodname> suministra un script de vista.
                Si no se pasan argumentos, se supone que el script requerido es
                <filename>[controller]/[action].phtml</filename> (donde
                <filename>.phtml</filename> es el valor de la propiedad
                <filename>$viewSuffix</filename>).
                Pasándole un valor a <methodname>$action</methodname> suministrará esa
                plantilla en al subdirectorio <filename>/[controller]/</filename>. Para
                anular el subdirectorio <filename>/[controller]/</filename> ponga un
                valor <constant>TRUE</constant> en <varname>$noController</varname>.
                Por último, las plantillas son suministradas en el objeto
                respuesta; si desea suministrar a un determinado
                <link linkend="zend.controller.response.namedsegments">
                named segment</link> en el objeto respuesta, pase un valor a
                <varname>$name</varname>.
            </para>

            <note><para>
                    Dado que el controlador y los nombres de acción pueden
                    contener caracteres delimitadores como '_', '.', y '-',
                    <methodname>render()</methodname> los normaliza a '-' para determinar
                    el nombre del script. Internamente, utiliza los
                    delimitadores de palabra y de path del despachador para
                    hacer esta normalización. Así, una solicitud a
                    <filename>/foo.bar/baz-bat</filename> suministrará el script
                    <filename>foo-bar/baz-bat.phtml</filename>.
                    Si su método de acción contiene camelCasing, recuerde que
                    esto se traducirá en palabras separadas por '-'
                    al determinar el nombre del archivo del script de vista.
            </para></note>

            <para>
                Algunos ejemplos:
            </para>

             <programlisting language="php"><![CDATA[
class MyController extends Zend_Controller_Action
{
    public function fooAction()
    {
        // Suministra my/foo.phtml
        $this->render();

        // Suministra my/bar.phtml
        $this->render('bar');

        // Suministra baz.phtml
        $this->render('baz', null, true);

        // Suministra my/login.phtml al segmento 'form' del
        // objeto respuesta
        $this->render('login', 'form');

        // Suministra site.phtml al segmento 'page' del objeto
        // respuesta; no usa el subdirectorio 'my/'
        $this->render('site', 'page', true);
    }

    public function bazBatAction()
    {
        // Suministra my/baz-bat.phtml
        $this->render();
    }
}
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.controller.action.utilmethods">
        <title>Métodos Utilitarios</title>

        <para>
            Además de los accesadores y de los métodos de integración de vistas,
            <classname>Zend_Controller_Action</classname> tiene varios
            métodos utilitarios para realizar tareas comunes dentro de sus
            métodos de acción (o de pre- y post-dispatch).
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>_forward($action, $controller = null, $module = null,
                        array $params = null)</methodname>: realiza otra acción. Si es
                    llamado en <methodname>preDispatch()</methodname>, la acción actualmente
                    requerida se saltará en favor de la nueva.
                    De lo contrario, después de procesar la acción actual,
                    se ejecutará la acción solicitada en _forward().
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>_redirect($url, array $options =
                        array())</methodname>: redireccionar a otro lugar.
                        Este método toma una <acronym>URL</acronym> y un conjunto de opciones.
                        Por defecto, realiza una redirección <acronym>HTTP</acronym> 302.
                </para>

                <para>
                    Las opciones pueden incluir uno o más de los siguientes:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <emphasis>exit:</emphasis> ya sea para salir
                            inmediatamente o no. Si así lo solicita, limpiamente
                            cerrará cualquier sesión abierta y realizará
                            la redirección.
                        </para>

                        <para>
                            Puede configurar esta opción globalmente en el
                            controlador utilizando el accesador
                            <methodname>setRedirectExit()</methodname>.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>prependBase:</emphasis> ya sea
                            anteponiendo o no la base <acronym>URL</acronym> registrada con el
                            objeto solicitud a la <acronym>URL</acronym> provista.
                        </para>

                        <para>
                            Puede configurar esta opción globalmente en el
                            controlador utilizando el accesador
                            <methodname>setRedirectPrependBase()</methodname>.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>code:</emphasis> qué código <acronym>HTTP</acronym>
                            utilizar en la redirección. Por defecto,
                            se utiliza un <acronym>HTTP</acronym> 302; se puede utilizar cualquier
                            código entre 301 y 306.
                        </para>

                        <para>
                            Puede configurar esta opción globalmente en el
                            controlador utilizando el accesador
                            <methodname>setRedirectCode()</methodname>.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.controller.action.subclassing">
        <title>Controladores de Acción y haciendo Subclases</title>

        <para>
            Por diseño, <classname>Zend_Controller_Action</classname>
            debe ser "subclaseada" a fin de crear un controlador de acción.
            Como mínimo, necesitará definir los métodos de acción que podrá
            llamar el controlador.
        </para>

        <para>
            Además de crear una funcionalidad útil para su aplicaciones web,
            también puede encontrar que está repitiendo demasiado los mismos
            setups o métodos utilitarios en sus diferentes controladores;
            si así fuera, creando una clase base común del controlador
            que extienda <classname>Zend_Controller_Action</classname> puede
            resolver esta redundacia.
        </para>

        <example id="zend.controller.action.subclassing.example-call">
            <title>Manejando Acciones No Existentes</title>

            <para>
                Si hay una solicitud a un controlador que incluye un método de
                acción no definido, se invocará a
                <classname>Zend_Controller_Action::__call()</classname>.
                <methodname>__call()</methodname> es, por supuesto, el método mágico de <acronym>PHP</acronym>
                para la sobrecarga del método.
            </para>

            <para>
                Por defecto, este método lanza un
                <classname>Zend_Controller_Action_Exception</classname>
                indicando que el método no se encuentró en el controlador.
                Si el método requerido termina en 'Action', la suposición es
                que una acción fue solicitada y no existe; tales errores
                resultan en una excepción con un código 404.
                Todos los demás métodos resultan en una excepción con un
                código 500. Esto le permite diferenciar fácilmente entre una
                página no encontrada y errores de aplicación con su
                manejador de errores.
            </para>

            <para>
                Usted debe anular esta funcionalidad si desea realizar otras
                operaciones. Por ejemplo, si desea mostrar un mensaje de error,
                usted podría escribir algo como esto:
            </para>

             <programlisting language="php"><![CDATA[
class MyController extends Zend_Controller_Action
{
    public function __call($method, $args)
    {
        if ('Action' == substr($method, -6)) {
            // Si no se encontró el método de la acción, suministrar la
            // plantilla de error
            return $this->render('error');
        }

        // todos los otros métodos lanzan una excepción
        throw new Exception('Se ha llamado al método "'
                            . $method
                            . '" que es inválido',
                            500);
    }
}
]]></programlisting>

            <para>
                Otra posibilidad es que puede querer avanzar a un controlador
                de página por defecto:
            </para>

             <programlisting language="php"><![CDATA[
class MyController extends Zend_Controller_Action
{
    public function indexAction()
    {
        $this->render();
    }

    public function __call($method, $args)
    {
        if ('Action' == substr($method, -6)) {
            // Si no se encontró el método de acción, avance a la
            // acción index
            return $this->_forward('index');
        }

        // todos los otros métodos lanzan una excepción
        throw new Exception('Se ha llamado al método "'
                            . $method
                            . '" que es inválido',
                            500);
    }
}
]]></programlisting>
        </example>

        <para>
            Además de sobrecargar <methodname>__call()</methodname>, cada uno de los
            métodos gancho de inicialización, utilidad, accesador, vista,
            y despacho mencionados anteriormente en este capítulo pueden ser
            anulados a fin de personalizar sus controladores.
            Como ejemplo, si está almacenando su objeto vista en un registro,
            quizás desee modificar su método <methodname>initView()</methodname> con código
            parecido al siguiente:
        </para>

         <programlisting language="php"><![CDATA[
abstract class My_Base_Controller extends Zend_Controller_Action
{
    public function initView()
    {
        if (null === $this->view) {
            if (Zend_Registry::isRegistered('view')) {
                $this->view = Zend_Registry::get('view');
            } else {
                $this->view = new Zend_View();
                $this->view->setBasePath(dirname(__FILE__) . '/../views');
            }
        }

        return $this->view;
    }
}
]]></programlisting>

        <para>
            Es de esperar, que de la información en este capítulo, usted puede ver
            la flexibilidad de este componente en particular y cómo puede darle
            forma a su aplicaciones o a las necesidades de su sitio web.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->