tonyair/silverstripe-multiform
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-multiform synced 2024-10-22 11:05:49 +02:00
Code Issues Projects Releases Wiki Activity

Documentation updates for multiform.

Browse Source 
BCSMultiForm isn't a very good example for a form name, also fixing some
issues where the $start_step is set to a non-existent class.
This commit is contained in:
Sean Harvey 2014-06-17 15:53:22 +12:00
parent bd2e9ce857
commit 9cb22a62d1
1 changed files with 43 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
README.md
View File

@ -83,24 +83,14 @@ currently located)
### 2. Create subclass of MultiForm ### 2. Create subclass of MultiForm
First of all, we need to create a new subclass of *MultiForm*, which can be First of all, we need to create a new subclass of *MultiForm*.
called anything.
A suggestion for a good name, is an abbreviation of the project this multi-form For the above example, our multi-form will be called *SurveyForm*
is for, with "MultiForm" appended to the end. For example, if I was doing a
site called "Bob's Chicken Shack" then a good name would be *BCSMultiForm*.
This makes sense, as it is specific to the project that you're developing a
multi-form for.
Keep in mind the PHP file you create must be in the `mysite/code` directory, and
the filename must be the same as the class name, with the `.php` extension.
For the above example, our multi-form will be called *BCSMultiForm.php*
:::php :::php
<?php <?php
class BCSMultiForm extends MultiForm { class SurveyForm extends MultiForm {
} }
@ -120,21 +110,21 @@ personal details of the form user, then we might have this class:
:::php :::php
<?php <?php
class BCSPersonalDetailsFormStep extends MultiFormStep { class SurveyFormPersonalDetailsStep extends MultiFormStep {
} }
Now that we've got our first step of the form defined, we need to go back to our Now that we've got our first step of the form defined, we need to go back to our
subclass of MultiForm, BCSMultiForm, and tell it that BCSPersonalDetailsFormStep subclass of MultiForm, SurveyForm, and tell it that SurveyFormPersonalDetailsStep
is the first step. is the first step.
:::php :::php
<?php <?php
class BCSMultiForm extends MultiForm { class SurveyForm extends MultiForm {
public static $start_step = 'BCSPersonalDetailsFormStep'; public static $start_step = 'SurveyFormPersonalDetailsStep';
} }
@ -148,16 +138,16 @@ To get more than one step, each step needs to know what it's next step is in
order to use flow control in our system. order to use flow control in our system.
To let the step know what step is next in the process, we do the same as setting To let the step know what step is next in the process, we do the same as setting
the `$start_step` variable *BCSMultiForm*, but we call it `$next_steps`. the `$start_step` variable *SurveyForm*, but we call it `$next_steps`.
:::php :::php
<?php <?php
class BCSPersonalDetailsFormStep extends MultiFormStep { class SurveyFormPersonalDetailsStep extends MultiFormStep {
public static $next_steps = 'BCSOrganisationDetailsFormStep'; public static $next_steps = 'SurveyFormOrganisationDetailsStep';
function getFields() { public function getFields() {
return new FieldList( return new FieldList(
new TextField('FirstName', 'First name'), new TextField('FirstName', 'First name'),
new TextField('Surname', 'Surname') new TextField('Surname', 'Surname')
@ -176,12 +166,12 @@ final, and needs to have another variable set to let the multi-form system know
this is the final step. this is the final step.
So, if we assume that the last step in our process is So, if we assume that the last step in our process is
BCSOrganisationDetailsFormStep, then we can do something like this: SurveyFormOrganisationDetailsStep, then we can do something like this:
:::php :::php
<?php <?php
class BCSOrganisationDetailsFormStep extends MultiFormStep { class SurveyFormOrganisationDetailsStep extends MultiFormStep {
public static $is_final_step = true; public static $is_final_step = true;
@ -200,8 +190,8 @@ may receive errors.*
However, we've forgotten one thing. We need to create a method on a page-type so However, we've forgotten one thing. We need to create a method on a page-type so
that the form can be rendered into a given template. that the form can be rendered into a given template.
So, if we want to render our multi-form as `$BCSMultiForm` in the *Page.ss* So, if we want to render our multi-form as `$SurveyForm` in the *Page.ss*
template, we need to create a BCSMultiForm method (function) on the controller: template, we need to create a SurveyForm method (function) on the controller:
:::php :::php
<?php <?php
@ -218,12 +208,12 @@ template, we need to create a BCSMultiForm method (function) on the controller:
// //
private static $allowed_actions = array( private static $allowed_actions = array(
'BCSMultiForm', 'SurveyForm',
'finished' 'finished'
); );
public function BCSMultiForm() { public function SurveyForm() {
return new BCSMultiForm($this, 'Form'); return new SurveyForm($this, 'Form');
} }
public function finished() { public function finished() {
@ -238,27 +228,27 @@ template, we need to create a BCSMultiForm method (function) on the controller:
} }
The `BCSMultiForm()` function will create a new instance our subclass of The `SurveyForm()` function will create a new instance our subclass of
MultiForm, which in this example, is *BCSMultiForm*. This in turn will then set MultiForm, which in this example, is *SurveyForm*. This in turn will then set
up all the form fields, actions, and validation available to each step, as well up all the form fields, actions, and validation available to each step, as well
as the session. as the session.
You can of course, put the *BCSMultiForm* method on any controller class you You can of course, put the *SurveyForm* method on any controller class you
like. like.
Your template should look something like this, to render the form in: Your template should look something like this, to render the form in:
:::html :::html
<div id="content"> <div id="content">
<% if Content %> <% if $Content %>
$Content $Content
<% end_if %> <% end_if %>
<% if BCSMultiForm %> <% if $SurveyForm %>
$BCSMultiForm $SurveyForm
<% end_if %> <% end_if %>
<% if Form %> <% if $Form %>
$Form $Form
<% end_if %> <% end_if %>
</div> </div>
@ -288,31 +278,31 @@ To include these with our instance of multiform, we just need to add an
For example: For example:
:::html :::html
<% with BCSMultiForm %> <% with $SurveyForm %>
<% include MultiFormProgressList %> <% include MultiFormProgressList %>
<% end_with %> <% end_with %>
This means the included template is rendered within the scope of the This means the included template is rendered within the scope of the
BCSMultiForm instance returned, instead of the top level controller context. SurveyForm instance returned, instead of the top level controller context.
This gives us the data to show the progression of the steps. This gives us the data to show the progression of the steps.
Putting it together, we might have something looking like this: Putting it together, we might have something looking like this:
:::html :::html
<div id="content"> <div id="content">
<% if Content %> <% if $Content %>
$Content $Content
<% end_if %> <% end_if %>
<% if BCSMultiForm %> <% if $SurveyForm %>
<% with BCSMultiForm %> <% with $SurveyForm %>
<% include MultiFormProgressList %> <% include MultiFormProgressList %>
<% end_with %> <% end_with %>
$BCSMultiForm $SurveyForm
<% end_if %> <% end_if %>
<% if Form %> <% if $Form %>
$Form $Form
<% end_if %> <% end_if %>
</div> </div>
@ -334,7 +324,7 @@ The default progress indicators make use of the above functions in the
templates. templates.
To use a custom method of your own, simply create a new method on your subclass To use a custom method of your own, simply create a new method on your subclass
of MultiForm. In this example, *BCSMultiForm* would be the one to customise. of MultiForm. In this example, *SurveyForm* would be the one to customise.
This new method you create would then become available in the progress indicator This new method you create would then become available in the progress indicator
template. template.
@ -356,9 +346,9 @@ Here is an example of what we could do here:
:::php :::php
<?php <?php
class BCSMultiForm extends MultiForm { class SurveyForm extends MultiForm {
public static $start_step = 'BCSPersonalDetailsForm'; public static $start_step = 'SurveyFormPersonalDetailsStep';
public function finish($data, $form) { public function finish($data, $form) {
parent::finish($data, $form); parent::finish($data, $form);
@ -370,7 +360,7 @@ Here is an example of what we could do here:
if($steps) { if($steps) {
foreach($steps as $step) { foreach($steps as $step) {
if($step->class == 'BCSPersonalDetailsFormStep') { if($step->class == 'SurveyFormPersonalDetailsStep') {
$member = new Member(); $member = new Member();
$data = $step->loadData(); $data = $step->loadData();
@ -380,7 +370,7 @@ Here is an example of what we could do here:
} }
} }
if($step->class == 'BCSOrganisationDetailsFormStep') { if($step->class == 'SurveyOrganisationDetailsStep') {
$organisation = new Organisation(); $organisation = new Organisation();
$data = $step->loadData(); $data = $step->loadData();
@ -399,20 +389,19 @@ Here is an example of what we could do here:
} }
} }
$controller = $this->getController(); $this->controller->redirect($controller->Link() . 'finished');
$controller->redirect($controller->Link() . 'finished');
} }
} }
#### Organization #### 8. Organisation data model
The class Organisation is mentioned in the above example but doesn't exist at The class Organisation is mentioned in the above example but doesn't exist at
the moment (unlike the existing Member() class which looks after the member the moment (unlike the existing Member() class which looks after the member
groups in SilverStripe) so we need to create it: groups in SilverStripe) so we need to create it:
(I have chosen in this example to create Organisation as a separate DataObject This example has been chosen as a separate DataObject but you may wish to change
but you may wish to change the code and add the data to the Member class). the code and add the data to the Member class instead.
:::php :::php
<?php <?php
@ -541,9 +530,9 @@ For example:
:::php :::php
<?php <?php
class BCSMultiForm extends MultiForm { class SurveyForm extends MultiForm {
public static $start_step = 'BCSPersonalDetailsForm'; public static $start_step = 'SurveyFormPersonalDetailsStep';
public function finish($data, $form) { public function finish($data, $form) {
parent::finish($data, $form); parent::finish($data, $form);