I have already talked about sfFormExtraPlugin in some previous posts. Today, I will present this plugin more thoroughly.

What it is?

The sfFormExtraPlugin is a plugin maintained by the symfony core team.

It contains a lot of interesting widgets, validators, and forms that are quite useful but did not make it into the core because they have third-party dependencies or their usage is too specific.

What's inside?

ReCaptcha widget and validator

sfWidgetFormReCaptcha

sfWidgetFormReCaptcha uses ReCaptcha to display a captcha and sfValidatorReCaptcha is the associated validator.

To use them, you need to create an API key on the ReCaptcha website.

The widget takes the ReCaptcha public_key as an option, whereas the validator takes the ReCaptcha private_key:

$this->widgetSchema['captcha'] = new sfWidgetFormReCaptcha(array(
  'public_key' => sfConfig::get('app_recaptcha_public_key')
));
 
$this->validatorSchema['captcha'] = new sfValidatorReCaptcha(array(
  'private_key' => sfConfig::get('app_recaptcha_private_key')
));
 

As it's not possible to change the name of the ReCaptcha fields, you need to add them manually when binding a form from an HTTP request.

Here's a typical usage when embedding a captcha in a form with a contact[%s] name format:

$captcha = array(
  'recaptcha_challenge_field' => $request->getParameter('recaptcha_challenge_field'),
  'recaptcha_response_field'  => $request->getParameter('recaptcha_response_field'),
);
$this->form->bind(array_merge($request->getParameter('contact'), array('captcha' => $captcha)));
 

The following table summarizes all available options for the sfWidgetFormReCaptcha widget:

Option Description
public_key The ReCaptcha public key
use_ssl Whether to use SSL or not (false by default)
server_url The URL for the HTTP API
server_url_ssl The URL for the HTTPS API (when use_ssl is true)

And this one is for sfValidatorReCaptcha:

Option Description
private_key The ReCaptcha private key
remote_addr The remote address of the user
server_host The ReCaptcha server host
server_port The ReCaptcha server port
server_path The ReCatpcha server path
server_timeout The timeout to use when contacting the ReCaptcha server

HTML WYSIWYG editor

sfWidgetFormTextareaTinyMCE

sfWidgetFormTextareaTinyMCE is an HTML WYSIWYG editor based on the popular TinyMCE library.

The JavaScript widget is configured with sensible defaults, but can be changed by using the config option:

$this->widgetSchema['content'] = new sfWidgetFormTextareaTinyMCE(array(
  'width'  => 550,
  'height' => 350,
  'config' => 'theme_advanced_disable: "anchor,image,cleanup,help"',
));
 

The config option must be JavaScript pairs of key/values.

Option Description
theme The Tiny MCE theme (default to advanced)
width The widget width in pixels
height The widget height in pixels
config The JavaScript configuration

Rich date widget

sfWidgetFormJQueryDate

sfWidgetFormJQueryDate represents a rich date widget, based on the JQuery JavaScript library.

As for the TinyMCE widget, it is configured by default with sensible defaults which can be overriden thanks to the config option:

$this->widgetSchema['published_at'] = new sfWidgetFormJQueryDate(array(
  'config' => '{}',
));
 

Here is the widget option list:

Option Description
image The image path to represent the widget (false by default)
config A JavaScript array configuration
culture The culture to use when displaying the widget

Language form

sfFormLanguage

sfFormLanguage is a form that allows users to change their culture. I have already published a post on sfFormLanguage, so I won't describe it again.

Double list widget

sfWidgetFormSelectDoubleList

sfWidgetFormSelectDoubleList is a widget that displays a multiple choices as a double list. This widget has already been explained in a previous post.

The following table describes all available options:

Option Description
choices An array of possible choices
class The main class of the widget
class_select The class for the two select tags
label_unassociated The label for unassociated
label_associated The label for associated
unassociate The HTML for the unassociate link
associate The HTML for the associate link
template The HTML template to use to render this widget
The available placeholders are:
label_associated, label_unassociated,
associate, unassociate,
associated, unassociated,
and class

Autocompleter widget

sfWidgetFormPropelJQueryAutocompleter sfWidgetFormPropelJQueryAutocompleter sfWidgetFormPropelJQueryAutocompleter

sfWidgetFormJQueryAutocompleter is an autocompleter widget based on the JQuery JavaScript library.

sfWidgetFormPropelJQueryAutocompleter extends sfWidgetFormJQueryAutocompleter and associates the widget to a Propel model.

This widget has already been explained in a previous post.

The following table describes all available options:

Option Description
url The URL to call to get the choices to use
config A JavaScript array that configures the JQuery autocompleter widget
value_callback A callback that converts the value before it is displayed

Contribute

sfFormExtraPlugin is still young and more widgets, validators, and forms will be added in the near future, so stay tuned.

If you have developed a specific widget or validator for your project and you want to share it with the symfony community, create a plugin out of it, or contribute it to the sfFormExtraPlugin plugin.

This tutorial is the first post in the brand new plugins category.

If you are the developer of a plugin or the user of a plugin, and want to spread the word about it, write a tutorial (in the markdown format), send it to me, and the best ones will be published on this blog in the coming weeks.

Published in #Plugins #Tutorials