[Pieforms-commit] SF.net SVN: pieforms: [234] pieforms-php5/trunk/doc/rst/user/usage.rst
Status: Alpha
Brought to you by:
oracleshinoda
Menu
▾
▴
[Pieforms-commit] SF.net SVN: pieforms: [234] pieforms-php5/trunk/doc/rst/user/usage.rst
|
From: <ora...@us...> - 2007-12-27 23:30:24
|
Revision: 234
http://pieforms.svn.sourceforge.net/pieforms/?rev=234&view=rev
Author: oracleshinoda
Date: 2007-12-27 15:30:27 -0800 (Thu, 27 Dec 2007)
Log Message:
-----------
Added screenshots to this document (badly needed!). Corrected some mistakes as some elements have changed.
Modified Paths:
--------------
pieforms-php5/trunk/doc/rst/user/usage.rst
Modified: pieforms-php5/trunk/doc/rst/user/usage.rst
===================================================================
--- pieforms-php5/trunk/doc/rst/user/usage.rst 2007-12-27 23:26:59 UTC (rev 233)
+++ pieforms-php5/trunk/doc/rst/user/usage.rst 2007-12-27 23:30:27 UTC (rev 234)
@@ -24,7 +24,9 @@
Your First Pieform
==================
-For the sake of argument, let us assume that you are writing a blogging application, and that your current task is to write a form into which new posts will be entered. This form will consist of:
+For the sake of argument, let us assume that you are writing a blogging
+application, and that your current task is to write a form into which new posts
+will be entered. This form will consist of:
* A text box, for the subject
* A textarea, for the post content
@@ -32,14 +34,18 @@
* A date field for choosing the date on which the post will become viewable, defaulting to the current date
* A submit and cancel button
-Also, for the sake of argument, let us assume that the category selection and date fields are optional and not really used that much, so we will place them in a fieldset and collapse it by default, to make the form seem simpler for general use.
+Also, for the sake of argument, let us assume that the category selection and
+date fields are optional and not really used that much, so we will place them
+in a fieldset and collapse it by default, to make the form seem simpler for
+general use.
So, given these requirements, let's get started!
The Basics
----------
-We shall start with the basic page shell, and build the pieces as required. Here is the most basic shell:
+We shall start with the basic page shell, and build the pieces as required.
+Here is the most basic shell:
.. highlight:: php/php5
@@ -53,9 +59,13 @@
And here is the output you get when running this:
-[insert screenshot here of boom]
+.. image:: ../../screenshots/no-configuration-boom.png
+ :alt: [Fatal error: Uncaught exception 'PieformException' with message 'Forms must have a name, and that name must be valid (validity test: could you give a PHP function the name?)']
-Whoops! Pieforms forms **must** have a name. This name is used on the client side to identify the form, and on the server side to provide unique names for the validation/submission callbacks. More on those later, but for now let's add some of the most basic parameters required:
+Whoops! Pieforms forms **must** have a name. This name is used on the client
+side to identify the form, and on the server side to provide unique names for
+the validation/submission callbacks. More on those later, but for now let's add
+some of the most basic parameters required:
.. highlight:: php/php5
@@ -65,12 +75,13 @@
echo pieform(array(
'name' => 'blogpost',
- 'method' => 'post'
+ 'method' => 'post',
));
?>
-[insert screenshot of boom]
+.. image:: ../../screenshots/no-elements-boom.png
+ :alt: [Fatal error: Uncaught exception 'PieformException' with message 'Forms must have a list of elements']
So now the form has a name, and will be sent by POST when submitted. But it has no elements! There's not too much point in having a form that does not have an element, so lets add the title field and submit/cancel buttons.
@@ -86,24 +97,26 @@
'elements' => array(
'title' => array(
'type' => 'text',
- 'title' => 'Post Title'
+ 'title' => 'Post Title',
),
'submit' => array(
'type' => 'submitcancel',
- 'value' => array('Enter New Post', 'Cancel')
- )
- )
+ 'value' => array('Enter New Post', 'Cancel'),
+ ),
+ ),
));
?>
-[insert screenshot of yay]
+.. image:: ../../screenshots/usage-form-1.png
+ :alt: [Form with text box and submit/cancel buttons]
Now we have some concrete progress, at last! We now have a single text box, with a submit and cancel button under it. Compare how much effort it took to add these elements with how you would normally make forms. I hope you are already seeing how quick this is!
Now let's try submitting the form:
-[insert screenshot of boom]
+.. image:: ../../screenshots/no-submithandler-boom.png
+ :alt: [Fatal error: Uncaught exception 'PieformException' with message 'No function registered to handle form submission for form "test"']
We have not specified the function that gets run when the form is submitted. This function has the name ``[formname]_submit``, and once it is done it should somehow redirect the user to another page (or redirect back to the same page if you wish, but it must be a redirect so that the form state is cleared), or exit the script. For now we will just show a success page:
@@ -119,13 +132,13 @@
'elements' => array(
'title' => array(
'type' => 'text',
- 'title' => 'Post Title'
+ 'title' => 'Post Title',
),
'submit' => array(
'type' => 'submitcancel',
- 'value' => array('Enter New Post', 'Cancel')
- )
- )
+ 'value' => array('Enter New Post', 'Cancel'),
+ ),
+ ),
));
function blogpost_submit(Pieform $form, $values) {
@@ -139,13 +152,15 @@
Please pardon my terrible HTML, this is only an example :). Now, when you submit the form:
-[screenshot of success]
+.. image:: ../../screenshots/usage-form-submitted.png
+ :alt: [Congratulations! New post entered. Back to enter another one...]
That's much better. Of course, the submit function should have inserted the blog post into the database before displaying this message, but I'll leave that detail as an exercise for the reader.
But what about the cancel button?
-[screenshot of cancel boom]
+.. image:: ../../screenshots/no-cancelhandler-boom.png
+ :alt: [Fatal error: Uncaught exception 'PieformException' with message 'Cancel element "submit" has no page to go to']
Not so great, luckily Pieforms tells you what you need to do to fix that. While we're at it, let's add the textarea for the post content:
@@ -161,18 +176,20 @@
'elements' => array(
'title' => array(
'type' => 'text',
- 'title' => 'Post Title'
+ 'title' => 'Post Title',
),
'content' => array(
- 'type' => 'textarea',
- 'title' => 'Content'
+ 'type' => 'textarea',
+ 'title' => 'Content',
+ 'rows' => 10,
+ 'cols' => 80,
),
'submit' => array(
'type' => 'submitcancel',
- 'value' => array('Enter New Post', 'Cancel')
- 'goto' => $_SERVER['SCRIPT_NAME']
- )
- )
+ 'value' => array('Enter New Post', 'Cancel'),
+ 'goto' => $_SERVER['SCRIPT_NAME'],
+ ),
+ ),
));
function blogpost_submit(Pieform $form, $values) {
@@ -184,7 +201,8 @@
?>
-[insert screenshot of form]
+.. image:: ../../screenshots/usage-form-2.png
+ :alt: [Form with text box, text area and submit/cancel buttons]
You will get the result above both when you view and cancel the form. Of course, your cancel button could redirect elsewhere, or put a message in the session that is displayed on the next page, using the cancel function ``[formname]_cancel_submit`` rather than ``'goto'`` on the element.
@@ -202,16 +220,18 @@
'elements' => array(
'title' => array(
'type' => 'text',
- 'title' => 'Post Title'
+ 'title' => 'Post Title',
),
'content' => array(
- 'type' => 'textarea',
- 'title' => 'Content'
+ 'type' => 'textarea',
+ 'title' => 'Content',
+ 'rows' => 10,
+ 'cols' => 80,
),
'optional' => array(
'type' => 'fieldset',
- 'title' => 'Advanced Options...',
- 'collapsable' => true,
+ 'legend' => 'Advanced Options...',
+ 'collapsible' => true,
'collapsed' => true,
'elements' => array(
'categories' => array(
@@ -219,26 +239,26 @@
'title' => 'Categories',
'multiple' => true,
'size' => 5,
- 'values' => array(
+ 'options' => array(
1 => 'Personal',
2 => 'Rants',
3 => 'Politics',
4 => 'Religion',
5 => 'Science',
- 6 => 'Arts'
- )
+ 6 => 'Arts',
+ ),
),
'publishdate' => array(
'type' => 'date',
- 'title' => 'Publish Date'
- )
- )
+ 'title' => 'Publish Date',
+ ),
+ ),
),
'submit' => array(
'type' => 'submitcancel',
- 'value' => array('Enter New Post', 'Cancel')
- 'goto' => $_SERVER['SCRIPT_NAME']
- )
+ 'value' => array('Enter New Post', 'Cancel'),
+ 'goto' => $_SERVER['SCRIPT_NAME'],
+ ),
)
));
@@ -251,12 +271,39 @@
?>
-[insert screenshot]
+.. image:: ../../screenshots/usage-form-3.png
+ :alt: [Form with text box, text area, collapsed fieldset and submit/cancel buttons]
+To make sure that the collapsing works for you, you have to include the
+MochiKit library in the page that has the form. Otherwise, you will simply get
+a page where the legend is not visible in the fieldset.
+
+In addition, collapsing works by toggling a class on the fieldset. When you
+click on the legend, the class 'collapsed' will be toggled. You can verify this
+in firebug or a similar DOM inspection tool, and write your own CSS rules to
+make the collapsing work as you expect. Something like this will start you off:
+
+.. highlight:: css/css
+
+ .collapsed * {
+ display: none;
+ }
+ .collapsed legend, .collapsed legend a {
+ display: block;
+ }
+
+
Adding a Touch of Class
-----------------------
-Now the whole form is layed out, including the collapsable fieldset. Cool! But we are not finished yet. The form has no rules attached to it (other than a hidden rule on the multiselect box to automatically check that the submitted value is in the array of values), and could be improved with a bit of javascript love. On the rule side, let's make the title and content of the post required and the publish date be later than the current time. For javascript improvement, we can make the textarea resizable and auto focus the title element on page load.
+Now the whole form is layed out, including the collapsible fieldset. Cool! But
+we are not finished yet. The form has no rules attached to it (other than a
+hidden rule on the multiselect box to automatically check that the submitted
+value is in the array of values), and could be improved with a bit of
+javascript love. On the rule side, let's make the title and content of the post
+required and the publish date be later than the current time. For javascript
+improvement, we can make the textarea resizable and auto focus the title
+element on page load.
.. highlight:: php/php5
@@ -272,18 +319,22 @@
'title' => array(
'type' => 'text',
'title' => 'Post Title',
- 'rules' => array('required' => true)
+ 'rules' => array(
+ 'required' => true,
+ ),
),
'content' => array(
'type' => 'textarea',
'title' => 'Content',
- 'rules' => array('required' => true),
- 'resizable' => true
+ 'rules' => array(
+ 'required' => true,
+ ),
+ 'resizable' => true,
),
'optional' => array(
'type' => 'fieldset',
- 'title' => 'Advanced Options...',
- 'collapsable' => true,
+ 'legend' => 'Advanced Options...',
+ 'collapsible' => true,
'collapsed' => true,
'elements' => array(
'categories' => array(
@@ -291,26 +342,26 @@
'title' => 'Categories',
'multiple' => true,
'size' => 5,
- 'values' => array(
+ 'options' => array(
1 => 'Personal',
2 => 'Rants',
3 => 'Politics',
4 => 'Religion',
5 => 'Science',
- 6 => 'Arts'
- )
+ 6 => 'Arts',
+ ),
),
'publishdate' => array(
'type' => 'date',
- 'title' => 'Publish Date'
- )
- )
+ 'title' => 'Publish Date',
+ ),
+ ),
),
'submit' => array(
'type' => 'submitcancel',
- 'value' => array('Enter New Post', 'Cancel')
- 'goto' => $_SERVER['SCRIPT_NAME']
- )
+ 'value' => array('Enter New Post', 'Cancel'),
+ 'goto' => $_SERVER['SCRIPT_NAME'],
+ ),
)
));
@@ -329,17 +380,53 @@
?>
-Not too much added, and pretty much everything we wanted is implemented. The title and content are now required - try submitting the form without them set. There's no easy rule for checking that a value is greater than another just yet, so we added a 'validate' function which sets an error on the form if the publish date is not in the future. It took one line to make the textarea resizable, and just one more to make the title element focus on page load. Note that we specified 'autofocus' to be **true** - this means that the first element in the form will be focussed on page load. You can specify an element by name if you want that particular element to be focussed on page load.
+Not too much added, and pretty much everything we wanted is implemented. The
+title and content are now required - try submitting the form without them set.
+There's no easy rule for checking that a value is greater than another just
+yet, so we added a 'validate' function which sets an error on the form if the
+publish date is not in the future. It took one line to make the textarea
+resizable, and just one more to make the title element focus on page load. Note
+that we specified 'autofocus' to be **true** - this means that the first
+element in the form will be focussed on page load. You can specify an element
+by name if you want that particular element to be focussed on page load.
The Finishing Touches
---------------------
Programatically, the form is done (except for any actualy logic to save the data somewhere). Now all you need it a bit of CSS magic, and you're done!
-[insert CSS code here]
+.. highlight:: css/css
-[insert screenshot here]
+ fieldset {
+ border: 1px solid #888;
+ font-family: Arial, sans-serif;
+ }
+ .collapsed {
+ border-color: transparent;
+ border-top: 1px solid #888;
+ }
+ .collapsed legend, .collapsed legend a {
+ display: block;
+ }
+ .collapsed * {
+ display: none;
+ }
+ .pieform th {
+ text-align: right;
+ font-family: Arial, sans-serif;
+ vertical-align: top;
+ padding: .25em .5em .25em 1em;
+ }
+ .pieform input, .pieform textarea, .pieform select {
+ border: 1px solid #888;
+ }
+ .pieform input[type="submit"] {
+ border: 2px outset #ccc;
+ }
+.. image:: ../../screenshots/usage-form-4.png
+ :alt: [The form, styled with CSS]
+
From zero to form in very short order - when you get good at writing forms and Pieforms is already integrated into your software, the above form will be very quick indeed to create.
Now let's move on to another form, this time one that will have a bit more of an 'AJAX feel'.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
