12.5. Widgets para fechas

Los widgets para fechas se pueden utilizar para facilitar la introducción de fechas, ya que utilizan varios elementos para introducir sólo la fecha, sólo la hora o la fecha y hora. Todos los widgets de fechas se representan mediante varias etiquetas HTML. Además estos widgets se pueden personalizar en función de la cultura del usuario.

12.5.1. sfWidgetFormDate

sfWidgetFormDate muestra un widget para seleccionar la fecha:

Figura 12.15 Widget para seleccionar la fecha

Los valores enviados por el usuario se guardan en un array con el mismo nombre que el widget:

$w = new sfWidgetFormDate();
$w->render('fecha');

# los valores enviados por el usuario se encuentran en
# un array llamado "fecha"
# array(
#   'fecha' => array(
#     'day'   => 15,
#     'month' => 10,
#     'year'  => 2005,
#   ),
# );

El comportamiento del widget se puede personalizar mediante las siguientes opciones:

La opción format permite modificar la distribución por defecto de las etiquetas (al mostrar el widget, las variables %year%, %month% y %day% se sustituyen por sus correspondientes etiquetas <select>):

$w = new sfWidgetFormDate(
  array('format' => '%year% - %month% - %day%')
);

Figura 12.16 Widget personalizado para seleccionar la fecha

La etiqueta <select> de los años (year) muestra por defecto los diez años alrededor del año actual. La opción years permite modificar este comportamiento:

$years = range(2009, 2020);
$w = new sfWidgetFormDate(
  array('years' => array_combine($years, $years))
);

Las opciones years, months y days toman como argumento un array cuyas claves son los valores de las etiquetas <option> y cuyos valores son las cadenas de texto que se muestran al usuario.

12.5.2. sfWidgetFormTime

sfWidgetFormTime muestra un widget para seleccionar una hora:

Figura 12.17 Widget para seleccionar la hora

Los valores enviados por el usuario se guardan en un array con el mismo nombre que el widget:

$w = new sfWidgetFormTime();
$w->render('hora');

# los valores enviados por el usuario se encuentran en
# un array llamado "hora"
# array(
#   'hora' => array(
#     'hour'    => 12,
#     'minute'  => 13,
#     'second'  => 14,
#   ),
# );

El comportamiento del widget se puede personalizar mediante las siguientes opciones:

Por defecto este widget no permite elegir los segundos de la hora, pero este comportamiento se puede modificar estableciendo la opción with_seconds a true:

$w = new sfWidgetFormTime(array('with_seconds' => true));

Las opciones format y format_without_seconds permiten modificar la distribución por defecto de las etiquetas (al mostrar el widget, las variables %hour%, %minute% y %second% se sustituyen por sus correspondientes etiquetas <select>):

$w = new sfWidgetFormTime(array(
  'with_seconds' => true,
  'format'       => '%hour% : %minute% : %second%',
));

Figura 12.18 Widget personalizado para seleccionar la hora

Si no quieres que el usuario pueda elegir cualquier valor de las listas desplegables, puedes indicar los valores seleccionables para cada lista:

$segundos = array(0, 15, 30, 45);
$w = new sfWidgetFormTime(array(
  'with_seconds' => true,
  'seconds'      => array_combine($segundos, $segundos),
));

Figura 12.19 Widget para seleccionar la hora con los segundos personalizados

Las opciones hours, minutes y seconds toman como argumento un array cuyas claves son los valores de las etiquetas <option> y cuyos valores son las cadenas de texto que se muestran al usuario.

12.5.3. sfWidgetFormDateTime

sfWidgetFormDateTime es un widget especial que muestra dos sub-widgets: un widget de tipo sfWidgetFormDate y otro widget de tipo sfWidgetFormTime:

$w = new sfWidgetFormDateTime();

Figura 12.20 Widget para seleccionar la fecha y la hora

12.5.4. sfWidgetFormI18nDate

sfWidgetFormI18nDate extiende el widget sfWidgetFormDate. Mientras que el widget estándar muestra los meses como números, este widget muestra los meses como cadenas de texto y traducidas en función de la cultura del usuario:

$w = new sfWidgetFormI18nDate(array('culture' => 'fr'));

Figura 12.21 Widget internacionalizado para seleccionar la fecha

El formato de los meses se puede configurar mediante la opción month_format, que acepta los siguientes tres valores: name (valor por defecto, que muestra el nombre completo del mes), short_name (abreviatura del nombre del mes) o number (número del mes).

$w = new sfWidgetFormI18nDate(array(
  'culture'      => 'fr',
  'month_format' => 'short_name',
));

Figura 12.22 Widget internacionalizado para seleccionar la fecha con los meses abreviados

El widget también tiene en cuenta la cultura del usuario en el orden en el que se muestran las tres listas desplegables y en el separador utilizado entre ellas.

12.5.5. sfWidgetFormI18nTime

sfWidgetFormI18nTime extiende el widget sfWidgetFormTime estándar. En función de la cultura que se le pasa como opción culture, el widget determina el orden en el que se muestran las tres listas desplegables y el separador utilizado entre ellas.

$w = new sfWidgetFormI18nTime(array('culture' => 'ar'));

Figura 12.23 Widget internacionalizado para seleccionar la hora

12.5.6. sfWidgetFormI18nDateTime

sfWidgetFormI18nDateTime es un widget especial que muestra dos sub-widgets: un widget de tipo sfWidgetFormI18nDate y otro widget de tipo sfWidgetFormI18nTime.

12.5.7. sfWidgetFormDataRange

sfWidgetFormDateRange es un widget que permite seleccionar un rango de fechas:

$w = new sfWidgetFormDateRange(array(
  'from_date' => new sfWidgetFormDate(),
  'to_date'   => new sfWidgetFormDate(),
));

Figura 12.24 Widget para seleccionar un rango de fechas

La opción template se puede emplear para modificar la plantilla que utiliza el wdiget para mostrar sus contenidos:

$w = new sfWidgetFormDateRange(array(
  'from_date' => new sfWidgetFormDate(),
  'to_date'   => new sfWidgetFormDate(),
  'template'  => 'Begin at: %from_date%<br />End at: %to_date%',
));

Figura 12.25 Widget personalizado para seleccionar un rango de fechas

12.5.8. sfWidgetFormJQueryDate

sfWidgetFormJQueryDate utiliza la librería JQuery UI para mostrar un widget que permite seleccionar una fecha:

$w = new sfWidgetFormJQueryDate(array(
  'culture' => 'en',
));