Reviews, ExpressionEngine, Tutorials

Creating a Custom Fieldtype for ExpressionEngine With FieldFrame

March 12, 2009
by Ryan Masuga

FieldFrame is a “framework for rapid development of Fieldtype extensions” for ExpressionEngine. We decided to see exactly what that means by creating a new jQuery Color Picker custom field extension based on FieldFrame, and explain how it was done.

FieldFramePhoto by Sifter via flickr.

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

MD Color PickerMD Color Picker FieldFrame Fieldtype

I googled “jquery color picker field” and compared a few. The first one on the list, ( 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):

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'         => '',
    'versions_xml_url' => ''
  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">
    $(document).ready( function(){
      onSubmit: function(hsb, hex, rgb) {
      onBeforeShow: function () {
     .bind("keyup", function(){
  $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.

FieldFrame Fieldtype File StructureFieldFrame Fieldtype File Structure

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.


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

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


Cody Lundquist 03.12.09

Great article!  I’ve got a couple ideas myself for the catalog and this helps me get those done even faster!  Thanks Ryan :)

Peter 03.12.09

Finally! A few times I wanted to write a color picker extension myself but the benefit over not having to type the hex color code into a texfield was just not greater than the effort to create such an extension. FieldFrame seems to make it much, much easiert.

Nice article, great extension and even a better Framework!

Matt 03.12.09

Awesome— thanks for the great extension!

Richard Angstmann 03.12.09

I am genuinely very excited about this new framework now that I am starting to understand more about it, what it does and I’m even interested in how it works, even though I am no pro coder!

Anything that can make life easier when developing an EE site, and also for the client afterwards can only be a positive thing, and Brandon’s track record speaks for itself. I think this is a winner.

Brad Morse 05.08.09

Brad Morse

Thanks for the great read, definitely helped me understand the possibilities of FF more.

Lee 05.16.09

Great! this got me underway with create a jQuery Date Picker FieldType.

But how is one to allow it to work via the FF Matrix? I am unable to figure this out..  To me, a date picker is only useful to the FF Matrix.

Ryan Masuga 05.18.09

Ryan Masuga

Lee: In order to get your field to work with FF Matrix, you will need to utilize the display_cell function, which is covered in the FieldFrame Wiki at GitHub.

You must be registered member to comment. If you're already a member, log in now, and if not go register (it's free and easy!).