cvs: peardoc /en/package/html html-quickform-controller.xml /en/package/html/html-quickform-controller faq.xml
| From: | Alexey Borzov | Date: | Sun, 26 Oct 2003 15:56:17 +0000 |
| Subject: | cvs: peardoc /en/package/html html-quickform-controller.xml /en/package/html/html-quickform-controller faq.xml | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-1756@lists.php.net to get a copy of this message | ||
avb Sun Oct 26 10:56:17 2003 EDT
Added files:
/peardoc/en/package/html/html-quickform-controller faq.xml
Modified files:
/peardoc/en/package/html html-quickform-controller.xml
Log:
Added (sort of) FAQ for QFC
Index: peardoc/en/package/html/html-quickform-controller.xml diff -u peardoc/en/package/html/html-quickform-controller.xml:1.4 peardoc/en/package/html/html-quickform-controller.xml:1.5 --- peardoc/en/package/html/html-quickform-controller.xml:1.4 Tue Oct 14 18:54:22 2003 +++ peardoc/en/package/html/html-quickform-controller.xml Sun Oct 26 10:56:17 2003 @@ -1,4 +1,4 @@ -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <sect1 id="package.html.html-quickform-controller"> <title>HTML_QuickForm_Controller</title> <para> @@ -18,6 +18,7 @@ </para> &package.html.html-quickform-controller.intro; +&package.html.html-quickform-controller.faq; <refentry id="package.html.html-quickform-controller.html-quickform-controller-summary"> @@ -26,7 +27,7 @@ <refpurpose>The class implementing a PageController pattern.</refpurpose> </refnamediv> <refsect1> - <title>The class implementing a PageController pattern.</title> + &title.desc; <para>This class keeps track of pages and (default) action handlers for the form, it manages keeping the form values in session, setting defaults and constants for the form as a whole and getting its submit values.</para> <para>Generally you don't need to subclass this.</para> @@ -68,7 +69,7 @@ <refpurpose>The class represents a page of a multipage form.</refpurpose> </refnamediv> <refsect1> - <title>The class represents a page of a multipage form.</title> + &title.desc; <para>Generally you'll need to subclass this and define your <link linkend="package.html.html-quickform-controller.html-quickform-page.buildform"><function>buildForm</function></link> method that will build the form. While it is also possible to instantiate this class and build the form manually, this is not the recommended way.</para> </refsect1> @@ -104,12 +105,15 @@ <refpurpose>Class representing an action to perform on HTTP request.</refpurpose> </refnamediv> <refsect1> - <title>Class representing an action to perform on HTTP request. </title> + &title.desc; <para> The Controller will select the appropriate Action to call on the request and call its <link linkend="package.html.html-quickform-controller.html-quickform-action.perform"><function>perform</function></link> method. The subclasses of this class should implement all the necessary business logic. </para> +<para> +The default action handlers are described in the <link linkend="package.html.html-quickform-controller.faq.actions.default">FAQ section</link>. +</para> </refsect1> <refsect1> <title>Class Trees for <classname>HTML_QuickForm_Action</classname></title> @@ -170,7 +174,7 @@ <refpurpose>The action for a 'back' button of wizard-type multipage form.</refpurpose> </refnamediv> <refsect1> - <title>The action for a 'back' button of wizard-type multipage form.</title> + &title.desc; ¬documented; </refsect1> <refsect1> @@ -197,7 +201,7 @@ <refpurpose>This action allows to go to a specific page of a multipage form.</refpurpose> </refnamediv> <refsect1> - <title>This action allows to go to a specific page of a multipage form.</title> + &title.desc; <para>Please note that the name for this action in <function>addAction</function> should NOT be <literal>'direct'</literal>, but the name of the page you wish to go to.</para> </refsect1> @@ -225,7 +229,7 @@ <refpurpose>This action handles the output of the form.</refpurpose> </refnamediv> <refsect1> - <title>This action handles the output of the form.</title> + &title.desc; <para>If you want to customize the form display, subclass this class and override the <function>_renderForm</function> method, you don't need to change the <function>perform</function> method itself.</para> </refsect1> @@ -255,7 +259,7 @@ <refpurpose>The action handles the HTTP redirect to a specific page.</refpurpose> </refnamediv> <refsect1> - <title>The action handles the HTTP redirect to a specific page.</title> + &title.desc; ¬documented; </refsect1> <refsect1> @@ -282,7 +286,7 @@ <refpurpose>The action for a 'next' button of wizard-type multipage form.</refpurpose> </refnamediv> <refsect1> - <title>The action for a 'next' button of wizard-type multipage form.</title> + &title.desc; ¬documented; </refsect1> <refsect1> @@ -309,7 +313,7 @@ <refpurpose>The action for a 'submit' button.</refpurpose> </refnamediv> <refsect1> - <title>The action for a 'submit' button.</title> + &title.desc; ¬documented; </refsect1> <refsect1> Index: peardoc/en/package/html/html-quickform-controller/faq.xml +++ peardoc/en/package/html/html-quickform-controller/faq.xml <!-- $Revision: 1.1 $ --> <refentry id="package.html.html-quickform-controller.faq"> <refnamediv> <refname>FAQ</refname> <refpurpose>Understanding package features</refpurpose> </refnamediv> <refsect1 id="package.html.html-quickform-controller.faq.desc"> &title.desc; <para> This document is based on questions asked on <ulink url="mailto:&email.pear.general">PEAR general mailing list</ulink>. You are encouraged to search the list archives to find more verbose answers and examples. </para> </refsect1> <refsect1 id="package.html.html-quickform-controller.faq.noob"> <title>The package is so complex! I don't understand anything!</title> <para> Sorry, <classname>HTML_QuickForm_Controller</classname> is not intended for PHP newbies. If you don't understand what classes are, if you have no prior experience with QuickForm, if you are a fan of copy-paste programming then this package is not for you. </para> <para> The package is indeed complex, but so are the problems it is trying to solve. Try to rewrite any of the enclosed multipage form examples without using such a package and you'll see what we mean. </para> </refsect1> <refsect1 id="package.html.html-quickform-controller.faq.actions"> <title>Meta-question: actions</title> <para> To avoid confusion lets use the terms "action" for the string containing the name of the action and "action handler" for the subclass of <link linkend="package.html.html-quickform-controller.html-quickform-action-back-summary"><classname>HTML_QuickForm_Action</classname></link>. </para> <refsect2 id="package.html.html-quickform-controller.faq.actions.default"> <title>Default actions and default action handlers</title> <para> While you can invent your own action names and create custom handlers for them, you'll most certainly have to deal with the default actions and their handlers first. </para> <variablelist> <title>Default action names</title> <varlistentry> <term><literal>'display'</literal></term> <listitem><para> This action has a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-display-summary"><classname>HTML_QuickForm_Action_Display</classname></link>, which displays the form using the Default renderer. You should subclass this handler if you want to customize the form output. This action is called automatically when the page needs to be displayed and should <emphasis>not</emphasis> be bound to buttons via <function>getButtonName</function>. </para></listitem> </varlistentry> <varlistentry> <term><literal>'submit'</literal></term> <listitem><para> This action should be bound to a "global" submit button for a form. It can be the "submit" button of a single-page or tabbed multi-page form, "finish" button of a wizard. This action has a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-submit-summary"><classname>HTML_QuickForm_Action_Submit</classname></link>, which checks whether all the pages of the form are valid, then either calls the <literal>'process'</literal> handler or displays the invalid page. </para></listitem> </varlistentry> <varlistentry> <term><literal>'next'</literal></term> <listitem><para> This action should be bound to the "Next" button of (usually) a modal multipage form (AKA wizard). This action has a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-next-summary"><classname>HTML_QuickForm_Action_Next</classname></link>, which checks the validity of the current page and redirects to the next one if the current is valid (or if the form is not modal). On the last page of a modal multipage form this behaves like the default <literal>'submit'</literal> handler. </para></listitem> </varlistentry> <varlistentry> <term><literal>'back'</literal></term> <listitem><para> This action should be bound to the "Back" button of (usually) a modal multipage form (AKA wizard). This action has a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-back-summary"><classname>HTML_QuickForm_Action_Back</classname></link>, which redirects to the previous page if one exists. As of QFC 0.9.3, no form validation takes place on <literal>'back'</literal> action. </para></listitem> </varlistentry> <varlistentry> <term><literal>'jump'</literal></term> <listitem><para> This action has a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-jump-summary"><classname>HTML_QuickForm_Action_Jump</classname></link>, which just makes HTTP redirect to the given page of the form. This action should <emphasis>not</emphasis> be bound to buttons via <function>getButtonName</function>. </para></listitem> </varlistentry> <varlistentry> <term><literal>'process'</literal></term> <listitem><para> This is the action called by default <literal>'submit'</literal> and <literal>'next'</literal> (on the last page of the wizard only) handlers after successful (i.e. without validation errors) form submit. This action doesn't have a default handler, you should define the custom one yourself and implement all the necessary logic to process the form's values in it. </para></listitem> </varlistentry> </variablelist> <para>There is also a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-direct-summary"><classname>HTML_QuickForm_Action_Direct</classname></link>, that does <emphasis>not</emphasis> have a default action name. It is used to go to the specific page of the form and should be explicitly added via <link linkend="package.html.html-quickform-controller.html-quickform-page.addaction"><function>Page::addAction</function></link> or <link linkend="package.html.html-quickform-controller.html-quickform-controller.addaction"><function>Controller::addAction</function></link> with the name of the target page as <parameter>$actionName</parameter> and bound to buttons via <function>getButtonName</function> using the same name. </para> </refsect2> <refsect2 id="package.html.html-quickform-controller.faq.actions.call"> <title>How to call an action handler?</title> <para> You should use <classname>Page</classname>'s <link linkend="package.html.html-quickform-controller.html-quickform-page.handle">handle</link> method: <programlisting role="php"> <![CDATA[ $page->handle('action'); ]]> </programlisting> <classname>Controller</classname>'s <link linkend="package.html.html-quickform-controller.html-quickform-controller.handle">handle</link> method will be called automatically if needed. </para> </refsect2> <refsect2 id="package.html.html-quickform-controller.faq.actions.custom"> <title>How to make a custom action?</title> <para> Create a subclass of <link linkend="package.html.html-quickform-controller.html-quickform-action-summary"><classname>HTML_QuickForm_Action</classname></link>, add the necessary logic to its <function>perform</function> method. Add it to the <classname>Page</classname> or to the <classname>Controller</classname> via <function>addAction</function> with the appropriate name. </para> <para> If you intend to bind this action to some button via <function>getButtonName</function>, you should care about storing values in the <link linkend="package.html.html-quickform-controller.html-quickform-controller.container"><function>container</function></link>: <orderedlist> <listitem><para>Build the form.</para></listitem> <listitem><para>Get a reference to container.</para></listitem> <listitem><para>Fill the container's <varname>['values'][$pageName]</varname> and <varname>['valid'][$pageName]</varname> elements.</para></listitem> </orderedlist> </para> <para> As usual, see the default action handlers' source for the examples. </para> </refsect2> </refsect1> <refsect1 id="package.html.html-quickform-controller.faq.additional-data"> <title>How to pass additional data between pages of the form?</title> <para> The answer is quite simple: you need to use the <link linkend="package.html.html-quickform-controller.html-quickform-controller.container"><function>container</function></link> method of <classname>HTML_QuickForm_Controller</classname>, like this: <programlisting role="php"> <![CDATA[ // Note the reference $data =& $page->controller->container(); $data['_my_stuff'] = $stuff; ]]> </programlisting> On the target page you do <programlisting role="php"> <![CDATA[ $data =& $page->controller->container(); $stuff = $data['_my_stuff']; ]]> </programlisting> Please use some prefix for your fields or start their names with underscore to prevent possible name conflicts with the future versions of QFC. </para> <para> Please note that <classname>Controller</classname> knows nothing about your additional data, so do not expect it to return it via <link linkend="package.html.html-quickform-controller.html-quickform-controller.exportvalues"><function>exportValues</function></link> method or the like. You'll have to use the <link linkend="package.html.html-quickform-controller.html-quickform-controller.container"><function>container</function></link> method and extract the data yourself. However, your data <emphasis>will</emphasis> be deleted when the container is reset. </para> </refsect1> <refsect1 id="package.html.html-quickform-controller.faq.renderers"> <title>How to use template-based renderers?</title> <para> First of all, please understand that <classname>HTML_QuickForm_Page</classname> is a subclass of <classname>HTML_QuickForm</classname>, thus everything that applies to the parent class will apply to the child. You are encouraged to read the <link linkend="package.html.html-quickform.intro-renderers">section about renderers</link> in <classname>HTML_QuickForm</classname> and the docs to the renderer you are trying to use. The usage examples are available in <filename class="directory">docs/renderers/</filename> directory of QuickForm distribution. </para> <para> As was already pointed out, you should subclass the <link linkend="package.html.html-quickform-controller.html-quickform-action-display-summary"><classname>HTML_QuickForm_Action_Display</classname></link> class if you want to customize the form output and add an instance of this subclass as a handler for Page's <literal>'display'</literal> action. Its <function>_renderForm</function> will contain all renderer-specific code. </para> <para> The only new problem <classname>Controller</classname> introduces is the buttons bound to specific actions via <link linkend="package.html.html-quickform-controller.html-quickform-page.getbuttonname"><function>getButtonName</function></link>. If you are using some kind of Dynamic renderer this will not be a problem, as you need not care about the elements names, but you need these names to output the form via Static renderer. </para> <para> We'll assume using <link linkend="package.html.html-quickform.html-quickform-renderer-itstatic">ITStatic renderer</link> but the same can be applied to other Static renderers as well. You basically have 3 options: <orderedlist> <listitem><para>Manually add the buttons/placeholders with the names that should be autogenerated via <link linkend="package.html.html-quickform-controller.html-quickform-page.getbuttonname"><function>getButtonName</function></link> to the form. This is <emphasis>not recommended</emphasis>, as the names should not be of interest to anyone except <classname>Controller</classname> itself and should not be used directly.</para></listitem> <listitem><para>Put the auto-named buttons into <link linkend="package.html.html-quickform.groups">group</link>. You can name the group any way you like, just be sure to set <parameter>$appendName</parameter> to false. When ITStatic sees <varname>{form_element_html}</varname> placeholder, it'll assign group's HTML to it.</para></listitem> <listitem><para>Call <function>getButtonName</function> from within template. Add the following to the template <programlisting> <![CDATA[ <input type="submit" value="Bla-bla" name="func_buttonName('action')" ... /> ]]> </programlisting> and the following to the <function>_renderForm</function> method of your custom <classname>HTML_QuickForm_Action_Display</classname> subclass <programlisting role="php"> <![CDATA[ $tpl->setCallbackFunction('buttonName', array(&$page, 'getButtonName')); ]]> </programlisting> This code will work with <classname>HTML_Template_Sigma</classname>, <classname>HTML_Template_ITX</classname> (note the X) will require some more tweaking. </para></listitem> </orderedlist> </para> </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-executeMultiple-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->
Index: peardoc/en/package/html/html-quickform-controller.xml diff -u peardoc/en/package/html/html-quickform-controller.xml:1.4 peardoc/en/package/html/html-quickform-controller.xml:1.5 --- peardoc/en/package/html/html-quickform-controller.xml:1.4 Tue Oct 14 18:54:22 2003 +++ peardoc/en/package/html/html-quickform-controller.xml Sun Oct 26 10:56:17 2003 @@ -1,4 +1,4 @@ -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <sect1 id="package.html.html-quickform-controller"> <title>HTML_QuickForm_Controller</title> <para> @@ -18,6 +18,7 @@ </para> &package.html.html-quickform-controller.intro; +&package.html.html-quickform-controller.faq; <refentry id="package.html.html-quickform-controller.html-quickform-controller-summary"> @@ -26,7 +27,7 @@ <refpurpose>The class implementing a PageController pattern.</refpurpose> </refnamediv> <refsect1> - <title>The class implementing a PageController pattern.</title> + &title.desc; <para>This class keeps track of pages and (default) action handlers for the form, it manages keeping the form values in session, setting defaults and constants for the form as a whole and getting its submit values.</para> <para>Generally you don't need to subclass this.</para> @@ -68,7 +69,7 @@ <refpurpose>The class represents a page of a multipage form.</refpurpose> </refnamediv> <refsect1> - <title>The class represents a page of a multipage form.</title> + &title.desc; <para>Generally you'll need to subclass this and define your <link linkend="package.html.html-quickform-controller.html-quickform-page.buildform"><function>buildForm</function></link> method that will build the form. While it is also possible to instantiate this class and build the form manually, this is not the recommended way.</para> </refsect1> @@ -104,12 +105,15 @@ <refpurpose>Class representing an action to perform on HTTP request.</refpurpose> </refnamediv> <refsect1> - <title>Class representing an action to perform on HTTP request. </title> + &title.desc; <para> The Controller will select the appropriate Action to call on the request and call its <link linkend="package.html.html-quickform-controller.html-quickform-action.perform"><function>perform</function></link> method. The subclasses of this class should implement all the necessary business logic. </para> +<para> +The default action handlers are described in the <link linkend="package.html.html-quickform-controller.faq.actions.default">FAQ section</link>. +</para> </refsect1> <refsect1> <title>Class Trees for <classname>HTML_QuickForm_Action</classname></title> @@ -170,7 +174,7 @@ <refpurpose>The action for a 'back' button of wizard-type multipage form.</refpurpose> </refnamediv> <refsect1> - <title>The action for a 'back' button of wizard-type multipage form.</title> + &title.desc; ¬documented; </refsect1> <refsect1> @@ -197,7 +201,7 @@ <refpurpose>This action allows to go to a specific page of a multipage form.</refpurpose> </refnamediv> <refsect1> - <title>This action allows to go to a specific page of a multipage form.</title> + &title.desc; <para>Please note that the name for this action in <function>addAction</function> should NOT be <literal>'direct'</literal>, but the name of the page you wish to go to.</para> </refsect1> @@ -225,7 +229,7 @@ <refpurpose>This action handles the output of the form.</refpurpose> </refnamediv> <refsect1> - <title>This action handles the output of the form.</title> + &title.desc; <para>If you want to customize the form display, subclass this class and override the <function>_renderForm</function> method, you don't need to change the <function>perform</function> method itself.</para> </refsect1> @@ -255,7 +259,7 @@ <refpurpose>The action handles the HTTP redirect to a specific page.</refpurpose> </refnamediv> <refsect1> - <title>The action handles the HTTP redirect to a specific page.</title> + &title.desc; ¬documented; </refsect1> <refsect1> @@ -282,7 +286,7 @@ <refpurpose>The action for a 'next' button of wizard-type multipage form.</refpurpose> </refnamediv> <refsect1> - <title>The action for a 'next' button of wizard-type multipage form.</title> + &title.desc; ¬documented; </refsect1> <refsect1> @@ -309,7 +313,7 @@ <refpurpose>The action for a 'submit' button.</refpurpose> </refnamediv> <refsect1> - <title>The action for a 'submit' button.</title> + &title.desc; ¬documented; </refsect1> <refsect1> Index: peardoc/en/package/html/html-quickform-controller/faq.xml +++ peardoc/en/package/html/html-quickform-controller/faq.xml <!-- $Revision: 1.1 $ --> <refentry id="package.html.html-quickform-controller.faq"> <refnamediv> <refname>FAQ</refname> <refpurpose>Understanding package features</refpurpose> </refnamediv> <refsect1 id="package.html.html-quickform-controller.faq.desc"> &title.desc; <para> This document is based on questions asked on <ulink url="mailto:&email.pear.general">PEAR general mailing list</ulink>. You are encouraged to search the list archives to find more verbose answers and examples. </para> </refsect1> <refsect1 id="package.html.html-quickform-controller.faq.noob"> <title>The package is so complex! I don't understand anything!</title> <para> Sorry, <classname>HTML_QuickForm_Controller</classname> is not intended for PHP newbies. If you don't understand what classes are, if you have no prior experience with QuickForm, if you are a fan of copy-paste programming then this package is not for you. </para> <para> The package is indeed complex, but so are the problems it is trying to solve. Try to rewrite any of the enclosed multipage form examples without using such a package and you'll see what we mean. </para> </refsect1> <refsect1 id="package.html.html-quickform-controller.faq.actions"> <title>Meta-question: actions</title> <para> To avoid confusion lets use the terms "action" for the string containing the name of the action and "action handler" for the subclass of <link linkend="package.html.html-quickform-controller.html-quickform-action-back-summary"><classname>HTML_QuickForm_Action</classname></link>. </para> <refsect2 id="package.html.html-quickform-controller.faq.actions.default"> <title>Default actions and default action handlers</title> <para> While you can invent your own action names and create custom handlers for them, you'll most certainly have to deal with the default actions and their handlers first. </para> <variablelist> <title>Default action names</title> <varlistentry> <term><literal>'display'</literal></term> <listitem><para> This action has a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-display-summary"><classname>HTML_QuickForm_Action_Display</classname></link>, which displays the form using the Default renderer. You should subclass this handler if you want to customize the form output. This action is called automatically when the page needs to be displayed and should <emphasis>not</emphasis> be bound to buttons via <function>getButtonName</function>. </para></listitem> </varlistentry> <varlistentry> <term><literal>'submit'</literal></term> <listitem><para> This action should be bound to a "global" submit button for a form. It can be the "submit" button of a single-page or tabbed multi-page form, "finish" button of a wizard. This action has a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-submit-summary"><classname>HTML_QuickForm_Action_Submit</classname></link>, which checks whether all the pages of the form are valid, then either calls the <literal>'process'</literal> handler or displays the invalid page. </para></listitem> </varlistentry> <varlistentry> <term><literal>'next'</literal></term> <listitem><para> This action should be bound to the "Next" button of (usually) a modal multipage form (AKA wizard). This action has a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-next-summary"><classname>HTML_QuickForm_Action_Next</classname></link>, which checks the validity of the current page and redirects to the next one if the current is valid (or if the form is not modal). On the last page of a modal multipage form this behaves like the default <literal>'submit'</literal> handler. </para></listitem> </varlistentry> <varlistentry> <term><literal>'back'</literal></term> <listitem><para> This action should be bound to the "Back" button of (usually) a modal multipage form (AKA wizard). This action has a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-back-summary"><classname>HTML_QuickForm_Action_Back</classname></link>, which redirects to the previous page if one exists. As of QFC 0.9.3, no form validation takes place on <literal>'back'</literal> action. </para></listitem> </varlistentry> <varlistentry> <term><literal>'jump'</literal></term> <listitem><para> This action has a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-jump-summary"><classname>HTML_QuickForm_Action_Jump</classname></link>, which just makes HTTP redirect to the given page of the form. This action should <emphasis>not</emphasis> be bound to buttons via <function>getButtonName</function>. </para></listitem> </varlistentry> <varlistentry> <term><literal>'process'</literal></term> <listitem><para> This is the action called by default <literal>'submit'</literal> and <literal>'next'</literal> (on the last page of the wizard only) handlers after successful (i.e. without validation errors) form submit. This action doesn't have a default handler, you should define the custom one yourself and implement all the necessary logic to process the form's values in it. </para></listitem> </varlistentry> </variablelist> <para>There is also a default handler, <link linkend="package.html.html-quickform-controller.html-quickform-action-direct-summary"><classname>HTML_QuickForm_Action_Direct</classname></link>, that does <emphasis>not</emphasis> have a default action name. It is used to go to the specific page of the form and should be explicitly added via <link linkend="package.html.html-quickform-controller.html-quickform-page.addaction"><function>Page::addAction</function></link> or <link linkend="package.html.html-quickform-controller.html-quickform-controller.addaction"><function>Controller::addAction</function></link> with the name of the target page as <parameter>$actionName</parameter> and bound to buttons via <function>getButtonName</function> using the same name. </para> </refsect2> <refsect2 id="package.html.html-quickform-controller.faq.actions.call"> <title>How to call an action handler?</title> <para> You should use <classname>Page</classname>'s <link linkend="package.html.html-quickform-controller.html-quickform-page.handle">handle</link> method: <programlisting role="php"> <![CDATA[ $page->handle('action'); ]]> </programlisting> <classname>Controller</classname>'s <link linkend="package.html.html-quickform-controller.html-quickform-controller.handle">handle</link> method will be called automatically if needed. </para> </refsect2> <refsect2 id="package.html.html-quickform-controller.faq.actions.custom"> <title>How to make a custom action?</title> <para> Create a subclass of <link linkend="package.html.html-quickform-controller.html-quickform-action-summary"><classname>HTML_QuickForm_Action</classname></link>, add the necessary logic to its <function>perform</function> method. Add it to the <classname>Page</classname> or to the <classname>Controller</classname> via <function>addAction</function> with the appropriate name. </para> <para> If you intend to bind this action to some button via <function>getButtonName</function>, you should care about storing values in the <link linkend="package.html.html-quickform-controller.html-quickform-controller.container"><function>container</function></link>: <orderedlist> <listitem><para>Build the form.</para></listitem> <listitem><para>Get a reference to container.</para></listitem> <listitem><para>Fill the container's <varname>['values'][$pageName]</varname> and <varname>['valid'][$pageName]</varname> elements.</para></listitem> </orderedlist> </para> <para> As usual, see the default action handlers' source for the examples. </para> </refsect2> </refsect1> <refsect1 id="package.html.html-quickform-controller.faq.additional-data"> <title>How to pass additional data between pages of the form?</title> <para> The answer is quite simple: you need to use the <link linkend="package.html.html-quickform-controller.html-quickform-controller.container"><function>container</function></link> method of <classname>HTML_QuickForm_Controller</classname>, like this: <programlisting role="php"> <![CDATA[ // Note the reference $data =& $page->controller->container(); $data['_my_stuff'] = $stuff; ]]> </programlisting> On the target page you do <programlisting role="php"> <![CDATA[ $data =& $page->controller->container(); $stuff = $data['_my_stuff']; ]]> </programlisting> Please use some prefix for your fields or start their names with underscore to prevent possible name conflicts with the future versions of QFC. </para> <para> Please note that <classname>Controller</classname> knows nothing about your additional data, so do not expect it to return it via <link linkend="package.html.html-quickform-controller.html-quickform-controller.exportvalues"><function>exportValues</function></link> method or the like. You'll have to use the <link linkend="package.html.html-quickform-controller.html-quickform-controller.container"><function>container</function></link> method and extract the data yourself. However, your data <emphasis>will</emphasis> be deleted when the container is reset. </para> </refsect1> <refsect1 id="package.html.html-quickform-controller.faq.renderers"> <title>How to use template-based renderers?</title> <para> First of all, please understand that <classname>HTML_QuickForm_Page</classname> is a subclass of <classname>HTML_QuickForm</classname>, thus everything that applies to the parent class will apply to the child. You are encouraged to read the <link linkend="package.html.html-quickform.intro-renderers">section about renderers</link> in <classname>HTML_QuickForm</classname> and the docs to the renderer you are trying to use. The usage examples are available in <filename class="directory">docs/renderers/</filename> directory of QuickForm distribution. </para> <para> As was already pointed out, you should subclass the <link linkend="package.html.html-quickform-controller.html-quickform-action-display-summary"><classname>HTML_QuickForm_Action_Display</classname></link> class if you want to customize the form output and add an instance of this subclass as a handler for Page's <literal>'display'</literal> action. Its <function>_renderForm</function> will contain all renderer-specific code. </para> <para> The only new problem <classname>Controller</classname> introduces is the buttons bound to specific actions via <link linkend="package.html.html-quickform-controller.html-quickform-page.getbuttonname"><function>getButtonName</function></link>. If you are using some kind of Dynamic renderer this will not be a problem, as you need not care about the elements names, but you need these names to output the form via Static renderer. </para> <para> We'll assume using <link linkend="package.html.html-quickform.html-quickform-renderer-itstatic">ITStatic renderer</link> but the same can be applied to other Static renderers as well. You basically have 3 options: <orderedlist> <listitem><para>Manually add the buttons/placeholders with the names that should be autogenerated via <link linkend="package.html.html-quickform-controller.html-quickform-page.getbuttonname"><function>getButtonName</function></link> to the form. This is <emphasis>not recommended</emphasis>, as the names should not be of interest to anyone except <classname>Controller</classname> itself and should not be used directly.</para></listitem> <listitem><para>Put the auto-named buttons into <link linkend="package.html.html-quickform.groups">group</link>. You can name the group any way you like, just be sure to set <parameter>$appendName</parameter> to false. When ITStatic sees <varname>{form_element_html}</varname> placeholder, it'll assign group's HTML to it.</para></listitem> <listitem><para>Call <function>getButtonName</function> from within template. Add the following to the template <programlisting> <![CDATA[ <input type="submit" value="Bla-bla" name="func_buttonName('action')" ... /> ]]> </programlisting> and the following to the <function>_renderForm</function> method of your custom <classname>HTML_QuickForm_Action_Display</classname> subclass <programlisting role="php"> <![CDATA[ $tpl->setCallbackFunction('buttonName', array(&$page, 'getButtonName')); ]]> </programlisting> This code will work with <classname>HTML_Template_Sigma</classname>, <classname>HTML_Template_ITX</classname> (note the X) will require some more tweaking. </para></listitem> </orderedlist> </para> </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-executeMultiple-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->