repo_zf1/documentation/manual/es/module_specs/Zend_Controller-ActionHelpers-ContextSwitch.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect3 id="zend.controller.actionhelpers.contextswitch">
    <title>ContextSwitch con AjaxContext</title>

    <para>
        El ayudante de acción <code>ContextSwitch</code> está destinado a
        facilitar el regreso de respuestas de diferentes formatos de solicitud.
        El ayudante <code>AjaxContext</code> es una versión especializada de
        <code>ContextSwitch</code> que facilita el regreso de respuestas
        a XmlHttpRequests.
    </para>

    <para>
        Para habilitar alguno, usted debe proporcionar indicios en su
        controlador de qué acciones pueden responder a que contextos.
        Si una solicitud entrante indica un contexto válido para la acción
        determinada, entonces el ayudante:
    </para>

    <itemizedlist>
        <listitem><para>
                Deshabilita los esquemas, si están habilitados.
        </para></listitem>

        <listitem><para>
                Establecer un sufijo de vista alternativo, requiriendo de
                manera efectiva un script de vista separado para el contexto.
        </para></listitem>

        <listitem><para>
                Envía las cabeceras de respuesta apropiadas para el contexto
                deseado.
        </para></listitem>

        <listitem><para>
                Opcionalmente, llama a llamadas de retorno especifícas para
                configurar el contexto y/o realizar post-procesamiento.
        </para></listitem>
    </itemizedlist>

    <para>
        Como ejemplo, tomemos el siguiente controlador:
    </para>

    <programlisting role="php"><![CDATA[
class NewsController extends Zend_Controller_Action
{
    /**
     * Página final; enviar a listAction()
     */
    public function indexAction()
    {
        $this->_forward('list');
    }

    /**
     * Lista nuevos items
     */
    public function listAction()
    {
    }

    /**
     * Vista del nuevo item
     */
    public function viewAction()
    {
    }
}
]]></programlisting>

    <para>
        Digamos que queremos que <code>listAction()</code> también esté
        disponible en un formato XML. En lugar de crear una acción diferente,
        podemos indicarle que puede devolver una respuesta XML:
    </para>

    <programlisting role="php"><![CDATA[
class NewsController extends Zend_Controller_Action
{
    public function init()
    {
        $contextSwitch = $this->_helper->getHelper('contextSwitch');
        $contextSwitch->addActionContext('list', 'xml')
                      ->initContext();
    }

    // ...
}
]]></programlisting>

    <para>
        Esto es lo que hará:
    </para>

    <itemizedlist>
        <listitem><para>
                Establecer la cabecera de respuesta 'Content-Type' a 'text/xml'.
        </para></listitem>

        <listitem><para>
                Cambiar el sufijo de vista de 'xml.phtml' (o, si usa un sufifo
                de vista alternativo, 'xml.[su sufijo]').
        </para></listitem>
    </itemizedlist>

    <para>
        Ahora, necesitará crear un nuevo script de vista, 'news/list.xml.phtml',
        que creará y mostrará a XML.
    </para>

    <para>
        Para determinar si una solicitud debe iniciar un cambio de contexto,
        el ayudante comprueba si hay un token en el objeto solicitud.
        Por defecto, busca el parámetro 'format', aunque esto puede ser
        configurado. Esto significa que, en muchos casos, para provocar un
        cambio de contexto, puede agregar un parámetro 'format' a su solicitud:
    </para>

    <itemizedlist>
        <listitem><para>
                Via parámetro URL: <code>/news/list/format/xml</code>
                (recordar que el valor por defecto del esquema de ruteo permite
                pares arbitrarios de clave/valor tras la acción).
        </para></listitem>

        <listitem><para>
                Via parámetro GET: <code>/news/list?format=xml</code>
        </para></listitem>
    </itemizedlist>

    <para>
        <code>ContextSwitch</code> le permite especificar contextos arbitrarios,
        incluso qué sufijo cambiará (si hay alguno), cualquier cabecera de
        respuesta que deba ser enviada, y callbacks arbitrarios para la
        inicialización y posterior procesamiento.
    </para>

    <sect4 id="zend.controller.actionhelpers.contextswitch.contexts">
        <title>Contextos Disponibles por Defecto</title>

        <para>
            Por defecto, dos contextos están a disposición del ayudante
            <code>ContextSwitch</code> : JSON y XML.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>JSON</emphasis>. El contexto JSON establece la
                    cabecera de respuesta 'Content-Type' a 'application/json',
                    y el sufijo del script de vista a 'json.phtml'.
                </para>

                <para>
                    Sin embargo, por defecto, no es necesario un script de vista.
                    Simplemente serializará todas las variables de la vista,
                    y emitirá la respuesta JSON inmediatamente.
                </para>

                <para>
                    Este comportamiento puede ser desactivado apagando la
                    serialización auto-JSON:
                </para>

                <programlisting role="php"><![CDATA[
$this->_helper->contextSwitch()->setAutoJsonSerialization(false);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>XML</emphasis>. El contexto XML establece la
                    cabecera de respuesta 'Content-Type' a 'text/xml',
                    y el sufijo del script de vista a 'xml.phtml'.
                    Necesitará crear un script de vista nuevo para el contexto.
                </para>
            </listitem>
        </itemizedlist>
    </sect4>

    <sect4 id="zend.controller.actionhelpers.contextswitch.custom">
        <title>Creando Contextos Personalizados</title>

        <para>
            A veces, los contextos por defecto no son suficientes. Por ejemplo,
            puede que desee devolver YAML, o PHP serializado, un RSS o ATOM
            feed, etc. <code>ContextSwitch</code> le permite hacerlo.
        </para>

        <para>
            La forma más fácil para añadir un nuevo contexto es a través del
            método <code>addContext()</code>. Este método tiene dos argumentos,
            el nombre del contexto, y un array de especificación.
            La especificación debería incluir uno o más de los siguientes:
        </para>

        <itemizedlist>
            <listitem>
                <para><emphasis>suffix</emphasis>: el sufijo a anteponer al
                sufijo de la vista por defecto tal como está registrado en
                ViewRenderer.</para>
            </listitem>

            <listitem>
                <para><emphasis>headers</emphasis>: un array de pares
                cabecera/valor que desea enviar como parte de la respuesta.
                </para>
            </listitem>

            <listitem>
                <para><emphasis>callbacks</emphasis>: un array que contiene una
                o más de las claves 'init' o 'post', apuntando a callbacks PHP
                válidos que pueden utilizarse para inicializar el contexto y
                posterior procesamiento.</para>

                <para>La inicialización de callbacks ocurre cuando el contexto
                es detectado por <code>ContextSwitch</code>.
                Usted puede usarlo para ejecutar una lógica arbitraria.
                Por ejemplo, el contexto JSON utiliza un callback
                para desactivar a ViewRenderer cuando está activada la
                serialización auto-JSON.</para>

                <para>El post procesamiento ocurre durante la rutina de la
                acción <code>postDispatch()</code>, y puede ser utilizada
                para ejecutar una lógica arbitraria. Como ejemplo, el contexto
                JSON utiliza un callback para determinar si la serialización
                auto-JSON está activada; si así fuera, serializa las variables
                de la vista a JSON y envía la respuesta, pero si no,
                re-habilita a ViewRenderer.</para>
            </listitem>
        </itemizedlist>

        <para>
            Hay una variedad de métodos para interactuar con contextos:
        </para>

        <itemizedlist>
            <listitem><para>
                <code>addContext($context, array $spec)</code>: agrega un nuevo
                contexto. Lanza una excepción si el contexto ya existe.
            </para></listitem>

            <listitem><para>
                <code>setContext($context, array $spec)</code>: añade un nuevo
                contexto o sobrescribirá un contexto existente.
                Usa la misma especificación que <code>addContext()</code>.
            </para></listitem>

            <listitem><para>
                <code>addContexts(array $contexts)</code>: añade muchos
                contextos de una vez. El array <code>$contexts</code> debería
                ser un array de pares contexto/especificación.
                Si alguno de los contextos ya existe, arrojará una excepción.
            </para></listitem>

            <listitem><para>
                <code>setContexts(array $contexts)</code>: añade nuevos
                contextos y sobreescribe los existentes. Usa la misma
                especificación que <code>addContexts()</code>.
             </para></listitem>

            <listitem><para>
                <code>hasContext($context)</code>: devuelve true si el contexto
                existe, false de lo contrario.
            </para></listitem>

            <listitem><para> <code>getContext($context)</code>: recupera un
            único contexto por su nombre. Devuelve un array siguiendo la
            especificación usada en <code>addContext()</code>.
            </para></listitem>

            <listitem><para>
                <code>getContexts()</code>: recupera todos los contextos.
                Devuelve un array de pares contexto/especificación.
            </para></listitem>

            <listitem><para>
                <code>removeContext($context)</code>: elimina un único contexto
                por su nombre. Devuelve true si tiene éxito, false si el
                contexto no fue encontrado.
            </para></listitem>

            <listitem><para>
                <code>clearContexts()</code>: elimina todos los contextos.
            </para></listitem>
        </itemizedlist>
    </sect4>

    <sect4 id="zend.controller.actionhelpers.contextswitch.actions">
        <title>Estableciendo los Contextos por Acción</title>

        <para>
            Hay dos mecanismos para establecer contextos disponibles.
            Puede crear manualmente los arrays en su controlador, o utilizar
            varios métodos en <code>ContextSwitch</code> para ensamblarlos.
        </para>

        <para>
            El método principal para añadir relaciones acción/contexto es
            <code>addActionContext()</code>. Se esperan dos argumentos,
            la acción a la que el contexto se añade, y el nombre de un contexto
            o un array de contextos. Como ejemplo, considere la siguiente
            clase controlador:
        </para>

        <programlisting role="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
    public function listAction()
    {
    }

    public function viewAction()
    {
    }

    public function commentsAction()
    {
    }

    public function updateAction()
    {
    }
}
]]></programlisting>

        <para>
            Supongamos que queremos añadir un contexto XML a la acción 'list',
            y contextos XML y JSON a la acción 'comments'.
            Podríamos hacerlo en el método <code>init()</code>:
        </para>

        <programlisting role="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
    public function init()
    {
        $this->_helper->contextSwitch()
             ->addActionContext('list', 'xml')
             ->addActionContext('comments', array('xml', 'json'))
             ->initContext();
    }
}
]]></programlisting>

        <para>
            Alternativamente, puede simplemente definir la propiedad del array
            <code>$contexts</code>:
        </para>

        <programlisting role="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
    public $contexts = array(
        'list'     => array('xml'),
        'comments' => array('xml', 'json')
    );

    public function init()
    {
        $this->_helper->contextSwitch()->initContext();
    }
}
]]></programlisting>

        <para>
            El anterior es el menos sobrecargado, pero también está expuesto a
            posibles errores.
        </para>

        <para>
            Los siguientes métodos pueden ser utilizados para construir los
            mapeos del contexto:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>addActionContext($action, $context)</code>: marca uno
                    o más contextos como disponibles para una acción.
                    Si ya existen los mapeos, simplemente se añade a esos mapeos.
                    <code>$context</code> puede ser un único contexto,
                    o un array de contextos.
                </para>

                <para>
                    Un valor de <code>true</code> para el contexto marcará
                    todos los contextos como disponibles para la acción.
                </para>

                <para>
                    Un valor vacío de $contexto desactivará todos los contextos
                    para la acción determinada.
                </para>
            </listitem>

            <listitem><para>
                    <code>setActionContext($action, $context)</code>: marca uno
                    o más contextos como disponibles para una acción.
                    Si el mapeo ya existe, se reemplaza con los especificados.
                    <code>$context</code> puede ser un único contexto,
                    o un array de contextos.
            </para></listitem>

            <listitem><para>
                    <code>addActionContexts(array $contexts)</code>: agrega
                    varios pares acción/contexto de una vez.
                    <code>$contexts</code> debe ser un array asociativo de
                    pares acción/contexto. Le pasa la petición a
                    <code>addActionContext()</code>, lo que significa que si
                    los emparejamientos ya existen, se añade a ellos.
            </para></listitem>

            <listitem><para>
                    <code>setActionContexts(array $contexts)</code>: actúa como
                    <code>addActionContexts()</code>, pero sobreescribe
                    pares de acción/contexto existentes.
            </para></listitem>

            <listitem><para>
                    <code>hasActionContext($action, $context)</code>: determina
                    si una acción particular tiene un contexto determinado.
            </para></listitem>

            <listitem><para>
                    <code>getActionContexts($action = null)</code>: devuelve o
                    todos los contextos para una acción determinada,
                    o todos los pares de acción/contexto.
            </para></listitem>

            <listitem><para>
                    <code>removeActionContext($action, $context)</code>: elimina
                    uno o más contextos de una acción determinada.
                    <code>$context</code> puede ser un único contexto o un
                    array de contextos.
            </para></listitem>

            <listitem><para>
                    <code>clearActionContexts($action = null)</code>: elimina
                    todos los contextos de una acción determinada, o de todas
                    las acciones con contextos.
            </para></listitem>
        </itemizedlist>
    </sect4>

    <sect4 id="zend.controller.actionhelpers.contextswitch.initcontext">
        <title>Inicializando Conmutación de Contextos (Context Switching)</title>

        <para>
            Para inicializar la conmutación de contexto, necesita llamar a
            <code>initContext()</code> en su controlador de acción:
        </para>

        <programlisting role="php"><![CDATA[
class NewsController extends Zend_Controller_Action
{
    public function init()
    {
        $this->_helper->contextSwitch()->initContext();
    }
}
]]></programlisting>

        <para>
            En algunos casos, puede querer forzar el contexto utilizado;
            por ejemplo, puede que sólo quiera permitir el contexto XML si
            la conmutación de contexto está activada. Puede hacerlo
            pasando el contexto a <code>initContext()</code>:
        </para>

        <programlisting role="php"><![CDATA[
$contextSwitch->initContext('xml');
]]></programlisting>
    </sect4>

    <sect4 id="zend.controller.actionhelpers.contextswitch.misc">
        <title>Funcionalidad Adicional</title>

        <para>
            Se pueden utilizar una variedad de métodos para alterar el
            comportamiento del ayudante <code>ContextSwitch</code>.
            Estos incluyen:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>setAutoJsonSerialization($flag)</code>: Por defecto,
                    los contextos JSON serializarán cualquier variable de vista
                    a notación JSON y lo devolverán como una respuesta.
                    Si usted desea crear su propia respuesta, debe deshabilitar
                    esta opción; esto debe hacerse antes de llamar a
                    <code>initContext()</code>.
                </para>

                <programlisting role="php"><![CDATA[
$contextSwitch->setAutoJsonSerialization(false);
$contextSwitch->initContext();
]]></programlisting>

                <para>
                    Puede recuperar el valor del flag con
                    <code>getAutoJsonSerialization()</code>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>setSuffix($context, $suffix,
                        $prependViewRendererSuffix)</code>: Con este método,
                        puede especificar un sufijo diferente para utilizarlo
                        en un contexto determinado. El tercer argumento es
                        utilizado para indicar si anteponer o no el actual
                        sufijo de ViewRenderer con el nuevo sufijo; este flag
                        está activado por defecto.
                </para>

                <para>
                    Pasando un valor vacío para el sufijo hará que sólo el
                    sufijo ViewRenderer será utilizado.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>addHeader($context, $header, $content)</code>: Añadir
                    una cabecera de respuesta para un determinado contexto.
                    <code>$header</code> es el nombre de la cabecera, y
                    <code>$content</code> es el valor a pasar por esa cabecera.
                </para>

                <para>
                    Cada contexto pueden tener múltiples cabeceras;
                    <code>addHeader()</code> agrega cabeceras adicionales al
                    stack de cabecera del contexto.
                </para>

                <para>
                    Si el <code>$header</code> especificado ya existe para el
                    contexto, arrojará una excepción.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>setHeader($context, $header, $content)</code>:
                    <code>setHeader()</code> actúa igual que
                    <code>addHeader()</code>, excepto que le permite
                    sobreescribir cabeceras del contexto actual.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>addHeaders($context, array $headers)</code>: Añade
                    varias cabeceras de una vez a un determinado contexto.
                    Delega a <code>addHeader()</code>, así que si la cabecera
                    ya existe, arrojará una excepción. <code>$headers</code>
                    es un array de pares cabecera/contexto.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>setHeaders($context, array $headers.)</code>: como
                    <code>addHeaders()</code>, excepto que lo delegua a
                    <code>setHeader()</code>, permitiéndole sobreescribir las
                    cabeceras existentes.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getHeader($context, $header)</code>: recuperar el
                    valor de una cabecera para un determinado contexto.
                    Retorna null si no existe.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>removeHeader($context, $header)</code>: eliminar una
                    única cabecera para un determinado contexto.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>clearHeaders($context, $header)</code>: eliminar
                    todas las cabeceras para un determinado contexto.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>setCallback($context, $trigger, $callback)</code>:
                    establecer un callback en un determinado disparador para
                    poner en marcha un determinado contexto. Los disparadores
                    pueden ser 'init' o 'post' (indicando que se llamará a un
                    callback para cada contexto de inicialización o
                    postDispatch). <code>$callback</code> debe ser un callback
                    válido de PHP.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>setCallbacks($context, array $callbacks)</code>:
                    establece varios callbacks para un determinado contexto.
                    <code>$callbacks</code> deben ser pares de
                    diparadores/callbacks. En realidad, la mayor cantidad de
                    callbacks que pueden ser registrados son dos, uno para la
                    inicialización y otro para el procesamiento posterior.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getCallback($context, $trigger)</code>: recuperar un
                    callback para un determinado disparador en un contexto dado.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getCallbacks($context)</code>: recupera todos los
                    callbacks para un determinado contexto. Devuelve un array
                    de pares disparor/callback.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>removeCallback($context, $trigger)</code>: elimina un
                    callback para un determinado disparador y contexto.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>clearCallbacks($context)</code>: elimina todos los
                    callbacks para un determinado contexto.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>setContextParam($name)</code>: establece el parámetro
                    de petición para comprobar si un conmutador de contexto ha
                    sido solicitado. El valor por defecto es 'format',
                    pero este accededor puede ser utilizado para establecer un
                    valor alternativo.
                </para>

                <para>
                    <code>getContextParam()</code> puede ser utilizado para
                    recuperar el valor actual.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>setAutoDisableLayout($flag)</code>: Por defecto, los
                    esquemas están deshabilitados cuando sucede una conmutación
                    de contexto; esto es porque normalmente los esquemas sólo
                    serán utilizados para devolver respuestas normales, y no
                    tienen sentido en otros contextos.
                    Sin embargo, si desea usar esquemas (tal vez puede tener un
                    diseño para el nuevo contexto), puede cambiar este
                    comportamiento pasando un valor falso a
                    <code>setAutoDisableLayout()</code>. Usted debería hacer
                    esto <emphasis>antes</emphasis> de llamar a
                    <code>initContext()</code>.
                </para>

                <para>
                    Para conseguir el valor de este flag, utilice el accededor
                    <code>getAutoDisableLayout()</code>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getCurrentContext()</code> Puede ser utilizado para
                    determinar qué contexto fue detectado, si hay alguno.
                    Este retorna null si no hubo conmutación de contexto,
                    o si <code>initContext()</code> fue llamado antes de ser
                    invocado.
                </para>
            </listitem>
        </itemizedlist>
    </sect4>

    <sect4 id="zend.controller.actionhelpers.contextswitch.ajaxcontext">
        <title>Funcionalidad de AjaxContext</title>

        <para>
            El ayudante <code>AjaxContext</code> extiende
            <code>ContextSwitch</code>, así que toda de la funcionalidad
            listada para <code>ContextSwitch</code> está disponible.
            Hay algunas diferencias fundamentales, sin embargo.
        </para>

        <para>
            En primer lugar, el controlador de acción utiliza una propiedad
            diferente para determinar contextos, <code>$ajaxable</code>.
            Esto es, que puede tener diferentes contextos utilizados para
            AJAX versus peticiones normales HTTP.
            Los diversos métodos <code>*ActionContext*()</code> de
            <code>AjaxContext</code> le escribirán a esta propiedad.
        </para>

        <para>
            En segundo lugar, sólo se disparará si se produjo un XmlHttpRequest,
            según lo determinado por la solicitud del método del objeto
            <code>isXmlHttpRequest()</code>.
            Así, si se pasa el parámetro de contexto ('format') en la
            solicitud, pero la solicitud no fue hecha como un XmlHttpRequest,
            no se disparará ninguna conmutación de contexto.
        </para>

        <para>
            En tercer lugar, <code>AjaxContext</code> agrega un contexto
            adicional, HTML. En este contexto, se establece el sufijo a
            'ajax.phtml' para diferenciar el contexto de una solicitud normal.
            No se devuelven cabeceras adicionales.
        </para>

        <example id="zend.controller.actionhelpers.contextswitch.ajaxcontext.example">
            <title>Permitiendo a las Acciones Responder a Requerimientos Ajax</title>

            <para>
                En el siguiente ejemplo, estamos permitiendo requerimientos a
                las acciones 'view', 'form', y 'process' para responder a
                peticiones AJAX. En los dos primeros casos, 'view' y 'form',
                devolveremos fragmentos (snippets) de HTML con los cuales
                actualizaremos la página; y en el último, devolveremos JSON.
            </para>

            <programlisting role="php"><![CDATA[
class CommentController extends Zend_Controller_Action
{
    public function init()
    {
        $ajaxContext = $this->_helper->getHelper('AjaxContext');
        $ajaxContext->addActionContext('view', 'html')
                    ->addActionContext('form', 'html')
                    ->addActionContext('process', 'json')
                    ->initContext();
    }

    public function viewAction()
    {
        // Tirar para ver un único comentario.
        // Cuando se detecta AjaxContext, utiliza el script de vista
        // comment/view.ajax.phtml.
    }

    public function formAction()
    {
        // Mostrar el form "add new comment".
        // Cuando se detecta AjaxContext, utiliza el script de vista
        // comment/form.ajax.phtml.
    }

    public function processAction()
    {
        // Procesar un nuevo comentario
        // Devolver los resultados como JSON; simplemente asignar los
        // resultados como variables de la vista, y se devolverán como JSON.

    }
}
]]></programlisting>

            <para>
                En el lado del cliente, su biblioteca AJAX simplemente pedirá
                los parámetros finales '/comment/view', '/comment/form', y
                '/comment/process', y pasar el parámetro 'format':
                '/comment/view/format/html', '/comment/form/format/html',
                '/comment/process/format/json'. (O puede pasar el parámetro via
                string de consulta: e.g., "?format=json").
            </para>

            <para>
                Asumiendo que su biblioteca pasa la cabecera
                'X-Requested-With:XmlHttpRequest' entonces estas acciones
                devolverán la respuesta en el formato apropiado.
            </para>
        </example>
    </sect4>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->