Advanced Form Processing

Advanced Form Processing

Basically, when you call processForm(), you are calling two functions that automatically process your form. Sometimes you want to do more than just insert the data into the db. That's where our advanced form processing comes into play.

Please NoteAs of UserSpice 5, the form builder is a plugin and not built in by default. Please get it through Spice Shaker
See also: Form Builder Basics

PLEASE NOTE: The best place to put this is at the top of your page, just below the includes for the init.php and header. Do not put it below your form or the token security will fail every time.

A typical advanced setup looks more like this.

if(!empty($_POST)){
$response = preProcessForm();
if($response['form_valid'] == true){
//do something here after the form has been validated
postProcessForm($response);
}
}

So, why would you want to do this? A lot of times you'll want to do something like put the user's id into the db along with the other data. It's a REALLY bad idea to do this through things like hidden form fields. With tools like Chrome's Inspector, it would be super easy for someone to change a hidden field that says their user id is 2 to 1, which would make it look like the site administrator submitted that data. So, how do we get around this? We enter that information AFTER the form has been submitted.

First, let's break down what preProcessForm does.
1. It does the check for the CSRF security token. If it's a bad token, the form submit will fail.
2. It sanitizes the data to protect against SQL injections.
3. It performs the validations you requested when you built the forms (like must be a number between 1 and 10).

You'll also notice that we called $response = preProcessForm();
The reason for this is that we care about what the preProcessForm function is sending back to us. You will get something along the lines of


array(4) {
["form_valid"]=>
bool(true)
["validation"]=>
bool(true)
["token"]=>
bool(true)
["fields"]=>
array(5) {
["fname"]=>
string(4) "Bob"
}
["name"]=>
string(7) "parents"
}


So, as you can see, that form:
1. Passed validation
2. Passed the token check
3. Contained one form field called fname and the user entered "Bob"
4. The form's name is "parents"
5. The entire submission is valid (form_valid = true)

From there, you can do whatever you want. Let's say you want to stick the logged in user's id in there.
1. Edit your form.
2. Add a hidden field called user_id. This will create the column in the db and let the form processor know that you're looking for a user_id.
3. Just after the form preprocessor add the line
$response['fields']['user_id']=$user->data()->id;

What you've done there is added the user id server side, so no matter what the person did to hack that form the id that is going into the database is the user id who created the form.

Please note: This is also the same technique you use when you want to add additional custom fields to the form.  In between preProcessForm and postProcessForm you add those inputs to your insert variable using the same $response['fields']['user_id']=$user->data()->id;.  You will do this once per input.  Feel free to add other validations and conditions in there.

After you've done everything you want to do, you can call
$response = postProcessForm($response) to process the form. You can also dump that repsonse variable after post processing and it will show you if there were any database errors inserting or updating your form.

Also note that you don't have to call postProcessForm at all. You're free to do whatever you want with the data that was submitted.

Passing options to form functions

The main form functions have the ability to pass in an aray of options to greatly extend your capabilities. You can learn about these options below, but when you create your form, you need to pass them into the function. It looks something like this.


displayForm('myform',$options);


Submit Buttons

Customize the name, class, and text of your submit button with these options.

$options = array(
'submit'=>'submit', //If you want a custom submit button you must do 'submit'=>something. This doubles as the field name
'class'=>'btn btn-success',
'value'=>'This is the submit button',
);


Sometimes you might not want the form to be submittable.

$options = ['nosubmit'=>1];


Customizing your Form

What if you want to do something advanced that you can't pull off with our form editor? Add this code and it will not close the form tag, which means that you can add more form code in addition to what was generated by the form builder.

$options = ['noclose'=>1];


 

Debugging Forms

If you're having problems with getting your form to work properly, you can do

if(!empty($_POST)){dnd($_POST);} //simply see what was submitted
//or
processForm(['debug'=>1]);


Multiple Forms on One Page

By default, the UserSpice form editor automatically produces a token when the page is rendered and checks for that token on submit to make sure the page was not refreshed by a man in the middle attack. However, since one token is generated by each form, having multiple forms on the same page will break this. You can overcome this by generating the token outside the form and passing it to each from when you generate it.

$token = Token::generate();
$options = ['token'=>$token];


Updating Instead of Inserting

If you want to use a form to update a row of the database instead of updating it, there are a few things that you need to do first. There is a magic variable called $usFormUpdate. The form processor looks for this variable to be set and updates THAT row of the database. This prevents you from having to pass that id in through a "hidden" form field or something else that would be dangerous for security purposes. To use this…

$usFormUpdate = 10; //The row you want to update
$options['update'] = $usFormUpdate;

//then call your form with

displayform('formname',$options);

Note: At this time, if you have an update form on your page, you should not put another form on that page.

Displaying Tables

You can display a table of any form with the shortcode

displayTable('formName');

You can even add an options array such as

$opts['where'] = ['id','<',3];

and then call

displayTable('formName',$opts);

Other options include $opts['id']=1; to show the id column and $opts['class']="whatver"; to give any class other than "table table-striped".

Note that the ability to display tables of views is coming soon.

Validating Forms

In order to simplify the UI, form validation options are not created during form creation. In the form editor, you can click edit on any particular field and add validation options. Most, but not all of the options in the UserSpice validation class are thre. Some will be tweaked for better performance. Please note that there is nothing to stop you from putting in conflicting validation options. In other words you CAN require a number that is < 10 AND > 100 so pay attention.