Custom field types

It is quite easy to create custom field types.

The registry is based on 2 classes :

1. RegistryFieldBase: this is the base class for all field types.
2. Registry: 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 RegistryFieldBase class or an existing Field type class that already extends the RegistryFieldBase.

You will find all of the Radria default Registry classes in RadriaCore/class/Registry.class.php and documented in Default Field Types

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 (strFBFieldTypeChar class) field type to display as an HTML link.

In WebIDE in the Class tab create a new class: FieldTypeLink.class.php

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

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:

<?php
   /** 
    * Custom link field 
    */
  include_once("class/FieldTypeLink.class.php");
?>

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:

 <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>

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

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

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.

Lets start by creating our new RegistryField class. In the WebIDE in the class tab create a new class called: FieldUsPhone.class.php

<?php
Class FieldUsPhone extends RegistryFieldBase {
 
    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("utils.formatUsPhone");
            $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;
	    }
        }
    }
 
}
?>

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.

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.

In the default_form method we can see that a EventAction is added to the form: utils.formatUsPhone This EventAction will recompose the different fields and store them in the fields array so it can be processed by a database or object.

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

In the WebIDE in the Events tab we create a new EventAction called: utils.formatUsPhone

<?php
  /**
   * Event : utils.formatUsPhone
   *
   * Event to format the phone numbers type.
   * Get all of the phone field names.  
   * Concatenate the fields and update the main fields array.
   **/
 
   $fields = $this->getParam("fields");
   $phonefieldname = $this->getParam("phonefieldname");
   $areaphone = $this->getParam("areaphone");
   $secondphone = $this->getParam("secondphone");
   $thirdphone = $this->getParam("thirdphone");
   $internationalprefix = $this->getParam("internationalprefix");
   $extention = $this->getParam("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;
   }
   $this->updateParam("fields", $fields);
 
?>

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 Event execution a mydb.updateRecord or mydb.addRecord Event Action may process the fields array and update the data in the database.

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

<?php 
  /**
   * Custom phone number field 
   */
 
  include_once("class/FieldUsPhone.class.php");
?>

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 :

  <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>

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

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.

In the configuration file: includes/FieldUsPhone.conf.inc.php

<?php 
  /**
   * Custom phone number field 
   */
 
  include_once("class/FieldUsPhone.class.php");
 
  $cfg_fieldType[] = "FieldUsPhone";
  $FieldUsPhone = "Phone Number (US)";
 
?>

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.

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.

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:

<?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>

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:

<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>

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

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:

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).

Nothing

Download the package.

You can upload it in a repository.

Its now time to install the package 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 SiteManager configuration.

Edit the

  SiteManager/config.php

And change:

    // Show or hide the WebIDE project
    $cfg_show_WebIDE = false;

to

    // Show or hide the WebIDE project
    $cfg_show_WebIDE = true;

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.