[Pieforms-commit] SF.net SVN: pieforms: [237] pieforms-php5/trunk/doc/rst/user/templates.rst
Status: Alpha
Brought to you by:
oracleshinoda
Menu
▾
▴
[Pieforms-commit] SF.net SVN: pieforms: [237] pieforms-php5/trunk/doc/rst/user/templates.rst
|
From: <ora...@us...> - 2007-12-27 23:39:27
|
Revision: 237
http://pieforms.svn.sourceforge.net/pieforms/?rev=237&view=rev
Author: oracleshinoda
Date: 2007-12-27 15:39:31 -0800 (Thu, 27 Dec 2007)
Log Message:
-----------
Added documentation about templates.
Added Paths:
-----------
pieforms-php5/trunk/doc/rst/user/templates.rst
Added: pieforms-php5/trunk/doc/rst/user/templates.rst
===================================================================
--- pieforms-php5/trunk/doc/rst/user/templates.rst (rev 0)
+++ pieforms-php5/trunk/doc/rst/user/templates.rst 2007-12-27 23:39:31 UTC (rev 237)
@@ -0,0 +1,314 @@
+===================
+ Pieforms Elements
+===================
+:breadcrumbs:`Documentation Home > Pieforms Templates`
+
+:Author: Nigel McNie
+:Contact: ni...@ca...
+:Copyright: This document has been placed in the public domain
+
+.. contents::
+
+This document describes how you can lay out forms very precisely using
+templates rather than renderers.
+
+Overview
+========
+
+Imagine you have a form that you need to lay out quite precisely, compared to a
+typical form. Renderers assume that all elements will be layed out in a
+consistent manner, which makes them quite limiting in this situation. So
+instead, you can write a **template** for your form, that describes exactly how
+you want the form layed out.
+
+Using Templates
+===============
+
+There are two configuration elements you will be interested in if you are going
+to use templates:
+
+* The ``templatedir`` specifies in what directory (relative to PHP's include
+ path) templates will be searched for. You probably want to set this in your
+ ``pieform_configure()`` function, so that you do not have to specify it for
+ every form.
+* The ``template`` configuration element sets what file is to be used as a
+ template for this form. Unless you have written a generic template that
+ applies to many forms in your application, you probably want to set this on
+ the form itself.
+
+Here is an example of setting the ``templatedir`` and ``template``
+configuration elements on a form:
+
+.. highlight:: php/php5
+
+ <?php
+
+ $form = array(
+ 'name' => 'myform',
+ 'templatedir' => 'templates/',
+ 'template' => 'myform.php',
+ 'elements' => array(
+ ...
+ ),
+ ),
+ );
+
+ ?>
+
+In the above example, the ``templates/`` directory relative to PHP's include
+path will be searched for the ``myform.php`` file.
+
+An Example Template
+===================
+
+Let us assume that you have been tasked with laying out the blog post form you
+created as an example on the `basic usage <usage.html>`__ page in some
+different manner. Feedback from your users suggests that they would like the
+"Categories" multiple select to be to the right of the text area, and the
+"Publish Date" selector to be to the right of the "Post Title" textbox.
+
+This is not possible with a renderer, but with a template this is quite easy.
+We will simply write a template that outputs the elements in the correct
+places. Note that the existing form has a fieldset and the new form will not
+have one. When you use a template, Pieforms actually *ignores* fieldsets
+(although it keeps the elements inside them). So there is no need to change the
+form definition. For your reference, here is the current form definition and a
+screenshot of how the form is currently layed out:
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'blogpost',
+ 'method' => 'post',
+ 'autofocus' => true,
+ 'elements' => array(
+ 'title' => array(
+ 'type' => 'text',
+ 'title' => 'Post Title',
+ 'rules' => array(
+ 'required' => true,
+ ),
+ ),
+ 'content' => array(
+ 'type' => 'textarea',
+ 'title' => 'Content',
+ 'rules' => array(
+ 'required' => true,
+ ),
+ 'resizable' => true,
+ ),
+ 'optional' => array(
+ 'type' => 'fieldset',
+ 'legend' => 'Advanced Options...',
+ 'collapsible' => true,
+ 'collapsed' => true,
+ 'elements' => array(
+ 'categories' => array(
+ 'type' => 'select',
+ 'title' => 'Categories',
+ 'multiple' => true,
+ 'size' => 5,
+ 'options' => array(
+ 1 => 'Personal',
+ 2 => 'Rants',
+ 3 => 'Politics',
+ 4 => 'Religion',
+ 5 => 'Science',
+ 6 => 'Arts',
+ ),
+ ),
+ 'publishdate' => array(
+ 'type' => 'date',
+ 'title' => 'Publish Date',
+ ),
+ ),
+ ),
+ 'submit' => array(
+ 'type' => 'submitcancel',
+ 'value' => array('Enter New Post', 'Cancel'),
+ 'goto' => $_SERVER['SCRIPT_NAME'],
+ ),
+ )
+ ));
+
+ function blogpost_validate(Pieform $form, $values) {
+ if ($values['publishdate'] && $values['publishdate'] < time()) {
+ $form->set_error('publishdate', 'Sorry, your publish date must be in the future');
+ }
+ }
+
+ function blogpost_submit(Pieform $form, $values) {
+ echo <<<EOF
+ <p>Congratulations! New post entered. <a href="">Back to enter another one</a>...</p>
+ EOF;
+ exit;
+ }
+
+ ?>
+
+.. image:: ../../screenshots/usage-form-4.png
+ :alt: [The form we will be laying out]
+
+Step 1 - Specify Template Configuration Elements
+------------------------------------------------
+
+Add to the form configuration the ``templatedir`` and ``template`` configuration elements as shown:
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'blogpost',
+ 'method' => 'post',
+ 'autofocus' => true,
+ 'templatedir' => 'templates/',
+ 'template' => 'blogpost.php'
+ ...
+
+Step 2 - Create the Template
+----------------------------
+
+When you load the page after adding the template configuration elements, you
+will get something like the following:
+
+.. image:: ../../screenshots/template-missing-boom.png
+ :alt: [Fatal error: Pieform::require() [function.require]: Failed opening required 'templates/blogpost.php']
+
+Pieforms is complaining that it can't find your template. It tells you it was
+looking for ``templates/blogpost.php``, which matches the configuration we
+provided.
+
+Create the ``templates/`` directory somewhere relative to PHP's include path,
+and create ``blogpost.php`` in it, with the following contents:
+
+.. highlight:: php/php5
+
+ <?php
+
+ echo $form_tag;
+
+ foreach ($elements as $name => $element) {
+ echo '<div>' . $element['labelhtml'] . $element['html'] . ' ' . $element['helphtml'];
+ if ($element['description']) {
+ echo '<br><span style="font-size: smaller;">' . $element['description'] . '</span>';
+ }
+ echo '</div>';
+ if ($element['error']) {
+ echo '<div style="background-color: red;">' . $element['error'] . '</div>';
+ }
+ echo "\n";
+ }
+
+ echo $hidden_elements;
+ echo '</form>';
+
+ ?>
+
+This will give the following result:
+
+.. image:: ../../screenshots/form-template-1.png
+ :alt: [The form, very basically layed out in <div>s]
+
+.. NOTE:: You will see the PHP notice if your form definition has a fieldset in it. Pieforms is alerting you that fieldsets make no sense when using templates. You can safely ignore the notice, or edit the form definition to remove the fieldset. Of course, you will only see the notice if you have configured PHP to show notices anyway!
+
+As you can see from the template, there are some variables available to you that you can use:
+
+* ``$form_tag`` - This contains the <form> tag that Pieforms has generated for
+ your form. Naturally, it should be echo'd before any of the elements in the
+ form.
+* ``$elements`` - The elements of the form, in an associative array, ordered
+ the way they were defined. Rather than looping over this, you can just index
+ the array directly with an element name to get at the data for the element,
+ which is where much of the templating power comes from.
+
+ Fieldsets and hidden elements are not included in this variable.
+
+ Note that each element has several keys set on it, containing information
+ that you can use when building the form. Use ``print_r`` or similar to view
+ them all, but the major ones are:
+
+ * ``labelhtml`` - The HTML for the title of the element, including the
+ wrapping <label> HTML.
+ * ``html`` - The HTML for the element itself
+ * ``helphtml`` - The HTML for the help icon, if ``'help' => true`` was
+ specified on the element
+ * ``error`` - The error message, if the element failed validation
+* ``$hidden_elements`` - Contains any hidden elements for the form. **Always
+ output this**, as Pieforms adds at least one hidden element to help it detect
+ when the form has been submitted.
+
+Step 3 - Customise the template to suit your needs
+--------------------------------------------------
+
+10 minutes of playing around and I produced this:
+
+.. highlight:: php/php5
+
+ <?php echo $form_tag; ?>
+
+ <table>
+ <tr>
+ <th><?php echo $elements['title']['labelhtml']; ?></th>
+ <td>
+ <div style="float:right;">
+ <?php echo $elements['publishdate']['labelhtml'] . ': ' . $elements['publishdate']['html']; ?>
+ </div>
+ <?php echo $elements['title']['html'];
+ if ($elements['title']['error']) {
+ echo '<br><div style="color:red;">' . $elements['title']['error'] . '</div>';
+ } ?>
+ </td>
+ <td></td>
+ </tr>
+ <tr>
+ <th><?php echo $elements['content']['labelhtml']; ?></th>
+ <td><?php echo $elements['content']['html'];
+ if ($elements['content']['error']) {
+ echo '<br><div style="color:red;">' . $elements['content']['error'] . '</div>';
+ } ?></td>
+ <td style="vertical-align: top;">
+ <?php echo $elements['categories']['html']; ?>
+ </td>
+ </tr>
+ <tr>
+ <td></td>
+ <td><?php echo $elements['submit']['html']; ?></td>
+ </table>
+
+ <?php
+
+ echo $hidden_elements;
+ echo '</form>';
+
+ ?>
+
+Which renders like this:
+
+.. image:: ../../screenshots/form-template-2.png
+ :alt: [The form, layed out as required]
+
+Now the form is layed out as required. Try submitting the form, and the error
+messages for the title and content will be displayed if either one has not been
+specified.
+
+As you can see, it is trivial to achieve any layout you desire now. You could
+put all error messages at the top of the form if you want as well as or instead
+of putting the messages inline. You can change the order that elements are
+output in, or even perform some last minute modifications to the element HTML
+itself if you require (although you should try to keep away from doing this if
+you can!).
+
+Conclusion
+==========
+
+Templates give you a powerful way to lay out your forms when you need more
+control than what a renderer can provide.
+
+:breadcrumbs:`Documentation Home > Pieforms Templates`
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
