devot:eeDevoted to ExpressionEngine

Creating a Custom Fieldtype for ExpressionEngine With FieldFrame

March 12, 2009
by Ryan Masuga

I Was (Field)Framed!

FieldFrame is a new ExpressionEngine extension by Brandon Kelly of Playa Extension fame. It is a “framework for rapid development of fieldtype extensions in ExpressionEngine.” What it boils down to in layman’s terms is that FieldFrame will take care of much of the ugly parts of developing an extension – and there are a few ugly parts including some nasty RegExp stuff, among other considerations too heinous to mention here.

Adoption of FieldFrame for development of custom field type extensions will have a few advantages:

1. More rapid development, obviously
2. More extensions being made, due to simplifying the process
3. Less clutter on the Extensions Manager page, making that section more manageable

So, considering that development might be quicker if this is actually easy to do, I decided to try my hand at creating a FieldFrame fieldtype. Following is start to finish how it all went down.

Keep in mind I’m what I consider a “mid-level EE dev.” I know some PHP, but I wouldn’t claim to be exceptionally versed in it. I’m familiar with ExpressionEngine’s hooks and how some of the more common ones work from having developed a few extensions in the past.

Creating a FieldFrame Fieldtype for ExpressionEngine

I didn’t just want to make an extension in a vacuum. I read a tweet on Twitter last week from an ExpressionEngine user:

“Anybody know a color picker experessionengine extension?” – jackmcdade

I googled “jquery color picker field” and compared a few. The first one on the list, (Eyecon.ro jQuery Color Picker), was the best (and there is no license of any kind I could find) so I went with that one on the assumption I could include the necessary files in the download for what would become MD Color Picker.

The goal was to recreate the third example on the Eyecon page as an ExpressionEngine custom field: a simple text input you click that reveals the color picker. Selecting a color places the hex value in the field.

Gathering the Fieldtype Files

The nice thing about FieldFrame fieldtypes is that any necessary scripts or support images are contained in a folder with the name of the fieldtype that is contained in the “fieldtypes” folder that resides in your “extensions” folder.

I downloaded all the files necessary for the jQuery colorpicker to operate, and put them in a folder called “md_color_picker.” Then I created a blank fieldtype file called ft.md_color_picker.php. Once I had all that in place, it was time to make the field.

Creating the MD Color Picker Fieldtype

There are only two things this fieldtype needs to do to work. It needs to present the user with a text input and also ensure the JS and CSS files for the Colorpicker load in the head of the Publish and Edit screens of the ExpressionEngine Control Panel.

Start to finish development time was about 1.5 hours. About 20 minutes of that was me trying to figure out why a hook wasn’t being registered. I contacted Brandon, who clarified what I needed to do. He then updated the FieldFrame docs with the info I needed, so you shouldn’t run in to the same problem I did if you’re using any custom hooks. So, actual dev time was about 1.25 hours. That includes reading the FieldFrame docs, making a local Git repository, and testing locally.

Here are the entire contents of the ft.md_color_picker.php file (less the comments at the top of the file):

<?php
if ( ! defined('EXT')) exit('Invalid file request');
 
class Md_color_picker extends Fieldframe_Fieldtype {
 
  var $info = array(
    'name'             => 'MD Color Picker',
    'version'          => '1.0.0',
    'desc'             => 'Provides a color picker custom field',
    'docs_url'         => 'http://masugadesign.com/the-lab/scripts/md-color-picker/',
    'versions_xml_url' => 'http://masugadesign.com/versions/'
  );
 
  var $hooks = array('publish_form_headers');
 
  function publish_form_headers()
  {
    $r = $this->get_last_call('') . NL . NL;
 
  $r .= '<script src="'.FT_URL.'md_color_picker/js/colorpicker.js" type="text/javascript" charset="utf-8">>/script>';
  $r .= '<link rel="stylesheet" media="screen" type="text/css" href="'.FT_URL.'md_color_picker/css/colorpicker.css" />' .NL .NL;
 
  return $r;
  }
 
   function display_field($field_name, $field_data)
   {
   global $DSP;
 
   $r = '<script type="text/javascript" charset="utf-8">
  (function($){
    $(document).ready( function(){
     $("#'.$field_name.'").ColorPicker({
      onSubmit: function(hsb, hex, rgb) {
       $("#'.$field_name.'").val(hex);
      },
      onBeforeShow: function () {
       $(this).ColorPickerSetColor(this.value);
      }
     })
     .bind("keyup", function(){
      $(this).ColorPickerSetColor(this.value);
     });
    }); 
   })(jQuery);
   </script>';
  $r .=  $DSP->input_text($field_name, $field_data, '6', '6', 'input', '60px', '', FALSE);
 
    return $r;
  }
 
/* END class */
}
/* End of file ft.md_color_picker.php */
/* Location: ./system/extensions/fieldtypes/md_color_picker/ft.md_color_picker.php */

Essentially only 55 lines to get the job done – not bad. I can tell you from having developed other extensions that this extension would have been much, much longer without FieldFrame. Take a simple custom field extension such as MD Dulee Noted which is about 554 lines. For what MD Dulee Noted does, it could probably be chopped at least in half if it were built as a FieldFrame fieldtype.

