Moduli di contatto e messaggi

Contact Form e Contact Messages sono funzionalità di prima classe di WebBlocks CMS. Utilizzate il blocco nativo contact_form per le pagine di contatto invece di Trusted HTML, markup di form grezzo o soluzioni di ripiego con mailto:.

Questa guida consolida il comportamento di Contact Form e Contact Messages rivolto all'utente, documentato nei contratti dei blocchi, nei contratti di rendering pubblico, nella documentazione della Internal Content API e nel README. Non definisce nuovi comportamenti di runtime.

Il blocco Contact Form esegue il rendering di un vero form pubblico e memorizza nel CMS i messaggi accettati. Contact Messages offre agli amministratori una schermata di revisione di questi invii, che include stato, segnali di revisione dello spam, stato della notifica e dettagli sicuri sugli errori di consegna.

Il CMS tratta l'archiviazione e la notifica via e-mail come aspetti distinti:

• gli invii reali accettati vengono memorizzati prima che venga tentata la notifica
• la notifica può riuscire, fallire o essere saltata senza modificare il fatto che il CMS ha accettato l'invio pubblico
• i visitatori pubblici devono vedere un riscontro generico di successo o di validazione, non il punteggio di spam o i dettagli interni della consegna

Aggiungete il blocco dal selettore di blocchi del Page Builder. L'handle nativo del blocco è:

Il blocco Contact Form non è un contenitore di blocchi figli. Possiede la superficie pubblica del form e non accetta blocchi di contenuto annidati come normale modello di composizione.

Una tipica pagina di contatto utilizza contenuto strutturato attorno al form nativo:

Gli strumenti IA/operatore devono costruire lo stesso tipo di struttura dopo che la discovery in tempo reale ha confermato gli handle disponibili. Non devono creare form con Trusted HTML, markup <form> grezzo o link mailto: quando contact_form esiste nell'installazione CMS di destinazione.

Il testo visibile è traducibile:

• title o intestazione
• content o testo introduttivo
• submit_label
• success_message

Le impostazioni operative condivise si trovano nelle impostazioni del blocco:

• recipient_email
• send_email_notification
• store_submissions

Mantenete separati il testo editoriale e l'instradamento operativo. Il testo del form può variare in base alla lingua (locale), mentre le impostazioni di destinatario e notifica restano condivise per il blocco.

Il renderer pubblico genera un form nativo del browser che invia i dati a:

Il form è protetto da CSRF e valida i normali campi del visitatore.

Campi obbligatori:

• name
• email
• message

Campo opzionale:

• subject

Campo di controllo antispam generato dal renderer:

• _form_check_name metadati firmati
• form_check_{token} campo di controllo generato

Il renderer crea questi campi automaticamente. Non createli manualmente nel contenuto, in HTML grezzo o nei payload dell'API. Il campo di controllo non fa parte del normale input del visitatore e il vecchio campo website non è più il contratto pubblico di Contact Form.

Gli invii con il campo di controllo compilato ricevono lo stesso comportamento generico di successo di un normale invio accettato, ma non vengono memorizzati e non attivano la notifica. Gli invii automatizzati molto rapidi vengono gestiti allo stesso modo. I visitatori pubblici non devono ricevere diagnostica su spam o consegna.

Gli invii reali accettati vengono memorizzati prima che venga tentata la notifica via e-mail.

Percorso di amministrazione:

Contact Messages è una schermata di revisione per amministratori. Non è un elenco pubblico né un'API pubblica di consegna.

La schermata di amministrazione consente agli utenti del CMS di rivedere gli invii a livello di guida utente:

• lo stato del messaggio, ad esempio nuovo, letto, con risposta, archiviato o spam
• il contesto della pagina di origine, quando disponibile
• il punteggio di spam e le etichette del motivo dello spam per la revisione
• se la notifica è stata saltata, inviata, è fallita o è in attesa
• dettagli sicuri sull'errore quando la consegna della notifica fallisce

Lo stato della notifica via e-mail riguarda esclusivamente il comportamento della notifica:

• Sent significa che il CMS ha consegnato il messaggio al trasporto di posta configurato senza eccezioni. Non garantisce la consegna nella casella di posta.
• Failed significa che è stato tentato un invio reale della notifica e Laravel ha segnalato un'eccezione. Il dettaglio salvato è sanificato e non deve includere password, token, il file .env grezzo o stack trace.
• Skipped significa che la notifica non è stata tentata, di solito perché il blocco l'ha disattivata.
• Not configured significa che la notifica non è stata tentata perché non era disponibile alcun destinatario, il mailer è log, array o null, oppure le impostazioni SMTP sono incomplete al punto da rendere impossibile la consegna in uscita.
• Pending è riservato ai record per i quali non si è ancora verificato un tentativo di notifica o una risoluzione.

I messaggi salvati meno recenti possono avere lo stato di notifica dedotto dai vecchi campi di invio/errore. Il CMS non riscrive automaticamente questi record storici.

Contact Messages segue inoltre il comportamento condiviso degli elenchi di amministrazione per l'eliminazione in blocco degli elementi selezionati, dove disponibile. Considerate l'eliminazione come un'azione di pulizia amministrativa, non come parte della normale gestione del form pubblico.

La gestione dello spam ha due livelli.

Il livello del campo di controllo generato dal renderer prevede lo scarto immediato:

