repo_zf1/documentation/manual/en/module_specs/Zend_Controller-ActionHelpers-Json.xml

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

    <para>
        <acronym>JSON</acronym> responses are rapidly becoming the response of choice when dealing
        with <acronym>AJAX</acronym> requests that expect dataset responses;
        <acronym>JSON</acronym> can be immediately parsed on the client-side, leading to quick
        execution.
    </para>

    <para>
        The <acronym>JSON</acronym> action helper does several things:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                Disables layouts if currently enabled.
            </para>
        </listitem>

        <listitem>
            <para>
                Optionally, an array of options to pass as the second argument
                to <methodname>Zend_Json::encode()</methodname>. This array of options
                allows enabling layouts and encoding using
                <classname>Zend_Json_Expr</classname>.
            </para>

            <programlisting language="php"><![CDATA[
$this->_helper->json($data, array('enableJsonExprFinder' => true));
]]></programlisting>
        </listitem>

        <listitem>
            <para>
                Disables the ViewRenderer if currently enabled.
            </para>
        </listitem>

        <listitem>
            <para>
                Sets the 'Content-Type' response header to '<filename>application/json</filename>'.
            </para>
        </listitem>

        <listitem>
            <para>
                By default, immediately returns the response, without waiting
                for the action to finish execution.
            </para>
        </listitem>
    </itemizedlist>

    <para>
        Usage is simple: either call it as a method of the helper broker, or
        call one of the methods <methodname>encodeJson()</methodname> or
        <methodname>sendJson()</methodname>:
    </para>

    <programlisting language="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
    public function barAction()
    {
        // do some processing...
        // Send the JSON response:
        $this->_helper->json($data);

        // or...
        $this->_helper->json->sendJson($data);

        // or retrieve the json:
        $json = $this->_helper->json->encodeJson($data);
    }
}
]]></programlisting>

    <note>
        <title>Keeping Layouts</title>

        <para>
            If you have a separate layout for <acronym>JSON</acronym> responses -- perhaps to wrap
            the <acronym>JSON</acronym> response in some sort of context -- each method in the
            <acronym>JSON</acronym> helper accepts a second, optional argument: a flag to enable or
            disable layouts. Passing a boolean <constant>TRUE</constant> value will keep
            layouts enabled:
        </para>

        <programlisting language="php"><![CDATA[
$this->_helper->json($data, true);
]]></programlisting>

        <para>
            Optionally, you can pass an array as the second parameter. This
            array may contain a variety of options, including the
            <emphasis>keepLayouts</emphasis> option:
        </para>

        <programlisting language="php"><![CDATA[
$this->_helper->json($data, array('keepLayouts' => true);
]]></programlisting>
    </note>

    <note>
        <title>Enabling encoding using Zend_Json_Expr</title>

        <para>
            <methodname>Zend_Json::encode()</methodname> allows the encoding of native
            <acronym>JSON</acronym> expressions using <classname>Zend_Json_Expr</classname>
            objects. This option is disabled by default. To enable this option, pass a boolean
            <constant>TRUE</constant> value to the <emphasis>enableJsonExprFinder</emphasis>
            option:
        </para>

        <programlisting language="php"><![CDATA[
$this->_helper->json($data, array('enableJsonExprFinder' => true);
]]></programlisting>

        <para>
            If you desire to do this, you <emphasis>must</emphasis> pass an
            array as the second argument. This also allows you to combine other
            options, such as the <emphasis>keepLayouts</emphasis> option. All such
            options are then passed to <methodname>Zend_Json::encode()</methodname>.
        </para>

        <programlisting language="php"><![CDATA[
$this->_helper->json($data, array(
    'enableJsonExprFinder' => true,
    'keepLayouts'          => true,
));
]]></programlisting>
    </note>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->