tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-01 21:58:51 +02:00
Code Issues Projects Releases Wiki Activity

FIX: use GFMD code blocks to fix code formatting consistency.

Browse Source
This commit is contained in:
Cam Findlay 2014-12-09 09:02:32 +13:00
parent 6d0cd49d6d
commit aba966729a
1 changed files with 68 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
docs/en/01_Tutorials/03_Forms.md
View File

@ -22,7 +22,7 @@ The poll we will be creating on our homepage will ask the user for their name an
**mysite/code/HomePage.php**
:::php
```php
class HomePage_Controller extends Page_Controller {
private static $allowed_actions = array('BrowserPollForm');
@ -54,11 +54,11 @@ The poll we will be creating on our homepage will ask the user for their name an
}
...
```
Let's step through this code.
:::php
```php
// Create fields
$fields = new FieldList(
new TextField('Name'),
@ -71,7 +71,7 @@ Let's step through this code.
'Lynx' => 'Lynx'
))
);
```
First we create our form fields.
We do this by creating a `[api:FieldList]` and passing our fields as arguments.
@ -81,11 +81,11 @@ argument is passed, as in this case, it is assumed the label is the same as the
The second field we create is an `[api:OptionsetField]`. This is a dropdown, and takes a third argument - an
array mapping the values to the options listed in the dropdown.
:::php
```php
$actions = new FieldList(
new FormAction('doBrowserPoll', 'Submit');
);
```
After creating the fields, we create the form actions. Form actions appear as buttons at the bottom of the form.
The first argument is the name of the function to call when the button is pressed, and the second is the label of the button.
@ -93,9 +93,9 @@ Here we create a 'Submit' button which calls the 'doBrowserPoll' method, which w
All the form actions (in this case only one) are collected into a `[api:FieldList]` object the same way we did with
the fields.
:::php
```php
return new Form($this, 'BrowserPollForm', $fields, $actions);
```
Finally we create the `[api:Form]` object and return it.
The first argument is the controller that contains the form, in most cases '$this'. The second is the name of the method
@ -107,7 +107,7 @@ Add the following code to the top of your home page template, just before `<div
**themes/simple/templates/Layout/HomePage.ss**
:::ss
```ss
...
<div id="BrowserPoll">
<h2>Browser Poll</h2>
@ -115,6 +115,7 @@ Add the following code to the top of your home page template, just before `<div
</div>
<div class="Content">
...
```
In order to make the graphs render correctly,
we need to add some CSS styling.
@ -122,43 +123,50 @@ Add the following code to the existing `form.css` file:
**themes/simple/css/form.css**
:::css
```css
/* BROWSER POLL */
#BrowserPoll {
float: right;
margin: 20px 10px 0 0;
width: 20%;
}
form FieldList {
border:0;
}
#BrowserPoll .message {
float:left;
display: block;
color:red;
background:#efefef;
border:1px solid #ccc;
padding:5px;
margin:5px;
}
#BrowserPoll h2 {
font-size: 1.5em;
line-height:2em;
color: #0083C8;
}
#BrowserPoll .field {
padding:3px 0;
}
#BrowserPoll input.text {
padding: 0;
font-size:1em;
}
#BrowserPoll .Actions {
padding:5px 0;
}
#BrowserPoll .bar {
background-color: #015581;
}
form FieldList {
border:0;
}
#BrowserPoll .message {
float:left;
display: block;
color:red;
background:#efefef;
border:1px solid #ccc;
padding:5px;
margin:5px;
}
#BrowserPoll h2 {
font-size: 1.5em;
line-height:2em;
color: #0083C8;
}
#BrowserPoll .field {
padding:3px 0;
}
#BrowserPoll input.text {
padding: 0;
font-size:1em;
}
#BrowserPoll .Actions {
padding:5px 0;
}
#BrowserPoll .bar {
background-color: #015581;
}
```
All going according to plan, if you visit [http://localhost/your_site_name/home/?flush=1](http://localhost/your_site_name/home/?flush=1) it should look something like this:
@ -175,7 +183,7 @@ If you recall, in the [second tutorial](/tutorials/extending_a_basic_site) we sa
**mysite/code/BrowserPollSubmission.php**
:::php
```php
<?php
class BrowserPollSubmission extends DataObject {
private static $db = array(
@ -183,12 +191,12 @@ If you recall, in the [second tutorial](/tutorials/extending_a_basic_site) we sa
'Browser' => 'Text'
);
}
```
If we then rebuild the database ([http://localhost/your_site_name/dev/build](http://localhost/your_site_name/dev/build)), we will see that the *BrowserPollSubmission* table is created. Now we just need to define 'doBrowserPoll' on *HomePage_Controller*:
**mysite/code/HomePage.php**
:::php
```php
class HomePage_Controller extends Page_Controller {
// ...
public function doBrowserPoll($data, $form) {
@ -198,7 +206,7 @@ If we then rebuild the database ([http://localhost/your_site_name/dev/build](htt
return $this->redirectBack();
}
}
```
A function that processes a form submission takes two arguments - the first is the data in the form, the second is the `[api:Form]` object.
In our function we create a new *BrowserPollSubmission* object. Since the name of our form fields, and the name of the database fields, are the same we can save the form directly into the data object.
@ -214,13 +222,13 @@ Change the end of the 'BrowserPollForm' function so it looks like this:
**mysite/code/HomePage.php**
:::php
```php
public function BrowserPollForm() {
// ...
$validator = new RequiredFields('Name', 'Browser');
return new Form($this, 'BrowserPollForm', $fields, $actions, $validator);
}
```
If we then open the homepage and attempt to submit the form without filling in the required fields errors should appear.
@ -236,7 +244,7 @@ We can do this using a session variable. The `[api:Session]` class handles all s
**mysite/code/HomePage.php**
:::php
```php
// ...
class HomePage_Controller extends Page_Controller {
// ...
@ -248,12 +256,12 @@ We can do this using a session variable. The `[api:Session]` class handles all s
return $this->redirectBack();
}
}
```
Then we simply need to check if the session variable has been set in 'BrowserPollForm()', and to not return the form if
it is.
:::php
```php
// ...
class HomePage_Controller extends Page_Controller {
// ...
@ -262,7 +270,7 @@ it is.
// ...
}
}
```
If you visit the home page now you will see you can only vote once per session; after that the form won't be shown. You can start a new session by closing and reopening your browser,
or clearing your browsing session through your browsers preferences.
@ -277,7 +285,7 @@ Create the function 'BrowserPollResults' on the *HomePage_Controller* class.
**mysite/code/HomePage.php**
:::php
```php
public function BrowserPollResults() {
$submissions = new GroupedList(BrowserPollSubmission::get());
$total = $submissions->Count();
@ -292,20 +300,20 @@ Create the function 'BrowserPollResults' on the *HomePage_Controller* class.
}
return $list;
}
```
This code introduces a few new concepts, so let's step through it.
:::php
```php
$submissions = new GroupedList(BrowserPollSubmission::get());
```
First we get all of the `BrowserPollSubmission` records from the database. This returns the submissions as a `[api:DataList]`.Then we wrap it inside a `[api:GroupedList]`, which adds the ability to group those records. The resulting object will behave just like the original `DataList`, though (with the addition of a `groupBy()` method).
:::php
```php
$total = $submissions->Count();
```
We get the total number of submissions, which is needed to calculate the percentages.
:::php
```php
$list = new ArrayList();
foreach($submissions->groupBy('Browser') as $browserName => $browserSubmissions) {
$percentage = (int) ($browserSubmissions->Count() / $total * 100);
@ -314,7 +322,7 @@ We get the total number of submissions, which is needed to calculate the percent
'Percentage' => $percentage
)));
}
```
Now we create an empty `[api:ArrayList]` to hold the data we'll pass to the template. Its similar to `[api:DataList]`, but can hold arbitrary objects rather than just DataObject` instances. Then we iterate over the 'Browser' submissions field.
@ -325,7 +333,7 @@ The final step is to create the template to display our data. Change the 'Browse
**themes/simple/templates/Layout/HomePage.ss**
:::ss
```ss
<div id="BrowserPoll">
<h2>Browser Poll</h2>
<% if $BrowserPollForm %>
@ -341,7 +349,7 @@ The final step is to create the template to display our data. Change the 'Browse
</ul>
<% end_if %>
</div>
```
Here we first check if the *BrowserPollForm* is returned, and if it is display it. Otherwise the user has already voted,
and the poll results need to be displayed.