Function Reference

Function Reference

Override functions

These overrides are called at specific points in form processing.

 

BeforeStartProcessing()

function BeforeStartProcessing() 

 

This function is called at the very start, before any processing starts.

 

Override BeforeStartProcessing() function to do any initialization, or configuration setting.

 

1348652662_001_45This function is called each and every time the form processor script is invoked.

 

<?PHP
class MyCustomUploadFolder extends FM_ExtensionModule
{
function BeforeStartProcessing()
{
  $this->logger->LogInfo("BeforeStartProcessing is called");
 
  $this->config->file_upload_folder =
    '../../../uploads/form1';
 
  $this->config->allow_nonsecure_file_attachments = true;
 
  //you can initialize PHP settings too.
  ini_set("sendmail_from","me@mywebsite.com");
  return true;
}
}
?>
 

BeforeFormDisplay()

BeforeFormDisplay(&$formvars,$pagenum) 

 

This function is called before form is displayed.

 

Override this function to load the form with initial data. To fill the form, set the values in the $formvars associative array. For example, if a text field "Name" is to be loaded, set $formvars['Name']='value;

 

$pagenum is the current page being displayed.

 
1348652662_001_45 The function must return true or false. If the return value is false, the form is not displayed.

 

 

LoadDynamicList

function LoadDynamicList($listname,&$rows)

 

If you have lists loaded from database, you can override the default functionality and load the list using your own function.

Just override the LoadDynamicList() in your extension module.

 

$listname is the name of the list in the form. (you can have any number of lists) . Return the list in the $rows array. as name value pair.

 

See the example below:

 

<?php

class MyListLoader extends FM_ExtensionModule

{

   function LoadDynamicList($listname,&$rows)

   {

       if($listname == 'dl1')

       {

           $rows[] = array('name'=>'Select ...','value'=>'');

           $rows[] = array('name'=>'Item 1','value'=>'Item 1');

           $rows[] = array('name'=>'Item 2','value'=>'Item 2');

           $rows[] = array('name'=>'Item 3','value'=>'Item 3');

           $rows[] = array('name'=>'Item 4','value'=>'Item 4');

           return true;

       }

       else if($listname == 'dl2')

       {

           $rows[] = array('name'=>'Select ...','value'=>'');

           $rows[] = array('name'=>'ExItem 1','value'=>'ExItem 1');

           $rows[] = array('name'=>'ExItem 2','value'=>'ExItem 2');

           $rows[] = array('name'=>'ExItem 3','value'=>'ExItem 3');

           $rows[] = array('name'=>'ExItem 4','value'=>'ExItem 4');      

           return true;

       }

       return false;

   }

}

?>

The code above first checks for the list name (d11 and d12 being the list names) and loads the list.

 

LoadCascadedList

function LoadCascadedList($listname,$parent,&$rows)

 

You can custom load cascaded lists by overriding this function. Cascaded lists are lists loaded based on the selection in another list. ( See Dropdownlist )

 

$listname is the name of the list and $parent is the item selected in the parent list. You have to return the list of items in the $rows array. See the example below:

 

<?php

class MyLoadCascaded extends FM_ExtensionModule

{

function LoadCascadedList($listname,$parent,&$rows)

{

   $this->logger->LogInfo("ext module: LoadCascadedList  $listname parent $parent");

   if($listname == 'dl2')

   {

       if($parent == 'Item 1')

       {

         $rows[] = array('name'=>'Sub Item 1.1','value'=>'Sub Item 1.1');

         $rows[] = array('name'=>'Sub Item 1.2','value'=>'Sub Item 1.2');

         $rows[] = array('name'=>'Sub Item 1.3','value'=>'Sub Item 1.3');

         return true;

       }

       else if($parent == 'Item 2')

       {

         $rows[] = array('name'=>'Sub Item 2.1','value'=>'Sub Item 2.1');

         $rows[] = array('name'=>'Sub Item 2.2','value'=>'Sub Item 2.2');

         $rows[] = array('name'=>'Sub Item 2.3','value'=>'Sub Item 2.3');

         return true;

       }

   }  

   return false;

}

}

?>

 

DoValidate()

DoValidate(&$formvars, &$error_hash) 

 

Override this function to Validate the final form submission.

 

The submitted form data is available in the $formvars variable.

If there are errors, set the error message in the $error_hash and return false.

 

1348652662_001_45 In a multi-page form, to validate individual pages, override the DoValidatePage() function.

The DoValidate() function is called only after the last page is submitted.

 

For example, if the "Email" value submitted in the form is validated error, set the message as shown here:

 
<?PHP
 
class MyCustomValidationModule

 extends FM_ExtensionModule
{
  function DoValidate(&$formvars, &$error_hash)
   {
      if(!isset($formvars['email']))
       {
           $error_hash["email"]="Bad Email";
          return false;
       }
      return true;
   }
}
 
?>

 

DoValidatePage

function DoValidatePage(&$formvars, &$error_hash,$page)

 

Override this function to Validate a page, after the page is submitted. ( 'next' button is pressed).

 

The submitted form data is available in the $formvars variable.

If there are errors, set the error message in the $error_hash and return false.

 

 

<?PHP

 

class MyCustomValidationModule

 extends FM_ExtensionModule

