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>

    <sect4 id="zend.controller.actionhelpers.json.usage">
        <title>Usage</title>

        <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>

        <para>
            direct($data, $sendNow = true, $keepLayouts = false, $encodeData = true)
        </para>

        <para>
            sendJson($data, $keepLayouts = false, $encodeData = true)
        </para>

        <para>
            encodeJson($data, $keepLayouts = false, $encodeData = true)
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>$data</emphasis>: data to encode as JSON
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>$sendNow</emphasis>: flag to define whether
                    to send the JSON data immediately.  When true, the helper
                    will immediately set the respose body and exit.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>$keepLayouts</emphasis>: flag to define whether
                    to enable or disable layours.  When false, all layouts
                    are disabled.  Optionally, this can be 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>
            </listitem>
            <listitem>
                <para>
                    <emphasis>$encodeData</emphasis>: flag to define whether
                    <emphasis>$data</emphasis> is already JSON-encoded.  When
                    true, this helper will not encode <emphasis>$data</emphasis>
                    to JSON before sending.
                </para>
            </listitem>
        </itemizedlist>

        <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 an optional argument <emphasis>$keepLayouts</emphasis>: 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 third parameter. This
                array may contain a variety of options, including the
                <emphasis>keepLayouts</emphasis> option:
            </para>

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

// ...or, call a method of the helper
$this->_helper->sendJson($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, true, array('enableJsonExprFinder' => true);
]]></programlisting>

            <para>
                If you desire to do this, you <emphasis>must</emphasis> pass an
                array as the third 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, true, array(
'enableJsonExprFinder' => true,
'keepLayouts'          => true,
));
]]></programlisting>
        </note>
    </sect4>    

    <sect4 id="zend.controller.actionhelpers.json.example">
        <title>Example</title>

        <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>
    </sect4>
    
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->