• il campo nascosto generato form_check_{token} deve restare vuoto per i visitatori normali
• gli invii con il campo di controllo compilato ricevono un successo generico
• gli invii con il campo di controllo compilato non vengono memorizzati
• gli invii con il campo di controllo compilato non attivano la notifica

Gli invii che superano il campo di controllo generato possono comunque ricevere un punteggio prudenziale. Esempi attuali di segnali di punteggio:

• densità elevata di link o link multipli
• linguaggio di contatto commerciale
• combinazioni generiche di oggetto e messaggio in stile vendita
• invii ripetuti dallo stesso indirizzo IP

Lo spam con punteggio viene volutamente conservato con stato di spam per la revisione da parte dell'amministratore. Non descrivete l'eliminazione automatica dello spam come comportamento attuale. Una soglia configurabile di scarto automatico è solo una possibile direzione futura, dopo l'osservazione dei dati di produzione.

La notifica di Contact Form utilizza questo ordine di destinatari:

1. recipient_email a livello di blocco
2. Il destinatario Contact predefinito del sito corrente, da Edit Site -> Contact
3. CONTACT_RECIPIENT_EMAIL
4. MAIL_FROM_ADDRESS come ultimo fallback sicuro

Il successo dell'archiviazione è distinto dal successo della notifica. Una risposta pubblica di successo indica che il CMS ha accettato il flusso del messaggio, non necessariamente che la consegna dell'e-mail sia riuscita. Gli amministratori devono controllare Contact Messages per lo stato della notifica e i dettagli sicuri sugli errori.

Le notifiche di Contact Form utilizzano la consegna della posta di Laravel. Le impostazioni SMTP tipiche in .env sono:

MAIL_* controlla il trasporto di posta di Laravel. MAIL_FROM_ADDRESS è l'indirizzo mittente sicuro di ripiego e l'ultimo fallback sicuro per il destinatario. CONTACT_RECIPIENT_EMAIL è opzionale e viene utilizzato solo quando i destinatari del blocco e del sito sono vuoti. Per il normale instradamento del sito, preferite il destinatario Contact a livello di sito in Site -> Edit -> Contact.

Per le notifiche in produzione utilizzate un mailer in uscita reale, come SMTP. MAIL_MAILER=log, MAIL_MAILER=array e MAIL_MAILER=null sono utili per lo sviluppo o i test, ma Contact Messages li mostra come non configurati anziché inviati, perché non è stato tentato alcun invio reale in uscita.

Dopo aver modificato le impostazioni di posta in .env su un'installazione di produzione o da pacchetto, svuotate la configurazione memorizzata nella cache quando il caching della configurazione potrebbe essere attivo:

Per lo sviluppo locale, utilizzate un catcher SMTP locale o un account SMTP di test affidabile. Evitate di testare la consegna dei contatti su caselle personali o di produzione, a meno che l'operatore non abbia configurato intenzionalmente quell'ambiente.

Il comando di diagnostica è:

Utilizzate l'ID di uno specifico blocco Contact Form per esaminare il fallback dei destinatari di quel blocco:

Utilizzate una verifica di invio SMTP controllata solo quando l'indirizzo di test di destinazione è intenzionale:

La diagnostica non deve stampare password, token, segreti di posta o configurazioni sensibili grezze. I dettagli delle notifiche fallite, saltate e non configurate possono essere esaminati da Contact Messages. Considerate Contact Messages come la fonte di verità per gli invii memorizzati e il loro stato di notifica.

Prima di pubblicare o annunciare una pagina di contatto pubblica:

1. Verificate che il login amministratore funzioni.
2. Verificate che l'identità del sito e le impostazioni del dominio siano corrette.
3. Configurate la consegna MAIL_* o le impostazioni di posta di sistema approvate.
4. Configurate il destinatario Contact, preferibilmente in Site -> Edit -> Contact.
5. Eseguite php artisan contact:mail-diagnose.
6. Visualizzate in anteprima o pubblicate una pagina che contiene il blocco nativo contact_form.
7. Inviate un messaggio di prova con nome, e-mail, oggetto e messaggio.
8. Verificate che /webadmin/contact-messages mostri il messaggio memorizzato.
9. Esaminate lo stato della notifica ed eventuali dettagli sicuri sugli errori.

Se la notifica fallisce ma il messaggio viene memorizzato, trattatelo come un problema di consegna della posta, non come un invio fallito del form pubblico.

La Internal Content API è destinata a strumenti IA/operatore affidabili. Non è un'API pubblica di consegna né un'integrazione con un fornitore di IA.

Gli strumenti IA/operatore devono iniziare con la discovery in tempo reale:

Utilizzate poi i link individuati per i contratti correnti:

GET /webadmin/api/examples/contact-page mostra l'uso nativo di contact_form. Gli strumenti IA/operatore non devono indovinare gli handle né creare moduli di contatto con Trusted HTML, markup di form grezzo o link mailto: quando il blocco nativo Contact Form è disponibile.

L'applicazione dei contenuti resta orientata alla bozza e non pubblica per impostazione predefinita. Gli operatori devono validare i piani, applicarli solo dopo un'approvazione esplicita, visualizzare in anteprima la pagina in bozza e lasciare la pubblicazione a una persona o a un flusso di lavoro approvato esplicitamente.

• Contratti dei tipi di blocco
• Markup di rendering pubblico dei blocchi
• Contratti del renderer
• Internal Content API
• Discovery delle API
• Guida alla creazione di pagine con IA
• Inventario delle funzionalità