desy-angular v11.1 - Manual de integración DesyFormsModule

desy-angular v11.1 - Manual de integración DesyFormsModule

Componentes relativos a formularios


Los componentes que el usuario pueda introducir un valor, podra ser implementado con:

  • En formularios manejados por plantillas (Template-driven Forms), vinculando el dato mediante ngModel.

  • En formularios reactivos (Reactive Forms), indicando el nombre del control mediante el atributo formControlName.

Vamos a ver como se usa cada uno de los componentes.

 

Character count


<desy-character-count ... ></desy-character-count>

Permite representar una entrada de texto largo con límite de caracteres o palabras, indicando la cantidad restante.

 

Propiedad

Tipo

Descripción

Obligatorio

Propiedad

Tipo

Descripción

Obligatorio

id

string

Identificador del textarea.

Si

name

string

Nombre o atributo name del textarea.

Si

maxlength

number

Número máximo de caracteres.

Sí, cuando no se especifica maxwords.

countbbdd

boolean

Indica si se debe limitar el texto a introducir teniendo en cuenta el peso que pueden tener los caracteres especiales en base de datos.

 

maxwords

number

Número máximo de palabras. Sólo se aplica si no se ha especificado la propiedad maxlength.

Sí, cuando no se especifica maxlength.

threshold

number

Umbral de texto introducido a partir del cual se mostrará el texto con los caracteres/palabras restantes. Si no se especifica, este texto se mostrará siempre.

 

placeholder

string

Texto a mostrar de ejemplo antes de introducir texto.

 

labelText

string

Título o etiqueta. Puede especificarse utilizando una de las siguientes opciones:

  • labelText: texto de título.

  • labelDataobjeto que contiene toda la información de un componente Label.

  • labelRef: tag de un ng-template que contenga un componente Label.

Si se especifican varias, se aplicará la opción que admite mayor personalización: labelRef → labelData → labelText.

Si

labelData

LabelData

labelRef

TemplateRef <LabelComponent>

hintText

string

Descripción de ayuda. Puede especificarse utilizando una de las siguientes opciones:

  • hintText: texto de ayuda.

  • hintDataobjeto que contiene toda la información de un componente Hint.

  • hintRef: tag de un ng-template que contenga un componente Hint.

Si se especifican varias, se aplicará la opción que admite mayor personalización: hintRef → hintData → hintText.

 

hintData

HintData

 

hintRef

TemplateRef <LabelComponent>

 

errorMessageText

string

Mensaje de error. Puede especificarse utilizando una de las siguientes opciones:

  • errorMessageText: texto del mensaje de error.

  • errorMessageDataobjeto que contiene toda la información de un componente errorMessage.

  • errorMessageRef: tag de un ng-template que contenga un componente errorMessage.

Si se especifican varias, se aplicará la opción que admite mayor personalización: errorMessageRef → errorMessageData → errorMessageText.

 

errorMessageData

ErrorMessageData

 

errorMessageRef

TemplateRef <ErrorMessageComponent>

 

classes

string

Clases a aplicar sobre la entrada de texto.

 

formGroupClasses

string

Clases del grupo que contiene el título, la descripción, el mensaje de error y la entrada de texto.

 

countMessageClasses

string

Clases a aplicar sobre el texto con los caracteres/palabras restantes.

 

disabled

booelean

Permite deshabilitar el componente.

Nota: si se utilizan formularios reactivos, es preferible no utilizar este parámetro y gestionarlo desde el FormControl.

 

Propiedades de accesibilidad

El componente admite los parámetros de accesibilidad.

Ejemplo básico, utilizando ngModel

@Component({ selector: '...', templateUrl: '...', ... }) export class DemoCharacterCountComponent { ... value: string; ... } <desy-character-count id="id" [(ngModel)]="value" classes="w-100" labelText="Título" hintText="Introduce un texto largo." errorMessageText="El texto introducido es inválido" [countbbdd]="true" [maxlength]="100" [threshold]="75"></desy-character-count>

Ejemplo completo, utilizando formControlName