The directory structure for a fieldtype is relatively straightforward, too. Your fieldtype goes in a folder named for the fieldtype, and is placed inside extensions → fieldtypes. Any supporting files also go in your fieldtype folder.

Break It Down For Me, Fella

I’ll take a look at the fieldtype file from top to bottom. The most basic fieldtype you can conceive is outlined on the FieldFrame Wiki page titled A Simple Fieldtype. The only way in which MD Color Picker is any more complicated is that it makes use of a hook, and so requires an extra array and extra function.

Class

You name the class the same as you do the folder that your fieldtype file(s) reside in, and you should always start your class with a capital letter, otherwise it won’t load.

$info Array

This is required for all fieldtypes. As far as I know, only the last line is entirely optional (more details below).

$hooks Array

Because I needed to load a CSS file and a JS file in the head, I had to use the publish_form_headers hook. So that’s added to the array here.

publish_form_headers Hook

This is the function used to put the scripts into the top of the page. You can see I’m loading the files required for the jQuery color picker to work correctly. Note that I’m using a supplied fieldtyp constant called FT_URL which is set in the FieldFrame settings, and outputs the path to the FieldFrame folder.

display_field Function

This function displays the custom field in the CP. I knew I needed a text input, so I made use of ExpressionEngine’s Display Class to render the text input:

$r .=  $DSP->input_text($field_name, $field_data, '6', '6', 'input', '60px', '', FALSE);

That line outputs a text input with a size of 6, maxlength of 6, class of “input”, that is 60 pixels wide, and won’t convert its entities to ASCII text (FALSE is the default). For more info on the Display Class, you can peruse the EE Display Class Reference at your leisure.

Next we’ll look at some of the pros and cons of using FieldFrame.

Big Advantages

There are a number of cool things about making an EE custom field as a FieldFrame fieldtype instead.

Repeating Functions are Handled By FieldFrame

Because FieldFrame handles so much of the normal drudgery, you can concentrate on the functions, settings, display and behavior that make your custom fieldtype what it is.

Easy LG Addon Updater Compatibility

By adding one line to your FieldFrame fieldtype in the $info array, you can enable your fieldtype to work seamlessly with LG Addon Updater (LGAU), if it is installed. No longer will you have to manually add the two LGAU hooks, and drop the two functions somewhere in your file. LGAU compatibility is built in to FieldFrame.

'versions_xml_url' => 'http://masugadesign.com/versions/'

As long as that line is present in your $info array (and pointing to your XML file), the extension will call home to your XML file to make sure the newest version of your fieldtype is installed for the user – FieldFrame takes care of all the rest. For full instructions on making a proper XML file for LG Addon Updater, check the source file area of the docs at Leevi Graham’s site.

The Extensions Manager Remains Manageable

Many sites I work on utilize a number of EE extensions, and that page can get extremely long. For example, devot-ee.com has 48 extensions installed. That would be longer by at least three items at this point, due to the default fieldtypes that come with FieldFrame. The more custom field type extensions that get made with FieldFrame, the more they will be sectioned off into the FieldFrame settings page, leaving the Extension Manager to display those extensions that do other things.

Yeah, So What’s the Catch?

The only drawback I can see at this point is that FieldFrame is a 3rd-party solution. Reliance on another developers’s extension for your extension to work properly may be a real issue for some people. This is sort of the same situation when you consider how add-ons use LG Addon Updater to call home for updates – except that LGAU isn’t critical to your site functioning. If LGAU isn’t present, the hooks to call home are just ignored. In this case, if FieldFrame isn’t installed, any custom field extensions that rely on it are not going to function as expected.

Further Information

Brandon is keeping a Fieldtype Catalog at GitHub. If you’ve created a FieldFrame fieldtype, notify him to get the addon added to the catalog. All fieldtypes will also be cataloged here at devot:ee in the forthcoming add-on repository. The fieldtype catalog is no more, but you can easily see what fieldtypes exist using devot:ee's advanced add-on filter. [Updated by Ryan - March 10, 2010]

There is an EE Forum thread about FieldFrame, and FieldFrame can be downloaded from GitHub. The FieldFrame wiki/documentation is now at Pixel & Tonic.

The Colorpicker extension used as an example has two pages. You can find the MD Color Picker page at Masuga Design (among other nifty add-ons), as well as at GitHub.

I certainly hope I was able to accomplish a few things with this write-up:

1. Explain why developing custom fieldtypes will be better – and faster – with FieldFrame
2. Show how to make a FieldFrame fieldtype
3. Explain a bit about the hooks and functions in the fieldtype, which also applies to “normal” extension development.

I think FieldFrame is an enormous boon to ExpressionEngine developers and the entire EE community. I can see this extension becoming one of those few great “must installs” in very short order. If you haven’t tried it yet, download FieldFrame (which is free), make an EE sandbox environment, and kick the tires. Even if you never create a custom fieldtype yourself or download any fieldtypes that don’t already come with FieldFrame, I think you’ll find the three included fieldtypes: Checkbox, Checkbox Group, and Radio Group very useful when setting up your next ExpressionEngine site.

If you have questions or feedback, we’d love to hear about it in the comments.

This article was updated March 10, 2010.