logo-radria.gif
   
Blog Download Documentation Forum Tasks Home
Blog Download Documentation Forum Tasks Home
barside-right.gif
barside-left.gif
logo-sql.gif





Custom field types

It is quite easy to create custom field types.

The registry is based on 2 classes :

  1. FieldType: this is the base class for all field types.
  2. 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 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

      Class FieldTypeLink extends FieldTypeChar {
 
          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 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

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

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 getRData method is optional variables of FieldTypes can be accessed directly. For example :

 $this->getRData('hidden');

can be written as:

 $this->hidden

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 EventAction is added to the form: FieldUsPhone→eventFormatUsPhone 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 lets edit the class FieldUsPhone again and add the method: eventFormatUsPhone

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

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.

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

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

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 :

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

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

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

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:

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

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:

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

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

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

Download the package.

You can upload it in a 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 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.

 
core/registry/creating_new_field_types.txt · Last modified: 2008/11/10 13:57 by admin
 
Recent changes RSS feed Creative Commons License Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki