MB_PseudoForm

MB_PseudoForm consente di organizzare degli elementi input, select e textarea compilabili dall'utente in un contenitore (tipicamente un elemento div) e di inviare dati inseriti dall'utente ad un server per l'elaborazione utilizzando un "Ajax Request".

MB_PseudoForm può essere utile:

In tutte le situazioni in cui desidero inviare l'input dell'utente al server senza scaricare la pagina.
In particolare se voglio creare dei moduli di immissione in applicazioni .net di tipo WebForm senza utilizzare il form principale (vedi l'esempio nella cartella demo)

MB_PseudoForm invia i dati sotto forma di lista di oggetti. Questo consente di costruire lato server handlers generici, indipendenti dalla struttura del modulo di input da elaborare. Ad esempio, il demo allegato è una applicazione WebForm dove un API controller trasforma un qualsiasi gruppo di dati compilati dall'utente in una email formattata che viene inviata allo staff del sito.

Getting started

È possibile caricare MB_PseudoForm direttamente da CDN

<script src="https://cdn.jsdelivr.net/npm/@magicbruno/mb_pseudoform@1.0.0/dist/MB_PseudoForm.min.js"></script>

o installato con NPM

npm install @magicbruno/mb_pseudoform@1.0.0

o clonare il repository da Github:

git clone https://github.com/magicbruno/MB_PseudoForm.git

Come funziona

Uno pseudo form è un elemento HTML (per esempio un elemento div) che contiene degli elementi input, select e textarea e almeno un elemento cliccabile (<button> o <a>) che ha la funzione di inviare i dati.

Condizioni minime perché un elemento HTML diventi uno pseudo form sono:

Che sia definito l'handler destinato a ricevere i dati lato server utilizzando l'attributo data-mb-action da applicare all'elemento stesso
Che l'elemento contenga un submit button definito assegnando ad un elemento <button> o a un elemento <a> l'attributo data-mb-toggle="submit".

<div id="sample1-en" data-mb-action="api/PseudoForm">
  <!-- Campi di input -->
  <button type="button" data-mb-toggle="submit">Invia dati</button>
</div>

Attivazione

Si può attivare lo pseudo form via Javascript (pForm può essere indifferentemente un selettore CSS o un elemento HTML)

const myPseudoForm = new MB_PseudoForm(pForm) ;

o semplicemente assegnando all'elemento l'attributo data-mb-ride="pseudo-form".

<div id="sample1-en" data-mb-action="api/PseudoForm" data-mb-ride="pseudo-form">
  <!-- Campi di input -->
  <button type="button" data-mb-toggle="submit">Invia dati</button>
</div>

Proprietà e metodi

Può essere utile illustrare alcune caratteristiche base del funzionamento dello pseudo form. Per maggiori dettagli consigliamo di esaminare direttamente il codice che è scritto in modo molto chiaro e ampiamente commentato.

MB_PseudoForm si basa sul funzionamento di tre classi Javascript:

MB_PseudoForm, la classe principale
MB_PseudoFormValue che definisce l'oggetto in cui vengono trasformati i campi compilati dell'utente per l'invio al server
ValuesList che fornisce alcuni metodi per gestire una lista di MB_PseudoFormValue

MB_PseudoFormValue

MB_PseudoFormValue espone 5 proprietà che riflettono caratteristiche e valore dei campi compilati dall'utente.

Proprietà	Tipo	Descrizione
`Name`	`string`	Riflette il contenuto dell'attributo `name` dell'elemento. Nel caso l'attributo `name` non sia presente, viene usato l'`id` dell'elemento.
`Type`	`string`	Riflette il contenuto della proprietà `type` dell'elemento.
`Value`	`any`	Se l'elemento è una `checkbox` è `true` se selezionata, altrimenti `false`. Se l'elemento è un `input` di tipo `file` restituisce il contenuto del file codificato come DataUrlBase64. Negli altri casi riflette il contenuto della proprietà `value` dell'elemento.
`Label`	`string`	Riflette il contenuto dell'attributo `aria-label` dell'elemento. Nel caso l'attributo `aria-label` non sia presente restituisce lo stesso valore di `Name`
`Detail`	`string`	Se l'elemento è un `input` di tipo `file` restituisce in nome originale del file. Negli altri casi può essere usata per passare al server informazioni aggiuntive su quel campo (vedi demo)

I campi che compongono lo pseudo form sono trasformati in oggetti MB_PseudoFormValue utilizzando il metodo statico asincrono MB_PseudoFormValue.createAsync che restituisce una Promise che si risolve con l'oggetto creato.

ValuesList

Il valore restituito dal metodo MB_PseudoForm.collectData (vedi sotto), che raccoglie i campi compilati dall'utente come lista di oggetti MB_PseudoFormValue è un'istanza della classe ValueList.

La classe ValueList espone una sola proprietà, length, che restituisce la lunghezza della lista e offre alcuni metodi che aiutano a gestirla.

Metodo	Tipo restituito	Descrizione
`item(i)`	`MB_PseudoFormValue`	Parametro: i `number`. Restituisce l'oggetto `MB_PseudoFormValue` con indice i
`push(obj)`	`number`	Parametro: obj `MB_PseudoFormValue`. Aggiunge un oggetto `MB_PseudoFormValue` alla lista. Se esiste già un'oggetto che lo stesso `Name`, l'oggetto presente viene sostituito da quello inserito. Restituisce la nuova lunghezza della lista
`remove(name)`	`boolean`	Parametro: name `string`. Rimuove dalla lista l'oggetto con `Name` = name. Restituisce `true` se l'oggetto è stato rimosso `false` se non è stato trovato nella lista
`indexOf(name)`	`number`	Parametro: name `string`. Cerca dalla lista l'oggetto con `Name` = name. Ne restituisce l'indice se l'oggetto è stato trovato altrimenti `-1`.
`getValue(name)`	`any`	Parametro: name `string`. Cerca dalla lista l'oggetto con `Name` = name e restituisce il suo `Value`.
`clear()`	nessuno	Svuota la lista

MB_PseudoForm

In generale non dovrebbe essere necessario accedere direttamente alle proprietà e ai metodi di MB_PseudoForm. L'interfaccia con lo pseudo form è garantita dagli eventi (change.mb.pseudoform, validate.mb.pseudoform e submitted.mb.pseudoform) che vengono emessi nei momenti chiave del processo.

Proprietà

Proprietà	Tipo	Descrizione
`pseudoForm`	`HTML element`	Proprietà a sola lettura. Restituisce l'elemento HTML su cui è stato costruito lo pseudo form
`submit`	`HTML element`	Proprietà a sola lettura. Restituisce l'elemento HTML che viene usato come submit button
`inputs`	`static NodeList`	Proprietà a sola lettura. Restituisce la lista degli elementi (`input`, `select` e `textarea`) che fanno parte dello pseudo form in formato static NodeList
`pendingChanges`	`boolean`	Restituisce `true` se almeno un elemento di input è stato modificato. Viene automaticamente resettata quando i dati vengono inviati. Può essere resettata (impostata a `false`) anche programmaticamente.

Metodi

Metodo	Tipo restituito	Descrizione
`collectData`	`Promise`	Metodo asincrono. La Promise restituita si risolve con l'elenco dei valori immessi dall'utente sotto forma di `ValueList`.
`submitData`	nessuno	Consente di inviare programmaticamente lo pseudo form al server. Emette un evento `validate.mb.pseudoform` (cancellabile) subito prima dell'invio e un evento `submitted.mb.pseudoform` subito dopo aver ricevuto la risposta dal server.

Eventi

Tutti gli eventi sono inviati all'elemento HTML su cui viene costruito lo pseudo form. Per gestirli, quindi, basta aggiungere un gestore di eventi all'elemento stesso:

<div id="sample1-en" data-mb-action="api/PseudoForm" data-mb-ride="pseudo-form">
  <!-- Campi di input -->
  <button type="button" data-mb-toggle="submit">Invia dati</button>
</div>
....
<script>
  const myForm = document.getElementById("sample1-en");
  myForm.addEventListener('validate.mb.pseudoform', event => {
    const values = event.detail;
    // .......
  })
</script>

Evento	Descrizione
`change.mb.pseudoform`	Viene emesso ogni volta che un campo dello pseudo form viene modificato. La proprietà `detail` dell'evento contiene l'elemento HTML il cui valore è stato modificato.
`validate.mb.pseudoform`	Viene emesso subito prima che i dati vengano mandati al server. La proprietà `detail` dell'evento contiene la `ValueList` che sta per essere inviata. Consente di validare i dati prima dell'invio. Per estrarre informazione su campi specifici si possono applicare alla lista i metodi della classe `ValueList`. Se si applica il metodo `preventDefault` all'evento, l'invio viene cancellato.
`submitted.mb.pseudoform`	Viene emesso dopo che i dati vengano inviati e o si riceve la risposta dal server, o si verifica un errore. Nel caso di risposta dal server, la proprietà dell'evento detail contiene la risposta, in caso di errore contiene un oggetto con quattro proprietà `Success` (`boolean`, impostata su `false`), `Message` (`string`, contiene il messaggio di errore), `Exitcode` e `Data` attualmente non usate. (vedi demo).

Demo

Nella cartella demo del progetto troverete una semplice applicazione web ASP.NET che dimostra come utilizzare MB_PseudoForm congiuntamente a un API Controller per generare, partendo da un MB_PseudoForm, una mail formattata con le informazione inserite dall'utente e inviata allo staff del sito, e una mail di ringraziamento inviata all'utente stesso.

Utilizzare il demo

Clona il repository git sul tuo computer

git clone https://github.com/magicbruno/MB_PseudoForm.git

oppure scaricalo.

Apri /demo/demo.sln in Visual Studio.

Prima di eseguire l'applicazione devi configurare il server smtp che il controller utilizzerà per inviare i messaggi email generati.

Apri nell'editor di Visual Studio Web.config e nella sezione appSettings inserisci i dati:

    <appSettings>
    <!-- Inserisci url del server -->
        <add key="SmtpServer" value="..."/>
    <!-- Inserisci credenziali di accesso -->
        <add key="SmtpUsername" value="..."/>
        <add key="SmtpPassword" value="..."/>
    <!-- Modifica le impostazioni ssl se necessario -->
        <add key="SmtpPort" value="25"/>
        <add key="SmtpUseSSL" value="false"/>
    <!-- Mittente dei messaggi inviati dal server -->
        <add key="DefaultSmtpFromMail" value="..."/>
    <!-- Casella di posta dello staff -->
        <add key="MailTo" value="..."/>
    </appSettings>

Quindi lancia l'applicazione in Iis Express premendo f5 o ctrl + f5.

Nota

Per usare l'api controller /ApiControllers/PseudoFormController.cs in un tuo progetto devi installare il pacchetto Microsoft.AspNet.WebApi e aggiungere al progetto anche le classi /ApiControllers/ApiControllerResponse.cs e /ApiControllers/PseudoFormModel.cs. Maggiori informazioni su ASP.NET Web API qui.