{

   function DoValidatePage(&$formvars, &$error_hash,$page)

   {

       if($page == 2 && !isset($formvars['email']))

       {

           $error_hash["email"]="Bad Email";

           return false;

       }

       return true;

   }

}

 

?>

The code above validates email in the page 3.

 

1348652662_001_45The page index is 0 based. So on first page, $page value will be 0.

 

1348652662_001_45First check for the page number when you validate using this function.

 

PreprocessFormSubmission

function PreprocessFormSubmission(&$formvars)

 

Override this function to edit the form submission and add your own cleanup or enhancements.

PreprocessFormSubmission() is called after validations. You can add or change the submitted form data before it appears in the form submission email or in the database.

 

Here is an example:

 

<?php

class MyPreproc extends FM_ExtensionModule

{

   function PreprocessFormSubmission(&$formvars)

   {

       $formvars['Name'] = ucwords($formvars['Name']);

     

       return true;

   }

}

?>

The code above updates the Name field so that all names are auto-converted to 'Uppercase first letter'.

( john becomes John ).

 

BeforeConfirmPageDisplay()

BeforeConfirmPageDisplay(&$formvars)

 

BeforeConfirmPageDisplay() is Called just before displaying the 'confirm form submission' page (If the option is selected) .

 

The submitted form data will be available in the $formvars variable. You can customize the display of the values by modifying the values in the $formvars array.

 

For example, the code below makes the 'Name' display in Red if the submission was 'Bob'. Note that the change affects only the display. Not the actual form submission data.

 
<?PHP
 
class MyConfirmPageCustomModule

 extends FM_ExtensionModule
{
  function BeforeConfirmPageDisplay(&$formvars)
   {
      if($formvars["Name"] == 'Bob')
       {
           $formvars["Name"] =

                 "<font color='red'>".$formvars["Name"]."</font>";
       }
      return true;
   }
}
 
?>

 

 

BeforeSendingFormSubmissionEMail()

 

function BeforeSendingFormSubmissionEMail(&$receipient,&$subject,&$body) 

 

BeforeSendingFormSubmissionEMail is called just before sending email to the 'receipients' you have configured in the 'form to email' page. If BeforeSendingFormSubmissionEMail() function returns false, the email is not sent. You can override this function to send the email based on a condition. You can modify the body or the subject of the email as well.

 
<?PHP
 
class MyCustomConditionalEmail

         extends FM_ExtensionModule
{
  function BeforeSendingFormSubmissionEMail(&$receipient,

         &$subject,&$body)
   {
      if(false !== strpos($receipient,'admin@website.com'))
       {
          return true;
       }
      elseif($this->formvars['SendTo'] == 'sales' &&
             false === strpos($receipient,'sales@mywebsite.com'))
       {
          return false;
       }

 
      if($this->formvars['SendTo'] == 'support' &&
             false === strpos($receipient,'support@mywebsite.com'))
       {
          return false;
       }      
      return true;
   }
}
 
?>

 

BeforeSendingAutoResponse()

function BeforeSendingAutoResponse(&$receipient,&$subject,&$body)  

 

BeforeSendingAutoResponse() is called just before sending auto-response (if you have enabled auto-response in the 'form processing options' page).

 

If this function returns false, the auto-response is not sent. You can change the recipient or the body or the subject of the email.

 
<?PHP
 
class MyCustomResponseEmail

 extends FM_ExtensionModule
{
function BeforeSendingAutoResponse(&$receipient,

                         &$subject,&$body)
 {
  //The Name part is composed using FirstName

 //and LastName fields
   $receipient = $this->formvars['FirstName'].

         ' '.$this->formvars['LastName'].

         '<'.$this->formvars['Email'].'>';

 
   $this->logger->LogInfo("New receipient $receipient");
 
  //update the body of the email with conditional sections
  if(isset($this->formvars['subscribe']))
   {
       $body =

         str_replace('_REPLACE_CODE_',

                 'Thanks for the subscription too!',$body);
   }
  else
   {
       $body = str_replace('_REPLACE_CODE_','',$body);
   }
 }
}  
 
?>
 

 

FormSubmitted()

function FormSubmitted(&$formvars) 

 

FormSubmitted() function is called once the form submission data is finally submitted (After validations and confirmation page, if any).

 

The form submission data is present in the $formvars variable. You can handle the final, form submission data in this function.

 

For example, you can save the form submission to a database table or post the data to a custom web service.

 

BeforeThankYouPageDisplay()

BeforeThankYouPageDisplay(&$formvars)  

 

BeforeThankYouPageDisplay() is called just before displaying the 'Thank you page'.

 

You can customize the display of the values (just like BeforeConfirmPageDisplay()) if you are using 'Thank You ' page template and if you have place holder variables. (Like %Name%) in the template.

 
The function is not called if the form is set to redirect to a 'Thank You' page URL rather than displaying a template.

 
<?PHP
 
class MyConfirmPageCustomModule

         extends FM_ExtensionModule
{
  function BeforeThankYouPageDisplay(&$formvars)
   {
      if($formvars["Name"] == 'Bob')
       {
           $formvars["Name"] =

                 "<strong>".$formvars["Name"]."</strong>";
       }
      return true;
   }
}
 
?>

 

See Also:

Collection of Extension Modules