Ver índice de contenidos del libro

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.

Nota Algunos usuarios prefieren una sola etiqueta <input> para introducir fechas porque es mucho más rápido que utilizar varias listas desplegables de tipo <select>. Cuando se utiliza un solo <input>, el formato de la fecha se comprueba en el servidor durante el proceso de validación. El validador de fechas del framework Symfony incluye validaciones muy avanzadas que permiten que el usuario introduzca las fechas con formatos muy diferentes.

12.5.1. sfWidgetFormDate

sfWidgetFormDate muestra un widget para seleccionar la fecha:

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:

Opción Descripción
format Cadena de texto con el formato de la fecha (por defecto es %month%/%day%/%year%)
years Array con los años que se muestran en la lista para seleccionar un año (opcional)
months Array con los meses que se muestran en la lista para seleccionar un mes (opcional)
days Array con los días que se muestran en la lista para seleccionar un día (opcional)
can_be_empty Indica si el widget admite fechas vacías (true por defecto)
empty_values Array con los textos que se utilizan para los valores vacíos de las listas desplegables (por defecto se utiliza una cadena de texto vacía para todos los campos)

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%')
);
Widget personalizado para seleccionar la fecha

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:

Widget para seleccionar la 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:

Opción Descripción
format Cadena de texto con el formato de la hora (por defecto es %hour%:%minute%:%second%)
format_without_seconds Cadena de texto con el formato de la hora sin segundos (por defecto es %hour%:%minute%)
with_seconds Indica si se muestra una lista para seleccionar los segundos (false por defecto )
hours Array con las horas que se muestran en la lista para seleccionar una hora (opcional)
minutes Array con los minutos que se muestran en la lista para seleccionar un minuto (opcional)
seconds Array con los segundos que se muestran en la lista para seleccionar los segundos (opcional)
can_be_empty Indica si el widget admite horas vacías (true por defecto)
empty_values Array con los textos que se utilizan para los valores vacíos de las listas desplegables (por defecto se utiliza una cadena de texto vacía para todos los campos)

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%',
));
Widget personalizado para seleccionar la hora

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),
));
Widget para seleccionar la hora con los segundos personalizados

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();
Widget para seleccionar la fecha y la hora

Figura 12.20 Widget para seleccionar la fecha y la hora

Opción Descripción
date Opciones para el widget de la fecha (ver opciones de sfWidgetFormDate)
time Opciones para el widget de la hora (ver opciones de sfWidgetFormTime)
with_time Indica si se muestra el widget de la hora (true por defecto)
format Cadena de texto con el formato de la fecha y hora (por defecto es %date% %time%)

Nota Este widget crea por defecto instancias de sfWidgetFormDate y sfWidgetFormTime para mostrar la fecha y la hora. Si quieres cambiar las clases utilizadas por el widget, puedes redefinir los métodos getDateWidget() y getTimeWidget().

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'));
Widget internacionalizado para seleccionar la fecha

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',
));
Widget internacionalizado para seleccionar la fecha con los meses abreviados

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.

Nota Este widget depende del sub-framework de internacionalización de Symfony.

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'));
Widget internacionalizado para seleccionar la hora

Figura 12.23 Widget internacionalizado para seleccionar la hora

Nota Este widget depende del sub-framework de internacionalización de Symfony.

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.

Nota Este widget depende del sub-framework de internacionalización de Symfony.

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(),
));
Widget para seleccionar un rango de fechas

Figura 12.24 Widget para seleccionar un rango de fechas

Opción Descripción
from_date El widget para la fecha inicial (obligatorio)
to_date El widget para la fecha final (obligatorio)
template La plantilla que se utiliza para mostrar el widget. (la plantilla puede hacer uso de las variables %from_date% y %to_date%

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%',
));
Widget personalizado para seleccionar un rango de fechas

Figura 12.25 Widget personalizado para seleccionar un rango de fechas

Nota Este widget es la clase base de un widget más avanzado llamado sfWidgetFormFilterDate.

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',
));

Nota Este widget es parte del plugin sfFormExtraPlugin. Como los archivos de las librerías JQuery y JQuery UI no se incluyen en sfFormExtraPlugin, debes instalarlos e incluirlos a mano.

Opción Descripción
image La ruta de la imagen que representa el widget (false por defecto)
config Array de JavaScript con la configuración del widget de JQuery
culture La cultura del usuario