Conventions used in this document:
- Any text that is in this font is considered code, a literal value, the name of a file, folder, MySQL table, MySQL field, or a value in a MySQL field.
- Any text that is surrounded by angle brackets like <this> means that you should substitute it for your own value.
Example: vconsole/modules/<module>/ means that you should substitute <module> for your own value like invoices for the Manage Invoices module.
- Any text that is surrounded by square brackets like [this] means that it is optional.
Example: check_email($email, $error[, $dnscheck]); means that [, $dnscheck] is optional
- When you see ... in the code font, this means that you can add 1 or more items at that point. Do not actually include ... in your code.
Collecting Data From the wizardmanager() Function.
To collect your data, you simply pass the $wm data structure to the wizardmanager() function and it returns a fully validated array of all the data that the user entered. This includes file uploads, input values, choice builder values, and everything else. To see what was returned, you can call the html_print_r() function on the data. For example:
In the example above, the
$data array contains all the data that the user input. Also, the input has already been validated by the
wizardmanager() function so there is no need to re-validate the data. You can rest assure that values in the
$data array are validated according to the
validation specs you provided in the
$wm array for each field.
The
$data array contains 1 element for each step in the Wizard
$wm array, and each of those elements contain a key for each field in that step.
For example: Let's say we have a
$wm array with 2 steps and various fields within those steps like so:
<?php
$wm = array(
array(),
array(
'fields' => array(
array(
'type' => 'text',
'name' => 'test1',
'label' => 'Test 1'
),
array(
'type' => 'calendar',
'name' => 'test2',
'label' => 'Calendar',
'pack' => 'nextrow'
)
)
),
array(
'fields' => array(
array(
'type' => 'text',
'name' => 'test1',
'label' => 'Test 1'
),
array(
'type' => 'calendar',
'name' => 'test2',
'label' => 'Calendar',
'pack' => 'nextrow'
)
)
)
);
$data = wizardmanager($wm);
?>
We can see by the example that $data contains all the input from our user. There are 2 steps and 2 fields in each step. It is perfectly acceptable to have two fields that have the same field_name as long as they are in different steps.
Getting data from choicebuilder fields.
Choicebuilder fields are fields that have multiple embedded fields within them. This gives the user to add / remove multiple choices - each choice with an entire set of embedded fields. OK, so let me give an example:
Let's say that you want to gvie the user the ability to add / remove events from a calendar. And each event should have a start date, and end date, and a description. The best way to handle this is to use a choicebuilder field. Simply embed a start date calendar field, an end date calendar field, and a regular text field for the description inside a choicebuilder field. Now, the user can add and remove events. Each time they click on Add Option, they get 3 fields - Start date, end date, and description.
Does this all seem complex? Well, it can be, but we try to make it as easy as possible to get the user's data, even with complex data structures like choicebuilder fields. The data for the embedded fields can be accessed via:
$data[<step>]['<field_name>_'.<choice>] where <step> is the wizard step number and <field_name> is the name of the embedded field and <choice> is the choice number.
And the number of choices that the user set can be accessed via:
$data[<step>]['<field_name>'] where <field_name> is the name of the choicebuilder field itself. (Remember, choicebuilder field_names and embedded field_names must be unique within the step)
If you don't understand, you can always issue html_print_r($data); to see what $data contains. Remember, all the user input can be found within the $data array, even information about uploaded files (See below). OK, let's give an example to clarify things.
<?php
$wm = array(
array(),
array(
'fields' => array(
array(
'type' =>
'choicebuilder',
'name' =>
'events',
'label' =>
'Events',
'fielddata' => array(
'minchoices' => 1,
'maxchoices' => 5,
'defchoices' => 1,
'fields' => array(
array(
'type' =>
'calendar',
'name' =>
'start',
'label' =>
'Start Date',
'labelpos' =>
'before',
),
array(
'type' =>
'calendar',
'name' =>
'end',
'label' =>
'End Date',
'labelpos' =>
'before',
),
array(
'type' =>
'text',
'name' =>
'description',
'label' =>
'Description',
'labelpos' =>
'before',
)
)
)
)
)
)
);
$data =
wizardmanager($wm);
if (is_array($data)) {
html_print_r($data);
for ($i=1;$i<=$data[1][
'events'];$i++) {
print
"Event $i:
Start: " . $data[1][
'start_'.$i] .
"
End: " . $data[1][
'end_'.$i] .
"
Description: " . $data[1][
'description_'.$i] .
"<br />\n";
}
}
Getting uploaded files.
It is very simple to get files that were uploaded with the wizardmanager. First, let me say that you can't get them using the normal PHP methods. Usually, you would get your files using the $_FILES array. This is not the case with VConsole. This is because PHP is not responsible for uploading files. Instead, files are uploaded using a Perl script (vconsole/functions/perl/upload.cgi). The reason that we use a Perl script is because PHP doesn't support file upload progress hooks. (At least not until PHP 5.2) So, instead of using PHP to upload files, we decided to make VConsole upload files using Perl, plus we get a nice progress bar of the upload this way. (We may decide to switch to a PHP version of file uploading in the future once more users have adopted PHP 5.2 or above) So, in order to get your files, you simply look in the $data[<step>]['<field_name>'] array. This array contains the same parameters as the $_FILES would have contained if you uploaded the file using PHP. Uploaded files are stored in the vconsole/tmp/ folder. Here is a list of the keys and values for the $data[<step>]['<field_name>'] array:
- $data[<step>]['<field_name>']['name'] - The original name of the file that was uploaded.
- $data[<step>]['<field_name>']['type'] - The mime type of the file, if the file is of a known mime type. An example would be "image/gif". This mime type is based on the file extension of the original file and not on the content of the file itself and is taken from the vc_mimetypes MySQL table. Do not take this value for granted.
- $data[<step>]['<field_name>']['size'] - The size in bytes of the uploaded file.
- $data[<step>]['<field_name>']['tmp_name'] - The temporary filename of the file in which the uploaded file was stored on the server. Uploaded files are stored in the vconsole/tmp/ folder. You should use this value to access, move, and rename the file to wherever and whatever you need it to be.
- $data[<step>]['<field_name>']['error'] - If the file could not be uploaded for some reason, this will contain the error. (Remember that PERL is responsible for uploading files, so if there was a problem, it will be generated by the functions/perl/upload.cgi file.
