How to Create a Custom Component

Description and Requirements
This example describes how to create a "FAQ" functionality that allows the site administrator to publish frequently asked questions and their answers. The functionality requires one text field to enter the question and another one to enter the answer.

Creating a New Component for the Administration Panel
First, you must create a component for the administration panel. With this component the administration user will add data for new questions and their answers. 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.

  1. Create a PHP file called FAQ.cmp.php in the 'root/cmp/back/' directory. The sub extension cmp is important because it tells the system that this PHP file is a component.
  2. In the new file declare a class called FAQ (the name of the class must be the same as the file's name) that extends the CmsComponent class:
    class FAQ extends CmsComponent{
      // define the name of the database table.
      public $base = 'faq';
      }
    

  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('question', array
      'text' => BASIC_LANGUAGE::init()->get('faq_question'),
      'perm' => '*',
      'lingual' => true
      ));
      $this->setField('answer', array( 
      'text' => BASIC_LANGUAGE::init()->get('faq_answer'),
      'perm' => '*'
      'formtype' => 'html',
      'dbtype' => 'longtext',
      'lingual' => true
      ));
    
    // (optional. By default is false) start ordering support 
      $this->ordering(true);
      } 
    

  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(){
      $this->map('question', BASIC_LANGUAGE::init()->get('faq_question'), 'formater', 'align=left'); 
      $this->map('answer', BASIC_LANGUAGE::init()->get('faq_answer'), 'formater', 'width=500', 'align=left'); 
    
      return parent::ActionList();
      }
      // We will make and formatter for the column “answer” that will cut the answer length to clear html tags and cut to 50
      // symbols.
      function formater($val, $name, $row){
      if ($name == answer){
      $tmp = strip_tags($val);
      if(count($tmp) > 50){
      return substr($tmp, 0, 50) . ' ...';
      }else{
      return $tmp;
      }
      }
      return $val;
      }
    

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


Createing a Component for the Client Side

First, you create a component that extends the FAQ 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 "FAQ" functionality will be presented.

  1. Create a PHP file FAQFront.cmp.php in the 'root/cmp/front' directory:
    BASIC::init()->imported("FAQ", "cmp/back")
      class FAQFront extends FAQ{
    }
    
  2. Create a template file called faq.tpl in the 'root/themes/your_theme/tpl' directory. You can check the path to you site theme in the administration panel, under System -> Settings -> SITE_THEME. For more information about themes, see the How To Use Exception And Mobile Theme section.
      <div class="faq-container">
      <ul>
      <!-- foreach(${rows},k,row,i) -->
      <li><a href="#id_${i}">${row.columns.question.label}</a></li>
      <!-- end -->
      </ul>
    
      <!-- foreach(${rows},k,row,i) -->
      <a name="id_${i}"></a><div>
      <h3>${row.columns.question.label}</h3>
      ${row.columns.answer.label}
      </div>
      <!-- end -->
      <div>
      
  3. Configure the component to use the new template:
    	
    function main(){
      parent::main();
      $this->template_list = "faq.tpl";
    }
    
  4. Stop the administrative actions and formatting:
    function main(){
      parent::main();
      //$this->delAction('save');
      //$this->delAction('add');
      //$this->delAction('delete');
      $this->delAllActions();
    	
      // configure this component to use our template.
      $this->template_list = 'faq.tpl';
      }
      /**
      *	Override this method to stop answer test formating. 
      */	
    	
      function formater($val, $name, $row){
      return $val;
      }
      
  5. In the administration panel go to System -> Components, click the Add button and enter the required information:



  6. Create a new page for the FAQ section. To do this, in the administration panel go to System -> Pages and click Add to create the page:







The creation and configuration of the "FAQ" functionality is done. When you open the page on client side the "FAQ" UI is displayed: