====== Custom field types ======
It is quite easy to create custom field types.

The registry is based on 2 classes :
  - **FieldType**: this is the base class for all field types.
  - **Fields**: this is the class that is used to load the registry xml file and apply the registry to the fields.


To create your own field types you can extend the FieldType class or an existing Field type class that already extends the FieldType.

You will find all of the Radria default FieldType classes in RadriaCore/class/Registry.class.php and documented in [[core:registry:field_type|Default Field Types]]







===== Web Link Example =====

For example lets say you have a Field that contains URLs and you want that field to be displayed as a link.

We will extend the one line of text (FieldTypeChar class) field type to display as an HTML link.

In WebIDE in the Class tab create a new class: **FieldTypeLink.class.php**
<code php>
      Class FieldTypeLink extends FieldTypeChar {

          function default_Disp($field_value="") {
              if (!$this->getRData('hidden')) {
                  $this->processed .= “<A href=\”.$field_value.”\”>”.$field_value.”</a>”;
              }
          }

      }
</code>

We overwrite the method default_Disp to display a link for that value.

To load that class in your application create in the WebIDE->Web Page the following configuration file: **includes/FieldTypeLink.conf.inc.php**
With the following content:
<code php>
<?php
   /** 
    * Custom link field 
    */
  include_once("class/FieldTypeLink.class.php");
?>
</code>

To test the new field type create a table with the WebIDE with a text field call **weburl**.
Edit the registry XML source associated with your table and replace the **rfield** weburl with the following: 
<code xml>
 <rfield name="weburl">
    <rdata type="required">1</rdata>
    <rdata type="label">Web Page</rdata>
    <rdata type="textline">10:30</rdata>
    <rdata type="fieldtype">FieldTypeLink</rdata>
  </rfield>
</code>

By extending the FieldTypeChar our Link field type inherits the rdata text line.

The only required rdata is the fieldtype with the name of the FieldType class : FieldTypeLink.



===== Phone Number example =====

As a second example we will create an input mask for a phone number. We want the phone number to be typed into 3 fields and display them in the form of : (310)-370-3365 but store them in the database as a string of 10chars : 3103703365.




==== Registry Field Object ====

Lets start by creating our new FieldType class. In the WebIDE in the class tab create a new class called: **FieldUsPhone.class.php**
<code php>
<?php
Class FieldUsPhone extends FieldType {
 
    function default_Form($field_value="") {
        if (!$this->getRData('hidden') && !$this->getRData('readonly')) {
            if ($this->getRData('css_form_class')) {
               $field_class = $this->getRData('css_form_class');
            } else { $field_class = "adformfield"; }
            
            $international_prefix = "";
            $extention = "";
            if ($this->getRData('international') || $this->getRData('extention')) { 
            	list($field_value, $international_prefix, $extention) = explode("||", $field_value);
            }
            $e_format = new Event("FieldUsPhone->eventFormatUsPhone");
            $e_format->setSecure(false);
            $e_format->setHideKey(true);
            $e_format->setLevel(900);
            $fval .= $e_format->getFormEvent();
            $fval .= "<input type=\"hidden\" name=\"phonefieldname[]\" value=\"".$this->getFieldName()."\">";
            if ($this->getRData('international')) {
		$fval .= "\n+<input class=\"".$field_class."\" 
		        name=\"internationalprefix[".$this->getFieldName()."]\" 
		        value=\"".$international_prefix."\" 
		        type=\"text\" size=\"2\"> -";
            }
            $fval .= "\n(<input class=\"".$field_class."\" 
                                name=\"areaphone[".$this->getFieldName()."]\" 
                                value=\"".substr($field_value, 0, 3)."\" 
                                type=\"text\" size=\"3\">)";
            $fval .= "\n-<input class=\"".$field_class."\" 
                                name=\"secondphone[".$this->getFieldName()."]\" 
                                value=\"".substr($field_value, 3, 3)."\" 
                                type=\"text\" size=\"3\">";
            $fval .= "\n-<input class=\"".$field_class."\" 
                                name=\"thirdphone[".$this->getFieldName()."]\" 
                                value=\"".substr($field_value, 6, 4)."\" 
                                type=\"text\" size=\"4\">";
            
            if ($this->getRData('extention')) {
 		$fval .= "\n Ext:<input class=\"".$field_class."\" 
		        name=\"extention[".$this->getFieldName()."]\" 
		        value=\"".$extention."\" 
		        type=\"text\" size=\"5\">";           
            }
        $this->processed .= $fval;
       }
    }
 
    function default_Disp($field_value="") {
 	if (!$this->getRData('hidden')) {
 	    $international_prefix = "";
            $extention = "";
            if ($this->getRData('international') || $this->getRData('extention')) { 
            	list($field_value, $international_prefix, $extention) = explode("||", $field_value);
            }
            if (!empty($international_prefix)) { $international_prefix = "+".$international_prefix." "; }
            if (!empty($extention)) { $extention = " Ext:".$extention; }
            if (strlen($field_value) > 0) {
	        $this->processed .= $international_prefix."(".substr($field_value, 0, 3).")-".substr($field_value, 3, 3)."-".substr($field_value, 6, 4).$extention;
	    }
        }
    }
 
}
?>
</code>


You can see in the script above the FieldUsPhone field type takes a single field and displays it in 3, 4 or 5 form fields.
Some custom options (RData) are set like **international** and **extention**.

<note> The **getRData** method is optional variables of FieldTypes can be accessed directly. 
For example : <code php> $this->getRData('hidden'); </code> can be written as: <code php> $this->hidden </code>
</note> 

The value of the field is sent as a param ($field_value). We break that value into 3 values to match the 3 form field sizes. We create the html for the 3 input fields and name them in an array.
We will also need a generic array that will store all of the field names.








==== Formating Event Action ====

In the **default_form** method we can see that a [[core:events|EventAction]] is added to the form: **FieldUsPhone->eventFormatUsPhone**
This [[core:events|EventAction]] will recompose the different fields and store them in the fields array so it can be processed by a database or object.


The [[core:events]] parses the phonefieldname array to get all of the phone fields and format them.

In the WebIDE lets edit the class FieldUsPhone again and add the method: **eventFormatUsPhone** 

<code php>
<?php

Class FieldUsPhone extends FieldType {
 
  /**
   * Event : eventFormatUsPhone
   *
   * Event to format the phone numbers type.
   * Get all of the phone field names.  
   * Concatenate the fields and update the main fields array.
   **/

function eventFormatUsPhone(EventControler $event_controler) {

 
   $fields = $event_controler->fields;
   $phonefieldname = $event_controler->phonefieldname;
   $areaphone = $event_controler->areaphone;
   $secondphone = $event_controler->secondphone;
   $thirdphone = $event_controler->thirdphone;
   $internationalprefix = $event_controler->internationalprefix;
   $extention = $event_controler->extention;
 
   foreach ($phonefieldname as $phonefield) {
        if (!empty($internationalprefix[$phonefield]) || !empty($extention[$phonefield])) {
           $extra = "||".$internationalprefix[$phonefield]."||".$extention[$phonefield];
        } else {
           $extra = "";
        }
        $dbfield = $areaphone[$phonefield].$secondphone[$phonefield].$thirdphone[$phonefield].$extra ;
        $fields[$phonefield] = $dbfield;
   }
   $event_controler->fields = $fields;
 
}
// Continue the class 
}
?>
</code>

We get the fields array from the event controller, parse all of the phonefieldname fields, concatenate the field values and store the phone field in the fields array.
Before finishing we update the fields array in the event controller parameters.

We uses arrays indexed by field names to support multiple fields of that type in one form.

The **$fields** array is indexed by field name and contains field values submitted from the form. 
This array will be used further in the [[core:events|Event]] execution a mydb.updateRecord or mydb.addRecord Event Action may process the fields array and update the data in the database.


==== Auto Load configuration ====


To load the field type class in the application we need to create an auto include configuration file. 
In the WebIDE -> Web Pages create the following file: **includes/FieldUsPhone.conf.inc.php**
<code php>
<?php 
  /**
   * Custom phone number field 
   */

  include_once("class/FieldUsPhone.class.php");
?>
</code>




==== Registry XML source ====

Now to attach this new field type add a **phone_number** text field to one of your table and then edit its registry.

The registry rfield for a us phone field will look like this :
<code xml>
  <rfield name="phone_number">
    <rdata type="label">Phone</rdata>
    <rdata type="international">1</rdata>
    <rdata type="extention">1</rdata>
    <rdata type="css_form_class"></rdata>
    <rdata type="fieldtype">FieldUsPhone</rdata>
  </rfield>
</code>

The international prefix and extention are optional, by default if their rdata are not in the registry they will not display.



===== Add to WebIDE =====

Instead of having to edit the Registry source file to add your custom field type, it is more convenient to directly add it in the WebIDE.

You will need to create 2 or 3 additional files. Improve your configuration file to register the field to WebIDE field type arrays.


==== Configuration File ====

In the configuration file: **includes/FieldUsPhone.conf.inc.php **
<code php>
<?php 
  /**
   * Custom phone number field 
   */
 
  include_once("class/FieldUsPhone.class.php");

  $cfg_fieldType[] = "FieldUsPhone";
  $FieldUsPhone = "Phone Number (US)";

?>
</code>

The **$cfg_fieldType** array is used by WebIDE to register the field.
Then we assign a variable with the same name to give it a human readable label.








==== Options Form ====

Next we need to provide some information for the options form. The simplest way is to create a Registry.

And if you need further customization you can create a custom form.

=== Registry ===

With the WebIDE create a new registry called **FieldUsPhone.reg.xml** for each **RData** used by our field type.
The **FieldUsPhone.reg.xml** source code will looks like:
<code xml>
<?xml version="1.0"?>
<registry>
  <rfield name="international">
    <rdata type="label">International Prefix</rdata>
    <rdata type="listlabels">Yes:No</rdata>
    <rdata type="listvalues">1:0</rdata>
    <rdata type="default">1</rdata>
    <rdata type="fieldtype">strFBFieldTypeListBoxSmall</rdata>
  </rfield>
  <rfield name="label">
    <rdata type="default"></rdata>
    <rdata type="hidden"></rdata>
    <rdata type="html"></rdata>
    <rdata type="label">Label</rdata>
    <rdata type="readonly"></rdata>
    <rdata type="required"></rdata>
    <rdata type="textline">:</rdata>
    <rdata type="css_form_class"></rdata>
    <rdata type="css_disp_class"></rdata>
    <rdata type="css_form_style"></rdata>
    <rdata type="css_disp_style"></rdata>
    <rdata type="id"></rdata>
    <rdata type="fieldtype">strFBFieldTypeChar</rdata>
  </rfield>
  <rfield name="default">
    <rdata type="default"></rdata>
    <rdata type="hidden"></rdata>
    <rdata type="html"></rdata>
    <rdata type="label">Default</rdata>
    <rdata type="readonly"></rdata>
    <rdata type="required"></rdata>
    <rdata type="textline">50:</rdata>
    <rdata type="css_form_class"></rdata>
    <rdata type="css_disp_class"></rdata>
    <rdata type="css_form_style"></rdata>
    <rdata type="css_disp_style"></rdata>
    <rdata type="id"></rdata>
    <rdata type="fieldtype">strFBFieldTypeChar</rdata>
  </rfield>
  <rfield name="extention">
    <rdata type="label">Extention</rdata>
    <rdata type="listlabels">Yes:No</rdata>
    <rdata type="listvalues">1:0</rdata>
    <rdata type="default">1</rdata>
    <rdata type="fieldtype">strFBFieldTypeListBoxSmall</rdata>
  </rfield>
  <rfield name="css_form_class">
    <rdata type="fieldtype">PageBuilderFieldListStyles</rdata>
    <rdata type="label">CSS Class style</rdata>
    <rdata type="emptydefault">yes</rdata>
    <rdata type="default"></rdata>
    <rdata type="css_form_class"></rdata>
    <rdata type="css_form_style"></rdata>
    <rdata type="id"></rdata>
  </rfield>
</registry>

</code>



=== Custom Form ===


If you create custom field types you will want them to work with WebIDE so it can be added to a database table with the GUI.
The webIDE needs a few additional files and parameters so it can integrate your new field.

You will need a form and additional values in your configuration file.
Below is a sample form to be stored in the form folder with the exact same name as your Class.



In WebIDE create a new form called: **FieldUsPhone**
and enter the following code in the Row:
<code html>
<table>
  <tr>
    <td>Label</td>
    <td>[label]</td>
  </tr>
  <tr>
    <td>Default Value</td>
    <td>[default]</td>
  </tr>
  <tr>
    <td colspan="2">Turning on the field below will add International prefix and 
                    extention forms field to the phone number mask
    </td>
  </tr>
  <tr>
    <td>International</td>
    <td>[international]</td>
  </tr>
  <tr>
    <td>Extention</td>
    <td>[extention]</td>
  </tr>
  <tr>
    <td colspan="2">You can select a style class for the form fields</td>
  </tr>
  <tr>
    <td>CSS class Style</td>
    <td>[css_form_class]</td>
  </tr>
</table>
</code>


Now we will create a package and install it in the WebIDE.

If you are in a rush you can just copy the following files in the WebIDE:

    class/FieldUsPhone.class.php
    events/utils.formatUsPhone.inc.php
    includes/FieldUsPhone.conf.inc.php
    registry/FieldUsPhone.reg.xml
    form/FieldUsPhone.form.xml


<note> Its better to create a package of your field type so you can install it in other projects and better manage upgrades and new versions.</note>


===== Package a Field Type =====

If you want to reuse your custom field type in other projects you will need to create a package.
In this section we will only describe the specifics of Field Type packages. If you want more information on package and Add-On creation we can suggest the following articles:




==== Package Builder ====

Install the Package Builder

In the SiteManager's package section install in your project the following packages:

     contentadmin
     package builder

Then click on **Package Builder** in the Tools list and sign on in the Content Admin __(username / password are the same as your database access for this project)__.

<box blue round|Create your new package>

Package Information:
  * Name: FieldType_UsPhone
  * Version: 0.1
  * Description: Field type to display and enter phone numbers in a proper format.

Files to Add in the package:
  * class/FieldUsPhone.class.php
  * events/utils.formatUsPhone.inc.php
  * includes/FieldUsPhone.conf.inc.php
  * registry/FieldUsPhone.reg.xml
  * form/FieldUsPhone.form.xml

Database:
  Nothing

Parameters:
  * PHP and HTML file to upload: **none**

</box>


Download the package.

You can upload it in a [[core:package:repository:setting_up_package_repositories|repository]].

Its now time to install the package in the WebIDE.




==== Install in the WebIDE ====

WebIDE is a Radria project. By default it is hidden from the list of projects in the SiteManager.
You will need to change your [[:configuration#enable_webide_project|SiteManager configuration]]. 

Edit the 

    SiteManager/config.php

And change:
<code php>
    // Show or hide the WebIDE project
    $cfg_show_WebIDE = false;
</code>
to
<code php>
    // Show or hide the WebIDE project
    $cfg_show_WebIDE = true;
</code>

Then in the list of projects you should see the WebIDE.

Open the project and in the package section install our new **FieldType_UsPhone-0.1.pkg**

Then you should see the new field type when adding a Table Field or a Registry Field.