Autocompletamento

Elementi e stili per la creazione di input con autocompletamento.

Esempio di autocompletamento

Il completamento automatico è un componente che aiuta gli utenti a scegliere le risposte da un elenco fornito. Per la creazione del componente, è stato utilizzato il plugin Accessible autocomplete.

Regione

        
      
        
      

<div class="form-group">
  <label for="accessibleAutocomplete">Regione</label>
  <div id="accessibleAutocompleteWrapper" class="autocomplete-wrapper"></div>
</div>
<script>
  document.addEventListener('DOMContentLoaded', function () {
    const italianRegions = ["Abruzzo","Basilicata","Calabria","Campania","Emilia Romagna","Friuli Venezia Giulia","Lazio","Liguria","Lombardia","Marche","Molise","Piemonte","Puglia","Sardegna","Sicilia","Toscana","Trentino Alto Adige","Umbria","Valle d’Aosta","Veneto"];
    const selectElement = document.querySelector('#accessibleAutocompleteWrapper');
    const selectAutocomplete = new bootstrap.SelectAutocomplete(selectElement, {
      id: 'accessibleAutocomplete',
      name: 'regioni',
      source: italianRegions
    });
  })
</script>

Cambiare i valori dinamicamente

In questo esempio viene mostrato come popolare il componente con dati che cambiano a fronte di un altro input, ad esempio il valore di un altro elemento di un form (come una select nell’esempio che segue). Per far fronte a questa esigenza è sufficiente passare come opzione source una funzione per filtrare i dati e popolare il componente (Tutte le opzioni disponibili del componente).

Categoria alimento

Alimento

        
      
        
      

<div class="row">
  <div class="col-12">
    <div class="form-group">
      <div class="select-wrapper">
        <label for="category">Categoria alimento</label>
        <select id="category" name="category">
          <option value="frutta" selected>Frutta</option>
          <option value="verdura">Verdura</option>
        </select>
      </div>
    </div>
  </div>
  <div class="col-12">
    <div class="form-group">
      <label for="productAutocomplete">Alimento</label>
      <div id="productAutocompleteWrapper" class="autocomplete-wrapper"></div>
    </div>
  </div>
  <script>
    const form_data = {
      'frutta' : [
        'Mela',
        'Pera',
        'Melone',
        'Banana',
      ],
      'verdura' : [
        'Carota',
        'Zucchina',
        'Melanzana',
        'Carciofo',
      ],
    }
    document.addEventListener('DOMContentLoaded', function () {
      const categorySelect = document.getElementById("category");
      const selectWrapperElement = document.getElementById("productAutocompleteWrapper");
      const selectAutocomplete = new bootstrap.SelectAutocomplete(selectWrapperElement, {
        id: 'productAutocomplete',
        name: 'prodotto',
        source: (query, populateResults) => {
          const results = form_data[categorySelect.value]
          const filteredResults = results.filter(
            result => result.toLowerCase() .indexOf(query.toLowerCase()) !== -1
          )
          populateResults(filteredResults)
        }
      });
      // Facoltativo: se si vuole cancellare l'elemento al cambio del filtro
      categorySelect.addEventListener('change', (event) => {
        document.getElementById("productAutocomplete").value = '';
      });
    })
  </script>
</div>

Esempio Regioni e Comuni

Regione

Comune

        
      
        
      

