Skip to content

Commit

Permalink
FIX: use GFMD code blocks to fix code formatting consistency.
Browse files Browse the repository at this point in the history
  • Loading branch information
@camfindlay
camfindlay committed Dec 14, 2014
1 parent 34c8121 commit e9fd03b
Showing 1 changed file with 68 additions and 60 deletions.
128 changes: 68 additions & 60 deletions docs/en/01_Tutorials/03_Forms.md
View file
Expand Up @@ -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');

Expand Down Expand Up @@ -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'),
Expand All @@ -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.
Expand All @@ -81,21 +81,21 @@ 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.
Here we create a 'Submit' button which calls the 'doBrowserPoll' method, which we will create later.
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
Expand All @@ -107,58 +107,66 @@ 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>
$BrowserPollForm
</div>
<div class="Content">
...
```
In order to make the graphs render correctly,
we need to add some CSS styling.
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:
Expand All @@ -175,20 +183,20 @@ 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(
'Name' => 'Text',
'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) {
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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 {
// ...
Expand All @@ -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 {
// ...
Expand All @@ -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.
Expand All @@ -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();
Expand All @@ -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);
Expand All @@ -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.
Expand All @@ -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 %>
Expand All @@ -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.
Expand Down

0 comments on commit e9fd03b

Please sign in to comment.