gooseform v0.1.1

Goose Form

"Alla Goose più coraggiosa che io conosca"

Goose Form è un generatore dinamico di form realizzato in React. Mediante un oggetto JSON in ingresso opportunamente valorizzato, restituirà in uscita un form con tutti i campi richiesti, controlli di validazione e regole di visibilità. Oltre a questo, è possibile specificare anche la sorgente dati per generare form precompilati e l'endpoint di destinazione al quale inviare tutte le informazioni. Di seguito è presente la documentazione che illustra tutte le funzionalità del progetto. Sono disponibili i componenti Goose Form BE e Goose Form Manager per agevolare e velocizzare la creazione dei form.

Funzionamento

Il concetto fondamentale di Goose Form è quello di "identificativo". Ogni dato che vogliamo rappresentare deve avere un identificativo univoco scritto in camelCase ("nomeUtente", "dataDiNascita", "colorePreferito"). Le informazioni viaggeranno mediante la logica "Chiave/Valore". Esiste un oggetto di riferimento chiamato GooseKeyValue. Tuttavia l'applicazione non è in grado di gestire un nested JSON.

Componenti

GooseForm

GooseForm è l'oggetto contenitore di tutti i componenti, prende in input il JSON di configurazione e restituisce un form completo come descritto nel paragrafo introduttivo.

Oggetto JSON di esempio:

{
  "formId": "formId",
  "title": "Titolo del form",
  "icon": "fas fa-feather-alt",
  "sendButton": {...},
  "resetButton": {...},
  "description": "Descrizione del form",
  "popup": {...},
  "autocomplete": true,
  "destinationUrl": {...},
  "originUrl": {...},
  "components": [{...}],
  "controls": [{...}],
  "renders": [{...}]
}

Form precompilato

Goose Form, tramite l'oggetto originUrl di tipo GooseHttpRequest consente di leggere i dati in formato JSON (no nested JSON) da un endpoint e mostrarli all'interno del form. Il nome dell'attributo del JSON deve corrispondere a quello dell'identificativo del campo.

Oggetto JSON di esempio:

{
  "cognome": "Riggi",
  "colorePreferito": "blu",
  "nome": "Riccardo",
  "dataDiNascita": "2000-06-12"
}

Form submit

L'oggetto destinationUrl di tipo GooseHttpRequest consente di inviare sottoforma di JSON i dati del form ad uno specifico endpoint. I campi nascosti o disabilitati non verranno inviati. Verrà mostrato un messaggio di success se l'enpoint restituirà un codice HTTP di tipo 2xx, altrimenti apparirà un messaggio di error.

Oggetto JSON di esempio:

{
  "cognome": "Riggi",
  "colorePreferito": "blu",
  "nome": "Riccardo",
  "dataDiNascita": "2000-06-12"
}

GooseTooltip

GooseTooltip è una semplice icona che, al passaggio del mouse, mostra una descrizione | Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |icon|String|Nome basato su Font Awesome dell'icona| |description|String|Testo del tooltip|

Oggetto JSON di esempio:

{
    "icon": "fas fa-feather-alt",
    "description": "Esempio di descrizione"
}

GoosePopup

GoosePopup è un'icona che, se premuta, mostra un popup con un titolo e una descrizione | Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |icon|String|Nome basato su Font Awesome dell'icona| |textTooltip|String|Testo del tooltip| |title|String|Titolo del popup| |description|String|Testo del popup|

Oggetto JSON di esempio:

{
    "icon": "fas fa-feather-alt",
    "textTooltip": "Esempio di testo tooltip",
    "title": "Titolo popup",
    "description": "Esempio di descrizione"
}

GooseButton

GooseButton è semplicemente un pulsante con titolo ed icona | Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |icon|String|Nome basato su Font Awesome dell'icona| |title|String|Titolo del pulsante|

Oggetto JSON di esempio:

{
    "title": "Invia",
    "icon": "fas fa-feather-alt"
}

GooseHttpRequest

GooseHttpRequest è l'oggetto che permette di far eseguire chiamate HTTP a GooseForm e ai componenti che necessitano di recuperare i valori dinamicamente

Oggetto JSON di esempio:

{
    "url": "http://localhost:8080/gooseform/documentazione/destinazione/esempioUno",
    "method": "POST",
    "headers": [
      {
        "key": "HEADER_1",
        "value": "VALORE_1"
      },
      {
        "key": "HEADER_2",
        "value": "VALORE_2"
      }
    ],
    "body": null
}

GooseComponent

GooseComponent è l'oggetto che rappresenta ciascun componente del form, contiene degli attributi comuni a tutti i componenti e altri specifici che variano in base al type.

Elenco dei type:

[
  "GOOSE_TEXT_AREA",
  "GOOSE_SELECT",
  "GOOSE_LINKED_SELECT",
  "GOOSE_DATA_LIST",
  "GOOSE_TEXT_FIELD",
  "GOOSE_PASSWORD_FIELD",
  "GOOSE_NUMBER_FIELD",
  "GOOSE_RADIO",
  "GOOSE_CHECKBOX",
  "GOOSE_EMAIL_FIELD",
  "GOOSE_DATE_FIELD",
  "GOOSE_DATE_TIME_FIELD",
  "GOOSE_MONTH_FIELD",
  "GOOSE_WEEK_FIELD",
  "GOOSE_TIME_FIELD",
  "GOOSE_TEL_FIELD",
  "GOOSE_URL_FIELD",
  "GOOSE_COLOR_FIELD",
  "GOOSE_RANGE_FIELD"
]

Oggetto JSON di esempio:

{
    "formId": "idForm",
    "id": "cognome",
    "type": "GOOSE_TEXT_FIELD",
    "label": "Cognome",
    "widthXl": "12",
    "widthLg": "12",
    "widthMd": "12",
    "widthSm": "12",
    "width": "12",
    "setting": {...},
    "tooltip": {...},
    "popup": {...},
    "requiredMark": true
}

Di seguito l'elenco di tutti i componenti implementati in Goose Form con i relativi attributi specifici

GooseTextArea

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |rows|Number|Indica il numero di righe di altezza della Text Area|

Oggetto JSON di esempio:

{
    "rows": 3
}

GooseSelect (Statica)

In questa variante la lista delle opzioni viene inclusa all'interno del JSON di configurazione | Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |size|Number|Numero di opzioni mostrate| |values|List < GooseKeyValue >|Lista statica di opzioni con forma chiave/valore|

{
    "size": 1,
    "values": [
        {
            "key": "",
            "value": "Scegli..."
        },
        {
            "key": "GOOSE",
            "value": "GOOSE"
        },
        {
            "key": "PAPERA",
            "value": "PAPERA"
        },
        {
            "key": "ANATRA",
            "value": "ANATRA"
        },
        {
            "key": "OCA",
            "value": "OCA"
        },
        {
            "key": "PAPERELLA",
            "value": "PAPERELLA"
        }
    ],
}

GooseSelect (Dinamica)

In questa variante la lista delle opzioni viene recuperata mediante chiamata HTTP ad un endpoint esterno | Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |size|Number|Numero di opzioni mostrate| |dynamicValues|GooseHttpRequest|Oggetto che consente di chiamare un endpoint per recuperare le opzioni da mostrare| |keyName|String|Nome del campo definito chiave presente nella risposta dell'endpoint| |valueName|String|Nome del campo definito valore presente nella risposta dell'endpoint|

Oggetto JSON di esempio:

{
    "size": 1,
    "values": null,
    "dynamicValues": {
        "url": "http://localhost:8080/gooseform/documentazione/opzioni",
        "method": "POST",
        "headers": [
            {
                "key": "HEADER_1",
                "value": "VALORE CUSTOM HEADER"
            }
        ],
        "body": "CORPO DELLA CHIAMATA"
    },
    "keyName": "key",
    "valueName": "value"
}

GooseLinkedSelect

In questa variante di GooseSelect sono presenti due componenti: padre e figlio. Al variare del padre vengono aggiornate le opzioni del figlio. Le opzioni vengono recuperate via endpoint. Un esempio pratico è la classica coppia di select "Provincia" e "Comune": al variare della provincia viene mostrata la lista dei comuni corrispondenti. | Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |size|Number|Numero di opzioni mostrate| |dynamicValues|GooseHttpRequest|Oggetto che consente di chiamare un endpoint per recuperare le opzioni da mostrare| |keyName|String|Nome del campo definito chiave presente nella risposta dell'endpoint| |valueName|String|Nome del campo definito valore presente nella risposta dell'endpoint| |idLinkedSelectPadre|String|Contiene l'identificativo del padre a cui fa riferimento| |idLinkedSelectFiglia|String|Contiene l'identificativo del figlio a cui fa riferimento|

Oggetto JSON di esempio:

{
    "size": 1,
    "values": null,
    "dynamicValues": {
        "url": "http://localhost:8080/gooseform/documentazione/opzioni",
        "method": "POST",
        "headers": [
            {
                "key": "HEADER_1",
                "value": "VALORE CUSTOM HEADER"
            }
        ],
        "body": "CORPO DELLA CHIAMATA"
    },
    "keyName": "key",
    "valueName": "value",
    "idLinkedSelectPadre": null,
    "idLinkedSelectFiglia": "gooseLinkedSelectFiglia"
}

GooseDataList (Statica)

In questa variante la lista dei suggerimenti viene inclusa all'interno del JSON di configurazione | Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |placeholder|String|Segnaposto della casella di testo| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura| |autofocus|Boolean|Sposta il focus del cursore su questo determinato campo| |values|List < GooseKeyValue >|Lista statica di suggerimenti con forma chiave/valore|

Oggetto JSON di esempio:

{
    "name": "gooseDataListStatica",
    "placeholder": "Scegli valore",
    "disabled": false,
    "readonly": false,
    "autofocus": true,
    "values": [
        {
            "key": "unoStatico",
            "value": "Uno Statico"
        },
        {
            "key": "dueStatico",
            "value": "Due Statico"
        },
        {
            "key": "treStatico",
            "value": "Tre Statico"
        },
        {
            "key": "quattroStatico",
            "value": "Quattro Statico"
        },
        {
            "key": "cinqueStatico",
            "value": "Cinque Statico"
        }
    ],
    "dynamicValues": null,
    "keyName": null,
    "valueName": null
}

GooseDataList (Dinamica)

In questa variante la lista dei suggerimenti viene recuperata mediante chiamata HTTP ad un endpoint esterno | Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |placeholder|String|Segnaposto della casella di testo| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura| |autofocus|Boolean|Sposta il focus del cursore su questo determinato campo| |dynamicValues|GooseHttpRequest|Oggetto che consente di chiamare un endpoint per recuperare i suggerimenti da mostrare| |keyName|String|Nome del campo definito chiave presente nella risposta dell'endpoint| |valueName|String|Nome del campo definito valore presente nella risposta dell'endpoint|

Oggetto JSON di esempio:

{
    "name": "gooseDataListDinamica",
    "placeholder": "Scegli valore",
    "disabled": false,
    "readonly": false,
    "autofocus": true,
    "values": null,
    "dynamicValues": {
        "url": "http://localhost:8080/gooseform/documentazione/opzioniDue",
        "method": "POST",
        "headers": [
            {
                "key": "HEADER_2",
                "value": "VALORE NUOVO HEADER"
            }
        ],
        "body": "CORPO DELLA CHIAMATA DUE"
    },
    "keyName": "chiave",
    "valueName": "valore"
}

GooseTextField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |placeholder|String|Segnaposto della casella di testo| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura| |autofocus|Boolean|Sposta il focus del cursore su questo determinato campo|

Oggetto JSON di esempio:

{
    "name": "gooseTextField",
    "placeholder": "Inserisci un testo...",
    "disabled": false,
    "readonly": false,
    "autofocus": false
}

GoosePasswordField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |placeholder|String|Segnaposto della casella di testo| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura| |autofocus|Boolean|Sposta il focus del cursore su questo determinato campo|

Oggetto JSON di esempio:

{
    "name": "goosePasswordField",
    "placeholder": "Inserisci la password...",
    "disabled": false,
    "readonly": false,
    "autofocus": false
}

