desy-angular v11.1 - Manual de integración DesyFormsModule
- 1 Componentes relativos a formularios
- 1.1 Character count
- 1.2 Checkboxes
- 1.3 Date-input
- 1.4 Error Message
- 1.5 FieldSet
- 1.6 File Upload
- 1.7 Hint
- 1.8 Input
- 1.9 Input-group
- 1.10 Label
- 1.11 Legend
- 1.12 Radios
- 1.13 SearchBar
- 1.14 Select
- 1.15 Textarea
- 1.16 Tree
- 1.17 Accesibilidad
- 2 Uso de los directivas de los formularios
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:
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:
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:
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:
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:
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:
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:
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 | Sí |
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:
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:
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:
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. | Sí |
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. | Sí |
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 |
---|