repo_zf1/documentation/manual/en/module_specs/Zend_View-Helpers-Json.xml

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

    <para>
        When creating views that return <acronym>JSON</acronym>, it's important to also set the
        appropriate response header. The <acronym>JSON</acronym> view helper does exactly that. In
        addition, by default, it disables layouts (if currently enabled), as
        layouts generally aren't used with <acronym>JSON</acronym> responses.
    </para>

    <para>
        The <acronym>JSON</acronym> helper sets the following header:
    </para>

    <programlisting language="text"><![CDATA[
Content-Type: application/json
]]></programlisting>

    <para>
        Most <acronym>AJAX</acronym> libraries look for this header when parsing responses to
        determine how to handle the content.
    </para>

    <para>
        Usage of the <acronym>JSON</acronym> helper is very straightforward:
    </para>

    <programlisting language="php"><![CDATA[
<?php echo $this->json($this->data) ?>
]]></programlisting>

    <note>
        <title>Keeping layouts and enabling encoding using Zend_Json_Expr</title>

        <para>
            Each method in the <acronym>JSON</acronym> helper accepts a second, optional argument.
            This second argument can be a boolean flag to enable or disable
            layouts, or an array of options that will be passed to
            <methodname>Zend_Json::encode()</methodname> and used internally to encode data.
        </para>

        <para>
            To keep layouts, the second parameter needs to be boolean
            <constant>TRUE</constant>. When the second parameter is an array, keeping
            layouts can be achieved by including a <property>keepLayouts</property> key
            with a value of a boolean <constant>TRUE</constant>.
        </para>

        <programlisting language="php"><![CDATA[
// Boolean true as second argument enables layouts:
echo $this->json($this->data, true);

// Or boolean true as "keepLayouts" key:
echo $this->json($this->data, array('keepLayouts' => true));
]]></programlisting>

        <para>
            <classname>Zend_Json::encode</classname> 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> to the <property>enableJsonExprFinder</property> key of
            the options array:
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->json($this->data, array(
    'enableJsonExprFinder' => true,
    'keepLayouts'          => true,
)) ?>
]]></programlisting>
    </note>
    
    <note>
        <title>Sending pre-encoded JSON</title>

        <para>
            By default, the <acronym>JSON</acronym> helper will JSON-encode the 
            data provided to the helper's first parameter.  If you wish to pass 
            in data which has already been encoded into <acronym>JSON</acronym>, 
            the third parameter needs to be set to boolean <constant>FALSE</constant>.  
            When the second parameter is an array, disabling <acronym>JSON</acronym> 
            encoding can be achived by including a <property>encodeData</property> 
            key with the value of boolean <constant>FALSE</constant>:
        </para>

        <programlisting language="php"><![CDATA[
// Boolean false as third argument disables internal JSON encoding of data
echo $this->json($this->data, false, false);

// Or boolean false as "encodeData" key:
echo $this->json($this->data, array('encodeData' => false));
]]></programlisting>

    </note>
    
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->