Creating a Simple Contact Form

Description and Requirements
This example shows how to develop a "Contact Us" functionality. The functionality must be able to store user contacts in the database and send notification emails to the administrator.

Creating a Component for the Administration Panel
First, you must create a new component for the administration panel. By using this component, the administrator will manage the user contacts. New components can be created directly in the directory 'root/cmp'. However, we recommend that you create sub-directories '/back' and '/front' in the '/cmp' directory. In this example the 'root/cmp/back' and 'root/cmp/front' directories are used.

  1. Create a PHP file ContactUs.cmp.php in the 'root/cmp/back' directory. The sub-extension cmp is important, as it tells the system that this PHP file is a component.
  2. In the file declare a class named ContactUs (the name of the class has to be the same as the file's name). That class extends the CmsComponent class:
    class ContactUs extends CmsComponent{
      // define the name of the database table.
      public $base = 'tutorial_contact_us';
      }
     
  3. Override the main() method and declare two component fields. For more information about component fields, see the component-fields-options.txt file in the documentation.
    function main(){
      // call parent method for save main functionality. 
      parent::main();
     
      $this->setField('name', array(
      'text' => BASIC_LANGUAGE::init()->get('cu_name'),
      'perm' => '*'
      ));
      $this->setField('email', array(
      'text' => BASIC_LANGUAGE::init()->get('cu_email'),
      'perm' => '*'
      ));
      $this->setField('body', array(
      'text' => BASIC_LANGUAGE::init()->get('cu_body'),
      'perm' => '*',
      'formtype' => 'textarea',
      'dbtype' => 'text'
      ));
      }
      
  4. Add the component in the administration panel. To do that, in the administration panel go to System -> Components, click the Add button and enter the required information:





  5. The default system List view shows columns for all components fields. You can change this as shown below:
    function ActionList(){
      // do not need the admin to add new records
    $this->delAction('add');
     // make the form only for read
    $this->delAction('save');
    // make sorting support
      $this->sorting = new BasicSorting('name', false, $this->prefix);
     
      $this->map('name', BASIC_LANGUAGE::init()->get('cu_name'), 'formater'); 
      $this->map('email', BASIC_LANGUAGE::init()->get('cu_email'), 'formater'); 
      $this->map('body', BASIC_LANGUAGE::init()->get('cu_email'), 'cu_body'); 
      
      return parent::ActionList();
      }
      function formater($val, $name, $row){
       // make click email write support
      if($name == 'email'){
      return '<a href="emilto:'.$val.'">'.$val.'</a>';
      }
      return $val;
      }
    

The configuration of the administrative part of the functionality is finished.


Creating a Component for the Client Side
First, you create a component that extends the ContactUs class (the previously created administrative component). After that you create a template file with specific formatting for the task. Finally, create a page where the "Contact Us" functionality will be presented.

  1. Create a PHP file ContactUsFront.cmp.php in the 'root/cmp/front' directory:
      BASIC::init()->imported("ContactUs.cmp", "cmp/back")
      class ContactUsFront extends ContactUs {
    }
    
  2. Configure the component to create a form by default:
    function main(){
      parent::main();
     
      // make the form's name space. This will save form request if in the same page have
      // more forms (login, search, other components form).
      $this->prefix = 'cu';
    
      // redirect default action to form creator.
      $this->updateAction('list', 'ActionFormAdd');
    
      // (optional) change text of the action cancel and use it like reset button.
      $this->updateAction('cancel', null, BASIC_LANGUAGE::init()->get('cu_reset'));
      
      // for security delete edit and delete actions
      $this->delAction('edit');
      $this->delAction('delete');
      
      // by default the system use action edit when exist error. Because we stop edit
      // action will change to action add.
      $this->errorAction = 'add';
      }
      
  3. In the administration panel go to System -> Components, click the Add button and enter the required information:



  4. Create a new page for the "Contact Us" form. To do this, in the administration panel go to System -> Pages, click the Add button and enter the required information for the new page:








Security Issues
There are two security issues that must be addressed - spam and email validation.

Spam
To add captcha functionality in the form, add the following code in the main() method:

// make new field in the form.
  $this->setField('spam', array(
  'text' => BASIC_LANGUAGE::init()->get('cu_spam'),
  'formtype' => 'capcha',
  'dbtype' => 'none',
  'messages' => array(
  2 => BASIC_LANGUAGE::init()->get('invalid_sec_code')
  )
  ));
  
  // show method that will call after the standart validator.
  $this->specialTest = 'validator';
  
  // Make new method:
function validator(){
  if(
  strtolower(BASIC_GENERATOR::init()->getControl('capcha')->
  code($this->prefix.'spam')) 
  !=
  strtolower($this->getDataBuffer('spam'))
  ){
  $this->setMessage('spam', 2);
  }
  }
   

Email Validation
To add an error message for invalid emails, add the following code in the main() method:

 // add error message for invalid email
  $this->updateField('email', array(
  'messages' => array(
  2 => BASIC_LANGUAGE::init()->get('invalid_email')
  )
  ));
In the method validator() add this code:
  if(!BASIC::init()->validEmail($this->getDataBuffer('email'))){
  $this->setMessage('email', 2);
  }	


Sending Notification Emails to the Administrator

// extend the action save handler with send email functionality.
  function ActionSave(){
  // import spam mode.
  BASIC::init()->imported('spam.mod');
 
  // make email from form request
  $mail = new BasicMail(
  $this->getDataBuffer('email'),
  $this->getDataBuffer('name'), 
  array(
  'subject' => $this->getDataBuffer('subject'),
  'body' => $this->getDataBuffer('body')
  )
  );
  // send to support email. 
  $mail->send('support@sbnd.net');
  
  // make session flag thet will show message.
  BASIC_SESSION::init()->set('contact_sended', 1);
 
  return parent::ActionSave();
  }
  // extend the form creator to support show message after save success.
  function ActionFormAdd(){
  $this->delAction('cancel');
  
  if(BASIC_SESSION::init()->get('contact_sended')){
  BASIC_SESSION::init()->un('contact_sended');
  
  BASIC_ERROR::init()->setMessage(
  BASIC_LANGUAGE::init()->get('contact_send_success'));
  }
  return parent::ActionFormAdd();
  }
  }