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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.controller.actionhelpers.json">
   4     <title>JSON</title>
   5
   6     <para>
   7         <acronym>JSON</acronym> responses are rapidly becoming the response of choice when dealing
   8         with <acronym>AJAX</acronym> requests that expect dataset responses;
   9         <acronym>JSON</acronym> can be immediately parsed on the client-side, leading to quick
  10         execution.
  11     </para>
  12
  13     <para>
  14         The <acronym>JSON</acronym> action helper does several things:
  15     </para>
  16
  17     <itemizedlist>
  18         <listitem>
  19             <para>
  20                 Disables layouts if currently enabled.
  21             </para>
  22         </listitem>
  23
  24         <listitem>
  25             <para>
  26                 Optionally, an array of options to pass as the second argument
  27                 to <methodname>Zend_Json::encode()</methodname>. This array of options
  28                 allows enabling layouts and encoding using
  29                 <classname>Zend_Json_Expr</classname>.
  30             </para>
  31
  32             <programlisting language="php"><![CDATA[
  33 $this->_helper->json($data, array('enableJsonExprFinder' => true));
  34 ]]></programlisting>
  35         </listitem>
  36
  37         <listitem>
  38             <para>
  39                 Disables the ViewRenderer if currently enabled.
  40             </para>
  41         </listitem>
  42
  43         <listitem>
  44             <para>
  45                 Sets the 'Content-Type' response header to '<filename>application/json</filename>'.
  46             </para>
  47         </listitem>
  48
  49         <listitem>
  50             <para>
  51                 By default, immediately returns the response, without waiting
  52                 for the action to finish execution.
  53             </para>
  54         </listitem>
  55     </itemizedlist>
  56
  57     <para>
  58         Usage is simple: either call it as a method of the helper broker, or
  59         call one of the methods <methodname>encodeJson()</methodname> or
  60         <methodname>sendJson()</methodname>:
  61     </para>
  62
  63     <programlisting language="php"><![CDATA[
  64 class FooController extends Zend_Controller_Action
  65 {
  66     public function barAction()
  67     {
  68         // do some processing...
  69         // Send the JSON response:
  70         $this->_helper->json($data);
  71
  72         // or...
  73         $this->_helper->json->sendJson($data);
  74
  75         // or retrieve the json:
  76         $json = $this->_helper->json->encodeJson($data);
  77     }
  78 }
  79 ]]></programlisting>
  80
  81     <note>
  82         <title>Keeping Layouts</title>
  83
  84         <para>
  85             If you have a separate layout for <acronym>JSON</acronym> responses -- perhaps to wrap
  86             the <acronym>JSON</acronym> response in some sort of context -- each method in the
  87             <acronym>JSON</acronym> helper accepts a second, optional argument: a flag to enable or
  88             disable layouts. Passing a boolean <constant>TRUE</constant> value will keep
  89             layouts enabled:
  90         </para>
  91
  92         <programlisting language="php"><![CDATA[
  93 $this->_helper->json($data, true);
  94 ]]></programlisting>
  95
  96         <para>
  97             Optionally, you can pass an array as the second parameter. This
  98             array may contain a variety of options, including the
  99             <emphasis>keepLayouts</emphasis> option:
 100         </para>
 101
 102         <programlisting language="php"><![CDATA[
 103 $this->_helper->json($data, array('keepLayouts' => true);
 104 ]]></programlisting>
 105     </note>
 106
 107     <note>
 108         <title>Enabling encoding using Zend_Json_Expr</title>
 109
 110         <para>
 111             <methodname>Zend_Json::encode()</methodname> allows the encoding of native
 112             <acronym>JSON</acronym> expressions using <classname>Zend_Json_Expr</classname>
 113             objects. This option is disabled by default. To enable this option, pass a boolean
 114             <constant>TRUE</constant> value to the <emphasis>enableJsonExprFinder</emphasis>
 115             option:
 116         </para>
 117
 118         <programlisting language="php"><![CDATA[
 119 $this->_helper->json($data, array('enableJsonExprFinder' => true);
 120 ]]></programlisting>
 121
 122         <para>
 123             If you desire to do this, you <emphasis>must</emphasis> pass an
 124             array as the second argument. This also allows you to combine other
 125             options, such as the <emphasis>keepLayouts</emphasis> option. All such
 126             options are then passed to <methodname>Zend_Json::encode()</methodname>.
 127         </para>
 128
 129         <programlisting language="php"><![CDATA[
 130 $this->_helper->json($data, array(
 131     'enableJsonExprFinder' => true,
 132     'keepLayouts'          => true,
 133 ));
 134 ]]></programlisting>
 135     </note>
 136 </sect3>
 137 <!--
 138 vim:se ts=4 sw=4 et:
 139 -->