Section: Using a form after a submit
| « Displaying a form in a template | ^ jForms: automatic forms | display only form values » |
− Table of content
Once a form has been created, displayed and then filled by the user, it is submitted to an action.
This action should retrieve form data, check their values and process them (saving for example).
Fill your form ¶
Remember that jForms::fill() method return your form object and fill it with user input data:
$form = jForms::fill("main~contact");
Which is the same as:
$form = jForms::get("main~contact");
$form->initFromRequest();
You can again use setData to overload user inputs or fill some empty controls for example.
$form = jForms::get("main~contact");
$form->setData('name', $this->param('name'));
Check data ¶
Once you have a form object filled with submitted data, you should check precisely if this is what you expect before going on processing. check() method does basic checkings based on what you described in your XML file (if a field is required, if field data type is correct, etc...). check() returns true if all checkings pass, false otherwise.
If data validation fails, you'll generally display your form again with error messages. if you do so, check() will have automatically displayed error messages on your form and your user will have to correct them.
$form = jForms::fill("main~contact");
if (!$form->check()) {
// invalid: redirect to "show" action
$rep = $this->getResponse('redirect');
$rep->action='module~default:show';
return $rep;
}
You can, of course, implement more complex checkings on data. In order to access control data, call getData() method. In order to set an error on a particular field, use setErrorOn().
$form = jForms::fill("main~contact");
if (!$form->check()) {
// invalid : redirect to "show" action
$rep = $this->getResponse('redirect');
$rep->action='module~default:show';
return $rep;
}
$ok = true;
$valeur = $form->getData('nom');
if( strpos($value, 'qwerty') !== null) {
$ok = false;
$form->setErrorOn('name', 'you should spell your real name !');
}
// other checks
//....
if (!$ok) {
// invalid : redirect to "show" action
$rep = $this->getResponse('redirect');
$rep->action='module~default:show';
return $rep;
}
Get the list of modified values ¶
When a form has been initialized or reset, edited and then submitted, It can be useful to get the list of modified values.
This is a 2 step process :
- Before displaying your form to a user, call
initModifiedControlsList()method. Thus, you tell jForm you want to track modified records. If you don't need it, do not call it since all data values are cloned and stored in session, occupying memory. - Upon submit, call
getModifiedControls()method. It returns an arrays of modified controls. its keys are control names and its values are old control values.
// in your prepare action
$form = jForms::create("main~contact");
$form->initFromDao(...);
$form->initModifiedControlsList();
// in your submit action
$form = jForms::fill("main~contact");
if (!$form->check()) {
...
}
$list = $form->getModifiedControl();
Note : in Jelix 1.1 beta1, initModifiedControlsList() didn't exists. (there was resetModifiedControlsList() instead, but it is now deprecated). Moreover, getModifiedControls() was returning only modified values since last submit.
Storing data ¶
Once all checkings are ok, you can extract data of your form object through calls of getData() method or simply getAllData() call which retrieves all form data under a PHP array. And then, you could save them to database with jDao or jDb, send some parts by mail, and so on.
Storing through DAO ¶
Reflecting initFromDao which fills a form, saveToDao allows you to save user inputs via DAO. Values of fields whose name equals dao properties are affected to said dao, on a record. Record key is your form id. If you haven't set a form id, a new record willbe created instead of updating an existing record.
$form->saveToDao('shop~products');
If your primary key is not an auto-increment, and it is a new record, you should transmit its value as second argument of saveToDao(). It also accepts an optional jDb profile argument.
Note that saveToDao() method returns primary key of the processed record.
$primaryKey = $form->saveToDao('shop~products');
saveToDao is really handy, but if you just want to fill a dao record with your form contents and then set/edit its properties and save it afteruse prepareDaoFromControls() method. It is an identical signature as saveToDao, ie. same arguments except that it returns an array containing a dao record (daorec), its dao factory (dao), and a boolean (toInsert) telling if the record already exists or not.
$result = $form->prepareDaoFromControls('shop~products');
$result['daorec']->other_field='bla';
if($result['toInsert'])
$result['dao']->insert($result['daorec']);
else
$result['dao']->update($result['daorec']);
Storing values of a multiple choices control ¶
As well as saveToDao(), saveControlToDao() does the opposite of initControlFromDao(). It then save selected values of checkboxes or multpile choices listbox in a join table.
$form->saveControlToDao('categories', 'shop~products_categories');
First arg is a field name and the second a dao selector which will be used for storage.
Storing files ¶
If your form has file upload controls, you'll have to store those files upon submit. jForms API has two methods dedicated: saveFile() and saveAllFiles(). The first one deals with one file and the latter deals with every file uploaded and save them in a same directory. Be aware that you'll find original filename in its control data (which you access calling getData). Use setData to modify this name if needed.
saveFile() take your control name as argument. Its default behaviour will store file in var/uploads/module_name~form_name/ folder. An optional second argument is supported to override saveFile() default behaviour and store your file in your folder of choice. And a third one, if you want to modify its filename.
Example :
$form->saveFile('photo');
$form->saveFile('photo', JELIX_APP_WWW_PATH.'images/photos/');
$form->saveFile('photo', JELIX_APP_WWW_PATH.'images/photos/', $id.'.png');
$form->saveFile('photo', '', $id.'.png');
saveAllFiles copy all uploaded files to a directory. The default one is var/uploads/module_name~form_name/, but you can override it by providing a second argument:
$form->saveAllFiles();
$form->saveAllFiles(JELIX_APP_WWW_PATH.'images/photos/');
Destroy a form object ¶
When a form object is no more used (inputs done, submitted, data checked and treated/stored), you are advised to destroy your form object to lighten session data. Use jForms::destroy and give it your form selector and your form id (if there is one).
jForms::destroy("main~contact");
jForms::destroy('shop~products');
jForms::destroy('shop~products', $product_id);
