PHP form plugin

Introduction(top)

Sometimes you are going to need to run some specific code that is not provided for by one of the other form submission plug-ins. At this point the highly flexible Run PHP plug-in is a godsend.

Options(top)

• Process scripts - State where in the form submission process you would like the script to be executed.
• PHP File- Select the PHP file you would like to run. In Fabrik version 2 these files are located in /components/com_fabrik/plugins/forms/fabrik/php/scripts.
  • In Fabrik 3 these files are located in /plugins/fabrik_form/php/scripts/ .
  • In Fabrik 2, It is location in components/com_fabrik/plugins/form/fabrikphp
• The Joomla framework is available to these scripts, so for example you can access the Joomla database with :
  
  PHP:

  $db = JFactory::getDBO();
• PHP code to execute on from submission - If no script is selected then the code entered here will be run instead.

Any script you want to use should be located in the 'scripts' sub folder of this directory.
For best security practices you should always add this to the top of your custom php scripts:
this stops the script from being executed outside of Joomla/Fabrik.

Plugin Locations (top)

The plug-in allows you to run your PHP at various locations/times within a fabrik form:

Locations :

• getTopContent - will insert anything that has been return'ed from your PHP script into the top of the form
• getBottomContent - will insert anything that has been return'ed from your PHP script into the bottom of the form

In these cases it is the string value returned by the script which is inserted into the page. Use a return statement in your script (eg return 'Hello world'rather than echo statements.

Times :



The main "times" (or "hooks") that the PHP plugin can be set to run on are:

• onLoad - runs when the form has been loaded, after its data has been created and assigned
• onError - When the form is submitted it is first validated, if a validation error occurs then this hook is triggered allowing you to for example, alter the $model->_arErrors error array or log which validation errors were set.
• onBeforeProcess - occurs at the start of a form submission, before the posted data has been assigned to the form model, but after the form has been validated
• onBeforeStore - occurs after onBeforeProcess and occurs after any fileuploads have been dealt with
• onAfterProcess - occurs after onBeforeStore once the form has submitted its data to the database table

There are other hooks, which are documented in the tooltip for this setting.

Validation :If any of the scripts running during the form submission return false, then the form submission is halted.

Refresh display (top)

If using onBeforeLoad(), and your script modifies the database used by your form, or your form fields, you should wish that your display reflects your modifications. In that case, Fabrik should be forced to re-read data from the database when call getData(), just after the onBeforeLoad() hook runs.
For this use :

Examples(top)

Accessing Form Data (top)

Usually, the best way to get an element's data is with the $formModel->getElementData() method, which takes the full element name, and three optional arguments:

The getElementData() method should work on any hook for the PHP form plugin, with the exception of onBeforeLoad (as there is no element data to get at that point). It should also work anywhere $formModel is availabe, not just in the PHP form plugin, as long as it is running at a point where form data has actually been loaded.
Examples:
Sometimes using getElementData() won't quite do what you need, or you simply want to access the data structure(s) yourself. The element data is easy to get at, the trick is simply knowing where it will be, depending on what phase of loading / processing you are running your code in.

The form's data is stored as an array and can be accessed with
The way Fabrik handles repeat data changed between 3.0 and 3.2/1. In 3.0, repeat group data was stored in a 'join' array in formData, keyed by the groups ID. So $formModel->_formData['join'][123]['repeat_table___foo'] would be an array containing each repeated value. In 3.1/2, this got simplified, with the ['join'] array being remoed, so $formModel->formData['repeat_table___foo'] is the array of repeated values.


To quickly see the structure of your form's data set this as your code:
In Fabrik 3.0 or less:
Joined elements (e.g. muliselect database joins, file uploads with multiple files being uploaded) and elements in joined groups. have their data nested in the array, so fore example to access the element 'countries___regions' in join id 6 you would do :
In Fabrik 3.1 joined data is accessed in the same way as the main list's fields, e.g.
N.B : In the php code field your PHP code can make use of {placeholders} (not possible in php-script-files).

Accessing form's original data(top)

only tested with Fabrik3.4.3 and onBeforeStore (check with var_dump($formModel->getOrigData()[0]);exit; )
For an example of this in use see:
http://fabrikar.com/forums/index.php?threads/approve-form-before-pdf-generation.47518/#post-246324

Updating a form's value on Save(top)

Often you will want to update the data that has been submitted by the form, run your plugin onBeforeProcess. To do this the php would be:
If you need to update your data AFTER the form has been processed (and data has been written to the database), using onAfterProcess, note that the tablename___ prefix will have been removed from $formModel->formData[], so use $formModel->formDataWithTableName[] instead to access data. Also, using updateFormData() will have no effect, you have to manually run a query to update your table.

Conditionally updating a form's value on Save(top)

Lets say we want to update the field 'sport's value to 'badminton' when the field name's value is 'rob'. To do this the php would be:
You must use full element names ('table___element') with the onBeforeStore setting and short element names ( 'element' - no table name) with the onAfterProcess setting.

Updating a form's value before showing the form(top)

This would use the same code as the above example except you set the "plugin location" to onLoad

Fabrik 3.1. onward, use
for manipulating the data onLoad.

Stopping form submission (top)

Set your plug-in to run 'onBeforeProcess' add this script:
For Fabrik 3.0
For Fabrik 3.1
in order to change the main error message, which will show automatically when any of the field error messages are set, you can set:
this is only displayed if one of the _arErrors['tablemame___elementname'] values is set...

Totalling radio buttons and placing the result in an element (top)

Say you want to total the selected values of three radio buttons and store their total in another element when the form is submitted:

Lets say you have 3 radio elements, called listname___radio1, listname___radio2 and listname___radio3, with values 1,2,3 and labels one,two,three.

You want to total these and update a element 'listname___total'. You're php code would look like:
You would set it to run on both new and edit records, and to run on 'Start of form submission'

IP Check(top)

Say you have a form where you only want to record one record per IP address. Your form saves to the database table 'contacts' and stores the user's IP address in an element called 'ip':

To stop the form from loading add an onLoad PHP form plugin with the following code:

Insert a record in another table and update a form's field with the records primary key(top)

Decrease a value in another table(top)

I have a list called Courses which holds the available courses that a user can sign up for.
Courses have an element called spaces that is a number - example 20 spaces.
When a user signs up for a course I would like the value of spaces to be -1 space.

Get row ID of a form(top)

When a form is loaded, it's rowid is located in the querystring. To retreive it, for example for database manipulations, use : '{rowid}' in the PHP code.