1. Dokumentace
  2. Reference
  3. Controly – formuláře

<f:emailForm>

Control EmailForm slouží k poslání dat z odeslaného formuláře na email. Control podporuje validaci zaslaných dat na straně serveru, viz Jak to funguje / Formuláře.

<f:emailForm runat="server"
                  emailTemplate="EmailTemplates/newMessage">
    <formTemplate>
        <f:input runat="server"
                 id="someFormField" />
        <f:sendButton runat="server" />
    </formTemplate>
    <sentTemplate>
        Formulář byl úspěšně odeslán.
    </sentTemplate>
</f:emailForm>

Pro funkčnost emailového formuláře na stránce je nutné ještě nastavit email příjemce a mailserver, případně definovat šablonu emailu (viz níže).

Pokud stačí data zapsat do kolekce deklarované v Site.config, je možné použít control <f:collectionForm>.

Atributy

  • emailFormat nepovinný [text, html]

    Určuje formát odesílaného mailu.

  • emailTemplate nepovinný [cesta v textovém souboru]

    Cesta k uzlu v textového souboru s definicí šablony posílaného mailu. Není-li atribut uveden, je výsledný mail sestaven automaticky ze všech polí formuláře.

  • id povinný [string]

    Identifikátor formulářového prvku, který je použit pro HTML atribut name při výpisu do stránky a pro spárování s příslušným placeholderem v šabloně emailu v textovém souboru (viz <f:emailForm>).

  • resetOnSend nepovinný [true, false]

    Při nastavení se po odeslání formuláře zobrazí obě šablony formTemplate i sentTemplate. Ve výchozím nastavení false se zobrazí jen šablona sentTemplate.

  • targetCollection nepovinný [název cílové kolekce]

    Jméno kolekce deklarované v Site.config, do které vedle poslání emailem uloží data z formuláře. Není-li cílová kolekce uvedena, data jsou jen odeslána emailem.

Templates

Před odesláním formuláře se na stránce zobrazuje obsah formTemplate, po úspěšném odeslání potom sentTemplate.

Šablona emailu

V textovém souboru je možné definovat šablonu emailu, kterým se posílají data z odeslaného formuláře. V tomto příkladě emailTemplate="EmailTemplates/NewComment":

...
<EmailTemplates>
    <NewComment>
        <Subject>Nový příspěvek v diskuzi</Subject>
        <Body>
            Jméno: {name}
            Email: {email}
            Zpráva: {text}
        </Body>
    </NewComment>
</EmailTemplates>
...

Element <Subject> obsahuje předmět posílaného emailu, <Body> jeho tělo. Výrazy ve složených závorkách – např. {name} – odpovídají atributům id formulářových polí ve stránce.

V případě vícejazyčného webu není nutné uvádět šablonu ve všech jazycích, stačí pouze ve výchozím jazyku. Pokud není šablona nalezena v aktuálním jazyku webu, odkud byl formulář odeslán, použije se šablona z výchozího jazyka (viz Jazyky). Pokud není nalezena ani tam, použije se výchozí systémová, kdy je email sestaven ze všech polí formuláře.

Email příjemce a mailserver

Pro poslání obsahu odeslaného formuláře emailem je nutné v Runtime.config nastavit, odkud, komu a pomocí jakého SMTP serveru se má email odeslat. Více viz EmailForms.

Jak probíhá odeslaní a uložení do kolekce

Uložení dat do kolekce probíhá před odesíláním emailu, takže v případě, kdy odeslání emailu selže, jsou data k dispozici v cílové kolekci (pokud je nastaven atribut targetCollection u controlu <f:emailForm>). Vlastní odesílání mailu se zahájí v jiném procesu, než je obnovení stránky. To má výhodu, že odeslání mailu nezdržuje načtení stránky. Na druhou stranu ale nelze zobrazit případné chybové hlášení, pokud se odeslání nepovedlo.

Příklad

Jednoduchý kontaktní formulář s poli pro email uživatele a text zprávy, kdy po každém odeslání formuláře je odeslán email administrátorovi, uděláme takto:

<form method="post" runat="server">
    <f:EmailForm runat="server"
                      id="contact"
                      targetCollection="messageCol"
                      emailTemplate="Emails/Contact">
        <formTemplate>
            <label>
                Vaše jméno*
                <f:input runat="server"
                         id="name"
                         targetField="name" />
            </label>
            <label>
                Email*
                <f:input runat="server"
                         id="email"
                         targetField="email" />
            </label>
            <label>
                Zpráva*
                <f:textarea runat="server"
                            id="message"
                            targetField="message" />
            </label>
            <f:sendButton runat="server"
                          value="Odeslat" />
        </formTemplate>
        <sentTemplate>
            <p>Zpráva byla odeslána. Díky!</p>
        </sentTemplate>
    </f:EmailForm>
</form>

Data ukládáme do kolekce messageCol (atribut targetCollection="messageCol"), musíme ji tedy mít deklarovanou v Site.config i s patřičným typem jejích prvků:

...
<Vars>
    ...
    <Collection name="messageCol" itemType="MessageItem" />
    ...
</Vars>
...
<Types>
    ...
    <Type name="MessageItem">
        <SimpleText name="name" />
        <SimpleText name="email" />
        <Text name="message" />
    </Type>
    ...
</Types>
...

Taktéž používáme emailovou šablonu Emails/Contact (atribut emailTemplate="Emails/Contact"), musíme proto mít v textovém souboru zadefinovanou šablonu následovně:

<Texts lang="cs" xmlns="urn:Bet:ns:CmsTxt">
    ...
    <Emails>
        <Contact>
            <Subject>Nová zpráva</Subject>
            <Body>
                Jméno: {name}
                Email: {email}
                Zpráva:
                {message}
            </Body>
        </Discussion>
    </Emails>
    ...
</Texts>

A konečně musíme nastavit emailu příjemce a mail serveru. V tomto konkrétní příkladě by mohla definice v Runtime.config vypadat takto:

<JellyPotDef>
    ...
    <EmailForms>
        <EmailServer name="myServer"
                     smtp="smtp.example.com"
                     userName="someUsername"
                     pwd="somePassword" />
        <EmailForm name="contact"
                   server="myServer"
                   to="admin@example.com" />
    </EmailForms>
    ...
</JellyPotDef>

Více informací o nastavení příjemců a mailových serverů je uvedeno v článku EmailForms.

Validace dat

Příklad je pro názornost a přehlednost uveden bez validace zaslaných dat. O tom, jak validovat zaslaná data na straně serveru, se píše v článku Jak to funguje / Formuláře.

HTML email

Nastavením atributu emailFormat="html" lze odeslat email ve formátu HTML. Příklad výše by se tedy lišil pouze tímto atributem:

<form method="post" runat="server">
    <f:EmailForm runat="server"
                      id="contact"
                      targetCollection="messageCol"
                      emailTemplate="Emails/Contact"
                      emailFormat="html">
        <formTemplate>
...

V šabloně emailu v textovém souboru pak lze používat HTML tagy:

<Texts lang="cs" xmlns="urn:Bet:ns:CmsTxt">
    ...
    <Emails>
        <Contact>
            <Subject>Nová zpráva</Subject>
            <Body>
                <table>
                    <tr><td>Jméno</td><td>{name}</td></tr>
                    <tr><td>Email</td><td>{email}</td></tr>
                    <tr><td colspan="2">{message}</td></tr>
                </table>
            </Body>
        </Discussion>
    </Emails>
    ...
</Texts>

Připomínky a postřehy

Máte-li nějakou připomínku, dobrý nápad nebo jste našli v dokumentaci chybu, rádi od vás uslyšíme.