10.7. Widget y validadores propios (Symfony 1.4, la guía definitiva)

Si quieres crear tus propios widgets, sólo tienes que definir una clase que herede de sfWidgetForm y que incluya los métodos configure() y render(). Como siempre, la mejor forma de entender cómo funcionan los widgets consiste en estudiar el código fuente de los widgets existentes. A continuación se muestra el código del widget sfWidgetFormInput para ilustrar su funcionamiento:

class sfWidgetFormInputText extends sfWidgetForm
{
  /**
   * Configures the current widget.
   * This method allows each widget to add options or HTML attributes during widget creation.
   * Available options:
   *  * type: The widget type (text by default)
   *
   * @param array $options     An array of options
   * @param array $attributes  An array of default HTML attributes
   * @see sfWidgetForm
   */
  protected function configure($options = array(), $attributes = array())
  {
    $this->addOption('type', 'text');
    $this->setOption('is_hidden', false);
  }

  /**
   * Renders the widget as HTML
   *
   * @param  string $name        The element name
   * @param  string $value       The value displayed in this widget
   * @param  array  $attributes  An array of HTML attributes to be merged with the default HTML attributes
   * @param  array  $errors      An array of errors for the field
   * @return string An HTML tag string
   * @see sfWidgetForm
   */
  public function render($name, $value = null, $attributes = array(), $errors = array())
  {
    return $this->renderTag('input', array_merge(
      array('type' => $this->getOption('type'), 'name' => $name, 'value' => $value),
      $attributes
    ));
  }
}

De forma similar, los validadores propios se crean mediante clases que hereden de sfValidatorBase y que definan los métodos configure() y doClean(). ¿Por qué se llama doClean() en vez de validate()? Porque los validadores hacen dos cosas: comprueban que los datos cumplen las reglas establecidas y, opcionalmente, limpian los datos (por ejemplo forzando a que el dato sea de un determinado tipo, eliminando los espacios en blanco, convirtiendo fechas en timestamps, etc.) Por tanto, el método doClean() debe devolver el dato limpio o lanzar una excepción de tipo sfValidatorError si los datos del usuario no cumplen alguna de las reglas de validación. A continuación es muestra el código sfValidatorInteger para ilustrar todo lo anterior.

class sfValidatorInteger extends sfValidatorBase
{
  /**
   * Configures the current validator.
   * This method allows each validator to add options and error messages during validator creation.
   * Available options:
   *  * max: The maximum value allowed
   *  * min: The minimum value allowed
   * Available error codes:
   *  * max
   *  * min
   *
   * @param array $options   An array of options
   * @param array $messages  An array of error messages
   * @see sfValidatorBase
   */
  protected function configure($options = array(), $messages = array())
  {
    $this->addOption('min');
    $this->addOption('max');
    $this->addMessage('max', '"%value%" must be less than %max%.');
    $this->addMessage('min', '"%value%" must be greater than %min%.');
    $this->setMessage('invalid', '"%value%" is not an integer.');
  }

  /**
   * Cleans the input value.
   *
   * @param  mixed $value  The input value
   * @return mixed The cleaned value
   * @throws sfValidatorError
   */
  protected function doClean($value)
  {
    $clean = intval($value);
    if (strval($clean) != $value)
    {
      throw new sfValidatorError($this, 'invalid', array('value' => $value));
    }
    if ($this->hasOption('max') && $clean > $this->getOption('max'))
    {
      throw new sfValidatorError($this, 'max', array('value' => $value, 'max' => $this->getOption('max')));
    }
    if ($this->hasOption('min') && $clean < $this->getOption('min'))
    {
      throw new sfValidatorError($this, 'min', array('value' => $value, 'min' => $this->getOption('min')));
    }

    return $clean;
  }
}

La documentación de la API de Symfony incluye todos los detalles sobre la sintaxis empleada por los widgets y los validadores.

Utiliza opciones para pasar parámetros a las clases de formularios Una de las necesidades habituales en los formularios es el uso de parámetros de la aplicación, como por ejemplo el idioma o cultura del usuario. La forma más rápida (y mala) de hacerlo sería instanciar sfContext para obtener el objeto del usuario mediante sfContext::getInstance()->getUser(). El problema es que esa instrucción crea un código fuertemente acoplado entre el formulario y el contexto, lo que dificulta las pruebas unitarias y la reutilización del código. La única solución correcta consiste en pasar al formulario la cultura del usuario como opción:

// en la acción
public function executeContacto(sfWebRequest $request)
{
  $this->form = new ContactForm(array(), array('culture' => $this->getUser()->getCulture()));
}

// en la prueba unitaria
$form = new ContactoForm(array(), array('culture' => 'en'));

// la clase del formulario
class ContactoForm extends sfForm
{
  public function configure()
  {
    ...

    $this->setWidget('pais', new sfWidgetFormI18NCountry(array('culture' => $this->getOption('culture'))));

    ...
  }
}