Componente
@Component({ selector: '...', templateUrl: '...', ... }) export class DemoCharacterCountComponent { ... form: FormGroup = new FormGroup({ valueFormControl: new FormControl('', [Validators.required]) }); ... }
HTML utilizando labelText, hintText y errorMessageText
<desy-character-count id="identificador" classes="w-100" formControlName="valueFormControl" [maxwords]="15" labelText="Título" hintText="Introduce un texto largo (15 palabras como máximo)." [errorMessageText]="!form.valid ? 'Soy obligatorio' : null"></desy-character-count>
HTML utilizando labelData, hintData y errorMessageData
<desy-character-count id="identificador" classes="w-100" formControlName="valueFormControl" [maxwords]="15" labelData="{text: 'Título', ...}" hintText="{text: 'Introduce un texto largo (15 palabras como máximo).', ...}" [errorMessageData]="!form.valid ? {text: 'Soy obligatorio'} : null"></desy-character-count>
HTML utilizando labelRef, hintRef y errorMessageRef
<desy-character-count labelRef="labelTemplate" hintRef="hintTemplate" errorMessageRef="errorMessageTemplate" [maxwords]="15"> <ng-template #labelTemplate> <desy-label text='Título' ...></desy-label> </ng-template> <ng-template #hintTemplate> <desy-hint text='Introduce un texto largo (15 palabras como máximo).' ...></desy-hint> </ng-template> <ng-template #errorMessageTemplate> <desy-error-message [text]="!form.valid ? {text: 'Soy obligatorio'} : null" ...></desy-error-message> </ng-template> </desy-character-count>

 

Checkboxes


<desy-checkboxes ... >...</desy-checkboxes>

Permite representar un listado de checkboxes.

 

Propiedad

Tipo

Descripción

Obligatorio

Propiedad

Tipo

Descripción

Obligatorio

idPrefix

string

Prefijo para identificar los ítems, si no vienen identificados. Si no se especifica se usa name.

 

name

string

Atributo name de cada checkbox item.

si

classes

string

Clases CSS separadas por espacio que se aplicarán sobre el componente.

 

formGroupClasses

string

Clases CSS separadas por espacio que se aplicarán sobre el form group.

 

hasDividers

boolean

Determinar si se muestran lineas divesoras entre los items.

 

items

ItemCheckboxData[]

Objeto con la información de cada checkbox item. Admite double binding, ya que internamente se puede modificar el valor de checked.

si

fieldsetData

FieldsetData

Fieldset con legend. Puede especificarse utilizando una de las siguientes opciones:

  • Componente Fieldset como contenido (ver sección contenido).

  • fieldsetData: Objeto que contiene toda la información del componente Fieldset

  • legendRef: tag de un ng-template que contenga un componente legend

  • legendData: objeto que contiene toda la informaicón del componente legend

  • legendText: tengo de la legenda

Si se especifican varias, se aplicará la opción que admite mayor personalización: 

fieldsetComponent → fieldsetData legendRef→ legendData→ legendText.

 

legendRef

TemplateRef <LegendComponent>

 

legendData

LegendData

 

legendText

string

 

hintText

string

Descripción de ayuda. Puede especificarse utilizando una de las siguientes opciones:

  • Componente Hint como contenido (ver sección contenido).

  • hintText: texto de ayuda.

  • hintDataobjeto que contiene toda la información de un componente hint.

  • hintRef: tag de un ng-template que contenga un componente hint.

Si se especifican varias, se aplicará la opción que admite mayor personalización: 

hintComponent → hintRef → hintData → hintText.

 

hintData

HintData

 

hintRef

TemplateRef <LabelComponent>

 

errorMessageText

string

Mensaje de error. Puede especificarse utilizando una de las siguientes opciones:

  • Componente ErrorMessage como contenido (ver sección contenido).

  • errorMessageText: texto del mensaje de error.

  • errorMessageDataobjeto que contiene toda la información de un componente errorMessage.

  • errorMessageRef: tag de un ng-template que contenga un componente errorMessage.

Si se especifican varias, se aplicará la opción que admite mayor personalización: 

errorMessageComponent → errorMessageRef → errorMessageData → errorMessageText.

 

errorMessageData

ErrorMessageData

 

errorMessageRef

TemplateRef <ErrorMessageComponent>

 

 ItemCheckboxData

Propiedad

Tipo

Descripción

Obligatorio

Propiedad

Tipo

Descripción

Obligatorio

text

string

Contenido del texto de ayuda en formato texto plano. No se aplicará cuando se especifique la propiedad html.

Si, cuando no se especifica html.

html

string

Contenido del texto en formato HTML.

Si, cuando no se especifica text.

id

string

Identificador del ítem.

 

value

string

Valor del ítem.

si

labelData

LabelData

Objeto que contiene toda información del componente label. Solo se aplicarán los atributos y clases css.

 

hintText

string

Descripción de ayuda. Puede especificarse utilizando una de las siguientes opciones:

  • hintText: texto de ayuda.

  • hintDataobjeto que contiene toda la información de un componente hint.

Si se especifican varias, se aplicará la opción que admite mayor personalización:  hintData → hintText.

 

hintData

HintData

 

classes

string

Clases CSS separadas por espacio que se aplicarán sobre el ítem.

 

checked

boolean

Determina si está marcado.

 

disabled

boolean

Determina si está activo

 

isIndeterminated

boolean

Indica si admite un estado visual intermedio que no corresponde ni a marcado ni a desmarcado. Se suele utilizar cuando existen otros campos de tipo checkbox dependientes del ítem y se quiere representar que se han marcado sólo algunos de ellos.

 

conditional

boolean

Determina si tiene una condición.

Para implementar la template a mostrar, se usa la directiva Condition

 

Propiedades de accesibilidad

El componente e ItemCheckboxData admite los siguientes parámetros de accesibilidad.

 

Se permite proyectar contenido dentro de checkboxes para facilitar su uso. Admite los siguientes componentes:

FieldsetComponent

<desy-fieldset>...</desy-fieldset>

Permite especificar las propiedades del fieldset. No se debe especificar el caller de este componente, ya que se sobrescribirá internamente.

LegendComponent

<desy-legend>...</desy-legend>

Si no se especifica el componente fieldset, se puede utilizar para incorporar el título.

HintComponent

<desy-hint>...</desy-hint>

Permite especificar la descripción de ayuda. Se ignorará el parámetro id, ya que se sobrescribirá internamente.

ErrorMessageComponent

<desy-error-message>...</desy-error-message>

Permite especificar el mensaje de error. Se ignorará el parámetro id, ya que se sobrescribirá internamente.

CheckboxItemComponent

<desy-checkbox-item ...>...</desy-checkbox-item>

Permite especificar cada checkbox. Admite los mismos parámetros que ItemCheckboxData. El parámetro checked admite double-binding.

A su vez, este componente admite como contenido los componentes LabelComponent, HintComponent y ContentComponent. Este último permite especificar el contenido condicional que se mostrará al seleccionar el checkbox, siempre y cuando se especifice el parámetro conditional a true.

Si no se especifica el LabelComponent, el contenido (salvo los componentes HintContent y ContentComponent, si se especifican) será insertado dentro de un label de forma interna.

Evento

Tipo

Descripción

Evento

Tipo

Descripción

itemsChange

ItemCheckboxData[]

Se emite cada vez que se selecciona o deselecciona un checkbox, de forma que el valor de checked de cada item se devuelve actualizado en el evento.

Sólo se emite si se especifican los items como parámetro.

Ejemplo con contenido y NgModel

Componente
@Component({ selector: '...', templateUrl: '...', ... }) export class DemoCheckboxesComponent { ... value: string; ... }
HTML
<desy-checkboxes [(ngModel)]="valueContent" [idPrefix]="'example-content'" [name]="'checkboxNgModel'" [classes]="'flex'"> <desy-fieldset [legendText]="'Ejemplo con contenido'"></desy-fieldset> <desy-hint>Selecciona una o varias opciones</desy-hint> <desy-error-message *ngIf="!valueContent || valueContent.length === 0">Debes seleccionar al menos una opción</desy-error-message> <desy-checkbox-item [value]="'opcion1'" [conditional]="true"> <desy-label>Opción 1</desy-label> <desy-hint>Tiene contenido condicional</desy-hint> <desy-content>Contenido condicional</desy-content> </desy-checkbox-item> <desy-checkbox-item [value]="'opcion2'"> Opcion 2 <desy-hint>No se especifica label</desy-hint> </desy-checkbox-item> </desy-checkboxes>

 

Ejemplo con parámetros y NgModel

Componente
@Component({ selector: '...', templateUrl: '...', ... }) export class DemoCheckboxesComponent { ... value: string; ... }
HTML
<desy-checkboxes [(ngModel)]="value" idPrefix="example" name="checkboxNgModel" [items]="[{'value': 'british', 'text': 'British'}, {'value': 'irish', 'text': 'Irish'}, {'value': 'other', 'text': 'Citizen of another country'}]" legendText="What is your nationality?" hintText="If you have dual nationality, select all options that are relevant to you."></desy-checkboxes>

 

 

Ejemplo con Formulario y condicionales
Ver apartado ConditionDirective

 

 

 

Date-input


<desy-date-input ... ></desy-date-input>

Permite introducir una fecha como un grupo de campos.

Puede ser utilizado:

  • En formularios manejados por plantillas (Template-driven Forms), vinculando el dato mediante ngModelGroup.

  • En formularios reactivos (Reactive Forms), indicando el nombre del control mediante el atributo formControlName.

  • Independientemente, vinculando el dato mediante ngModel.

Propiedad

Tipo

Descripción

Obligatorio

Propiedad

Tipo

Descripción

Obligatorio

id

string

Identificador del grupo

disabled

boolean

Indica si el item está deshabilitado

 

namePrefix

string

Prefijo común a todos los ítems. Si no se especifica se usa name.

Nota: Si se utiliza en un formulario manejado por plantilla y se modifica este valor tras inicializarse, no se verá reflejado.

 

classes

string

Clases CSS separadas por espacio que se aplicarán sobre el componente.

 

formGroupClasses

string

Clases CSS separadas por espacio que se aplicarán sobre el form group.

 

items

ItemDateInputData[]

Objeto con la información de cada date item.

si

fieldsetData

FieldsetData

Fieldset con legend. Puede especificarse utilizando una de las siguientes opciones:

  • fieldsetData: Objeto que contiene toda la información del componente Fieldset

  • legendRef: tag de un ng-template que contenga un componente legend

  • legendData: objeto que contiene toda la informaicón del componente legend

  • legendText: tengo de la legenda

Si se especifican varias, se aplicará la opción que admite mayor personalización: fieldsetData legendRef→ legendData→ legendText.

 

legendRef

TemplateRef <LegendComponent>

 

legendData

LegendData

 

legendText

string

 

hintText

string

Descripción de ayuda. Puede especificarse utilizando una de las siguientes opciones:

  • hintText: texto de ayuda.

  • hintDataobjeto que contiene toda la información de un componente hint.

  • hintRef: tag de un ng-template que contenga un componente hint.

Si se especifican varias, se aplicará la opción que admite mayor personalización: hintRef → hintData → hintText.

 

hintData

HintData

 

hintRef

TemplateRef <LabelComponent>

 

errorMessageText

string

Mensaje de error. Puede especificarse utilizando una de las siguientes opciones:

  • errorMessageText: texto del mensaje de error.

  • errorMessageDataobjeto que contiene toda la información de un componente errorMessage.

  • errorMessageRef: tag de un ng-template que contenga un componente errorMessage.

Si se especifican varias, se aplicará la opción que admite mayor personalización: errorMessageRef → errorMessageData → errorMessageText.

 

errorMessageData

ErrorMessageData

 

errorMessageRef

TemplateRef <ErrorMessageComponent>

 

placeholder

String

Placeholder. Introducir como un string de tipo 'DD/MM/YYYY'

 

 ItemDateInputData

Propiedad

Tipo

Descripción

Obligatorio

Propiedad

Tipo

Descripción

Obligatorio

id

string

Identificador del ítem.

 

name

string

Nombre del ítem.

Nota: Si se utiliza en un formulario manejado por plantilla y se modifica este valor tras inicializarse, no se verá reflejado.

value

string

Valor del ítem.

 

labelData

LabelData

Objeto que contiene toda información del componente label. Solo se aplicarán los atributos y clases css.

labelText

string

Valor de la leyenda

 

disabled

boolean

Indica si está habilitado

 

classes

string

Clases CSS separadas por espacio que se aplicarán sobre el ítem.

 

divider

ItemDividerDateInputData

Indica el divisor entre componentes. Puede ser html o texto

 