<div class="row">
  <div class="col-12">
    <div class="form-group">
      <div class="select-wrapper">
        <label for="regione">Regione</label>
        <select id="regione" name="regione">
          
          <option value="Abruzzo">Abruzzo</option>
          
          <option value="Basilicata">Basilicata</option>
          
          <option value="Calabria">Calabria</option>
          
          <option value="Campania">Campania</option>
          
          <option value="Emilia Romagna">Emilia Romagna</option>
          
          <option value="Friuli Venezia Giulia">Friuli Venezia Giulia</option>
          
          <option value="Lazio">Lazio</option>
          
          <option value="Liguria">Liguria</option>
          
          <option value="Lombardia">Lombardia</option>
          
          <option value="Marche">Marche</option>
          
          <option value="Molise">Molise</option>
          
          <option value="Piemonte">Piemonte</option>
          
          <option value="Puglia">Puglia</option>
          
          <option value="Sardegna">Sardegna</option>
          
          <option value="Sicilia">Sicilia</option>
          
          <option value="Toscana">Toscana</option>
          
          <option value="Trentino Alto Adige">Trentino Alto Adige</option>
          
          <option value="Umbria">Umbria</option>
          
          <option value="Valle d’Aosta">Valle d’Aosta</option>
          
          <option value="Veneto">Veneto</option>
          
        </select>
      </div>
    </div>
  </div>
  <div class="col-12">
    <div class="form-group">
      <label for="comuniAutocomplete">Comune</label>
      <div id="comuniAutocompleteWrapper" class="autocomplete-wrapper"></div>
    </div>
  </div>
  <script>
    document.addEventListener('DOMContentLoaded', async function () {
      const italianRegions = ["Abruzzo","Basilicata","Calabria","Campania","Emilia Romagna","Friuli Venezia Giulia","Lazio","Liguria","Lombardia","Marche","Molise","Piemonte","Puglia","Sardegna","Sicilia","Toscana","Trentino Alto Adige","Umbria","Valle d’Aosta","Veneto"];
      const data = {}
      italianRegions.forEach(region => { data[region] = [] })
      const comuniJson = await (await fetch('/bootstrap-italia/docs/esempi/form/comuni.json')).json();
      comuniJson.forEach(comune => data[comune.regione].push(comune.comune))
      const regioniSelect = document.getElementById("regione");
      const selectWrapperElement = document.getElementById("comuniAutocompleteWrapper");
      const selectAutocomplete = new bootstrap.SelectAutocomplete(selectWrapperElement, {
        id: 'comuniAutocomplete',
        name: 'comuni',
        source: (query, populateResults) => {
          const results = data[regioniSelect.value]
          const filteredResults = results.filter(
            result => result.toLowerCase() .indexOf(query.toLowerCase()) !== -1
          )          
          populateResults(filteredResults)
        }
      });
      regioniSelect.addEventListener('change', (event) => {
        document.getElementById("comuniAutocomplete").value = '';
      });
    })
  </script>
</div>

Validazione

Per la validazione del campo con autocompletamento, si consiglia di utilizzare il plugin Just Validate come da guida. È possibile testare la validazione del campo con autocompletamento sulla pagina di esempio validazione.

Quando l’utente seleziona un valore dalla tendinda di Autocomplete occorre richiamare nuovamente la funzione di validazione. Questa chiamata può essere effettuata all’interno del metodo onConfirm che viene passato in configurazione e verrà chiamata ogni volta che l’utente seleziona un opzione.

Ad esempio con JustValidate occorrerà istanziare il componente in questo modo

const selectAutocomplete = new SelectAutocomplete(selectAutocompleteWrapper, {
  source: myData,
  id: 'idAutocomplete',
  onConfirm: () => {
    validate.revalidateField('#idAutocomplete')
  }
});

Il campo verrà validato così anche nel caso in cui l’utente seleziona un’opzione. Nel caso in cui è stato impostato che JustValidate validi il form solo dopo la submit occorre controllare il suo stato

  onConfirm: () => {
    if (!validate.isSubmitted && !validate.validateBeforeSubmitting)
      return
    validate.revalidateField('#idAutocomplete')
  }

Nell’esempio seguente si può provare questo comportamento (si noti che tra le configurazioni è stato passato anche minLength: 3, vista la grande mole di dati questa opzione impedirà la visualizzazione dei suggerimenti se vengono digitati meno di 3 caratteri)

        
      
        
      

<div>
  <form id="justValidate">
    <div class="row">
      <div class="col-12">
        <div class="form-group">
          <label for="comuneJVAutocomplete">Comune di residenza</label>
          <div id="comuneJVAutocompleteWrapper" class="autocomplete-wrapper"></div>
        </div>
      </div>
    </div>
    <div class="row">
      <div class="col-12">
        <button class="btn btn-primary mt-3" type="submit" id="submitform">Invia form</button>
      </div>
    </div>
  </form>
  <script>
    document.addEventListener('DOMContentLoaded', async function () {
      const validate = new bootstrap.FormValidate('#justValidate', {
        errorFieldCssClass: 'is-invalid',
        errorLabelCssClass: 'form-feedback',
        errorLabelStyle: '',
        focusInvalidField: false,
      })
      const comuniJson = await (await fetch('/bootstrap-italia/docs/esempi/form/comuni.json')).json();
      const comuni = comuniJson.map(comune => comune.comune)
      const selectAutocompleteWrapper = document.querySelector('#comuneJVAutocompleteWrapper');
      const selectAutocomplete = new bootstrap.SelectAutocomplete(selectAutocompleteWrapper, {
        source: comuni,
        id: 'comuneJVAutocomplete',
        name: 'comuni',
        minLength: 3,
        onConfirm: () => {
          if (!validate.isSubmitted && !validate.validateBeforeSubmitting)
            return
          validate.revalidateField('#comuneJVAutocomplete')
        }
      });
      validate
        .addField('#comuneJVAutocomplete', [
          {
            rule: 'required',
            errorMessage: 'Questo campo è richiesto',
          },
          {
            validator: (value) => {
              return comuni.includes(value);
            },
            errorMessage: 'Scegli una città valida',
          },
        ])
        .onSuccess((event) => {
          // Inserire qua l'azione nel caso di input valido, ad es.
          // document.forms['justValidate'].submit()
        })
      })
  </script>
</div>

Attivazione tramite codice

È possibile abilitare l’autocomplete manualmente utilizzando l’oggetto SelectAutocomplete.

import { SelectAutocomplete } from 'bootstrap-italia';

const autocompleteWrapperElement = document.querySelector('#wrapper-autocomplete');
const autocomplete = new SelectAutocomplete(autocompleteWrapperElement, options);

Opzioni

import { SelectAutocomplete } from 'bootstrap-italia';

const selectAutocompleteWrapper = document.querySelector('#accessibleAutocompleteWrapper');
const selectAutocomplete = new SelectAutocomplete(selectAutocompleteWrapper, {
  source: ['Option 1', 'Option 2', 'Option 3'],
  id: 'accessibleAutocomplete',
  minLength: 3,
  onConfirm: (selectedElement) => {
    console.log(selectedElement);
  }
});

Nome	Tipo	Predefinito	Descrizione
source	Array \| Function	-	Sorgente di dati dell'autocomplete. Se "source è una funzione, gli argomenti sono: (query: string, populateResults: Funzione): "query" è ciò che viene digitato nel campo di input, che richiamerà la funzione "populateResults" in modo sincrono con l'array di risultati da visualizzare nel menu (esempi sopra).
id	string	-	Id dell'elemento input che verrà generato dall' Autocomplete.
name	string	input-autocomplete	Nome del campo di input di completamento automatico, da utilizzare con un form padre.
minLength	number	0	Questa opzione impedisce la visualizzazione dei suggerimenti se vengono digitati meno di N caratteri.
defaultValue	string	-	Valore di default inserito nell'input.
required	boolean	false	Il campo di input verrà renderizzato con un attributo obbligatorio.
onConfirm	function	{}	Questa funzione viene chiamata quando l'utente conferma un'opzione, con l'opzione che ha confermato come argomento (si vedano gli esempi precedenti).

Metodi

Metodo	Descrizione
getInstance	Metodo statico che consente di ottenere l'istanza di avviso associata a un elemento DOM, è possibile utilizzarlo in questo modo: SelectAutocomplete.getInstance(domElement).
getOrCreateInstance	Metodo statico che restituisce un'istanza di avviso associata a un elemento DOM o ne crea una nuova nel caso in cui non fosse stata inizializzata. Puoi utilizzarla in questo modo: SelectAutocomplete.getOrCreateInstance(element).
dispose	Rimuove la funzionalità SelectAutocomplete.

Internazionalizzazione (i18n)

Il componente è internazionalizzabile tramite alcuni parametri della configurazione. La configurazione per Bootstrap Italia è stata settata in italiano. Per maggiori dettagli sulle stringhe che possono essere passate al componente fare riferimento alla guida ufficiale.

Breaking change

Nuova modalità di utilizzo del componente Autocomplete via codice.