GooseNumberField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |placeholder|String|Segnaposto della casella di testo| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura| |autofocus|Boolean|Sposta il focus del cursore su questo determinato campo| |steps|Number|Numero di salti tra un numero e l'altro|

Oggetto JSON di esempio:

{
    "name": "gooseNumberField",
    "placeholder": "Inserisci un numero...",
    "disabled": false,
    "readonly": false,
    "autofocus": false,
    "steps":2
}

GooseRadio (Statici)

In questa variante l'elenco dei radio viene incluso all'interno del JSON di configurazione | Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |size|Number|Numero di opzioni mostrate| |values|List < GooseKeyValue >|Lista statica di opzioni con forma chiave/valore| |name|String|Nome (uguale all'id)| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura|

{
    "name": null,
    "disabled": false,
    "readonly": false,
    "values": [
        {
            "key": "unoStatico",
            "value": "Uno Statico"
        },
        {
            "key": "dueStatico",
            "value": "Due Statico"
        },
        {
            "key": "treStatico",
            "value": "Tre Statico"
        },
        {
            "key": "quattroStatico",
            "value": "Quattro Statico"
        },
        {
            "key": "cinqueStatico",
            "value": "Cinque Statico"
        }
    ],
    "dynamicValues": null,
    "keyName": null,
    "valueName": null
}

GooseRadio (Dinamici)

In questa variante l'elenco dei radio viene incluso all'interno del JSON di configurazione | Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |size|Number|Numero di opzioni mostrate| |dynamicValues|GooseHttpRequest|Oggetto che consente di chiamare un endpoint per recuperare le opzioni da mostrare| |keyName|String|Nome del campo definito chiave presente nella risposta dell'endpoint| |valueName|String|Nome del campo definito valore presente nella risposta dell'endpoint| |name|String|Nome (uguale all'id)| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura|

{
    "name": null,
    "disabled": false,
    "readonly": false,
    "values": null,
    "dynamicValues": {
        "url": "http://localhost:8080/gooseform/documentazione/opzioni",
        "method": "POST",
        "headers": [
            {
                "key": "HEADER_1",
                "value": "VALORE CUSTOM HEADER"
            }
        ],
        "body": "CORPO DELLA CHIAMATA"
    },
    "keyName": "key",
    "valueName": "value"
}

GooseCheckbox

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura|

Oggetto JSON di esempio:

{
    "name": "gooseCheckbox",
    "disabled": false,
    "readonly": false,
}

GooseEmailField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |placeholder|String|Segnaposto della casella di testo| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura| |autofocus|Boolean|Sposta il focus del cursore su questo determinato campo|

Oggetto JSON di esempio:

{
    "name": "gooseEmailField",
    "placeholder": "Inserisci il tuo indirizzo email...",
    "disabled": false,
    "readonly": false,
    "autofocus": false
}

GooseColorField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura|

Oggetto JSON di esempio:

{
    "name": "gooseColorField",
    "disabled": false,
    "readonly": false,
}

GooseDateField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura|

Oggetto JSON di esempio:

{
    "name": "gooseDateField",
    "disabled": false,
    "readonly": false,
}

GooseDateTimeField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura|

Oggetto JSON di esempio:

{
    "name": "gooseDateTimeField",
    "disabled": false,
    "readonly": false,
}

GooseMonthField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura|

Oggetto JSON di esempio:

{
    "name": "gooseMonthField",
    "disabled": false,
    "readonly": false,
}

GooseRangeField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura| |autofocus|Boolean|Sposta il focus del cursore su questo determinato campo| |steps|Number|Numero di salti tra un numero e l'altro| |min|Number|Valore minimo| |max|Number|Valore massimo|

Oggetto JSON di esempio:

{
    "name": "gooseRangeField",
    "disabled": false,
    "readonly": false,
    "min": "-20",
    "max": "20",
    "step": "2"
}

GooseTelField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |placeholder|String|Segnaposto della casella di testo| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura| |autofocus|Boolean|Sposta il focus del cursore su questo determinato campo|

Oggetto JSON di esempio:

{
    "name": "gooseTelField",
    "placeholder": "Inserisci un numero di telefono...",
    "disabled": false,
    "readonly": false,
    "autofocus": false
}

GooseTimeField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura|

Oggetto JSON di esempio:

{
    "name": "gooseTimeField",
    "disabled": false,
    "readonly": false,
}

GooseUrlField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |placeholder|String|Segnaposto della casella di testo| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura| |autofocus|Boolean|Sposta il focus del cursore su questo determinato campo|

Oggetto JSON di esempio:

{
    "name": "gooseUrlField",
    "placeholder": "Inserisci un indirizzo web...",
    "disabled": false,
    "readonly": false,
    "autofocus": false
}

GooseWeekField

| Nome | Tipo | Descrizione | | ----------- | ----------- | ----------- | |name|String|Nome (uguale all'id)| |disabled|Boolean|Disabilita il campo| |readonly|Boolean|Imposta il campo in modalità sola lettura|

Oggetto JSON di esempio:

{
    "name": "gooseWeekField",
    "disabled": false,
    "readonly": false,
}

Controlli

Sono disponibili diversi controlli di validazione lato client che possono essere raggrupati in "STANDARD" e "COMPLEX". I primi confrontano il valore dell'oggetto al quale fanno riferimento con un valore statico impostato nella configurazione, i secondi lo confrontano con il valore di un altro elemento del form. Per ogni controllo è possibile impostare un messaggio di errore personalizzato.

GooseStandardControl

Oggetto JSON di esempio:

{
    "type": "STANDARD",
    "detail": {
        "idComponentA": "nome",
        "type": "REQUIRED",
        "referenceValue": null,
        "referenceValues": null,
        "errorMessage": "Il campo Nome è richiesto"
    }
}

Questo controllo ha come riferimento un componente "A", un valore di rifermento, oppure una lista di valori di riferimento, da confrontare, un messaggio di errore personalizzato e un tipo. Di seguito i tipi di controlli "STANDARD" disponibili:

GooseComplexControl

Oggetto JSON di esempio:

{
    "type": "COMPLEX",
    "detail": {
        "idComponentA": "password",
        "idComponentB": "confermaPassword",
        "type": "EQUAL",
        "errorMessage": "Le due password non corrispondono"
    }
}

Questo controllo ha come riferimento un componente "A", un componente "B", un messaggio di errore personalizzato e un tipo. Di seguito i tipi di controlli "COMPLEX" disponibili:

Render condizionale

Sono disponibili dei "Render condizionali" che consentono, al verificarsi di opportune condizioni, di nascondere o disabilitare un determinato campo. Esistono due tipi di render: "SIMPLE_RENDER" e "COMPLEX_RENDER". Il primo confronta il valore con un valore statico, il secondo con un valore di un altro determinato elemento del form.

GooseSimpleRenderConditional

Oggetto JSON di esempio:

{
    "type": "SIMPLE_RENDER",
    "detail": {
        "idComponentA": "a",
        "idComponentB": "b",
        "type": "HIDE_B_IF_A_EQUAL_X",
        "value": "GOOSE"
    }
}

Il "SIMPLE_RENDER" ha un componente "B" che verrà nascosto o disabilitato se il componente "A", confrontato con il valore di riferimento, darà esito positivo. Di seguito i tipi di "SIMPLE_RENDER":

GooseComplexRenderConditional

Oggetto JSON di esempio:

{
    "type": "COMPLEX_RENDER",
    "detail": {
        "idComponentA": "a",
        "idComponentB": "b",
        "type": "HIDE_C_IF_A_EQUAL_B",
        "idComponentC": "c"
    }
}

Il "COMPLEX_RENDER" ha un componente "C" che verrà nascosto o disabilitato se il componente "A", confrontato con il componente "B", darà esito positivo. Di seguito i tipi di "COMPLEX_RENDER":

Bom / Diba

SB Admin 2 (Tema basato su Bootstrap 4)

Font Awesome

React 18

Redux 7

React Router 6

Axios

react-markdown

remark-gfm

Favicon e logo

Licenza

Il codice sorgente da me scritto viene rilasciato con licenza MIT, framework, temi e librerie di terze parti mantengono le loro relative licenze.