maxLenght

number

Número maximo de caracteres

 

autocomplete

string

Atributo autocomplete.

 

pattern

string

Patrón que deberá cumplir el valor para considerarse válido.

 

hasErrors

boolean

Permite indicar externamente si el campo tiene un error.

 

placeholder

string

Placeholder.

 

Propiedades de accesibilidad

El componente e ItemDateInputData admite los siguientes parámetros de accesibilidad.

 

Se permite proyectar contenido dentro del date-input para facilitar su uso. Para ello se facilitan los siguientes sub-componentes:

LegendComponent

<desy-legend>...</desy-legend>

Si no se especifica el componente fieldset, se puede utilizar para incorporar el título.

HintComponent

<desy-hint>...</desy-hint>

Permite indicar un texto de ayuda en el componente

Este componente se encuentra en el módulo DesyFormsModule.

ErrorMessageComponent

<desy-error-message>...</desy-error-message>

Permite indicar un mensaje de error en el componente

Este componente se encuentra en el módulo DesyFormsModule.

DateInputDayComponent

<desy-input-day>...</desy-input-day>

Permite indicar un día en el componente. Admite los mismos parámetros de entrada que el objeto ItemDateInputData, a excepción de labelData.

Se debe incorporar un componente label como contenido para especificar el título.

DateInputMonthComponent

<desy-input-month>...</desy-input-month>

Permite indicar un mes en el componente. Admite los mismos parámetros de entrada que el objeto ItemDateInputData, a excepción de labelData.

Se debe incorporar un componente label como contenido para especificar el título.

DateInputYearComponent

<desy-input-year>...</desy-input-year>

Permite indicar un año en el componente. Admite los mismos parámetros de entrada que el objeto ItemDateInputData, a excepción de labelData.

Se debe incorporar un componente label como contenido para especificar el título.

Ejemplo con contenido y ngModel

 

<desy-date-input id="withNgModelAndContent" [(ngModel)]="value"> <desy-legend>Fecha de nacimiento</desy-legend> <desy-hint>Por ejemplo, 31 3 1980</desy-hint> <desy-error-message>Debes rellenar todos los campos</desy-error-message> <desy-input-day [name]="'day'" [classes]="'w-14'" [maxlength]="2"> <desy-label>Día</desy-label> </desy-input-day> <desy-input-month [name]="'month'" [classes]="'w-14'" [maxlength]="2"> <desy-label>Mes</desy-label> </desy-input-month> <desy-input-year [name]="'year'" [classes]="'w-20'" [maxlength]="4"> <desy-label>Año</desy-label> </desy-input-year> </desy-date-input>

 

Ejemplos con NgModel y Template Driven

 

Componente
@Component({ selector: '...', templateUrl: '...', ... }) export class DemoDateInputComponent { ... value: string; ... }
HTML con campo independiente
<desy-date-input id="withNgModel" [(ngModel)]="value" legendText="Fecha de nacimiento" hintText="Por ejemplo, 31 3 1980"></desy-date-input>
HTML con campo utilizado en un formulario dirigido por plantilla
<form class="form" #tdForm="ngForm"> <desy-date-input id="tdDate" ngModelGroup="tdDate" legendText="Fecha de nacimiento" hintText="Por ejemplo, 31 3 1980"></desy-date-input> </form>

 

Ejemplo con Reactive form

 

Componente
@Component({ selector: '...', templateUrl: '...', ... }) export class DemoDateInputComponent { ... form = new FormGroup({ date: new FormGroup({ day: new FormControl(), month: new FormControl(), year: new FormControl() }) }); ... }
HTML
<form class="form" [formGroup]="form"> <desy-date-input id="withReactiveForm" [items]="formItems" formGroupName="date" legendText="Fecha de nacimiento" hintText="Por ejemplo, 31 3 1980" errorMessageText="El año es obligatorio" [items]="[{name: 'day', classes: 'w-14', maxlength: 2}, {name: 'month', classes: 'w-14', maxlength: 2}, {name: 'year', classes: 'w-20', maxlength: 4, hasErrors: true}]"></desy-date-input> </form>

Error Message


<desy-error-message ... ></desy-error-message>

Permite representar un texto de error.

Propiedad

Tipo

Propiedad

Tipo