Help:KLEmailForm

Jump to: navigation, search

Contents

KLEmailForm is a MediaWiki extension used to create an email form in any article. Both the form fields and the response to submittal are formatted using standard wikitext. Upon submittal, the user is returned to the same page and the response is displayed in place of the form.

Using KLEmailForm

The tags <EmailForm> and </EmailForm> enclose all form definitions. Within the enclosing tags, wikitext is parsed as normal and additional <EmailForm> tags are used to supply arguments such as <emailform from=40 /> to insert a textfield "from" with a column width of 40.

The tag <emailform result> begins the definition of the result wikitext. All subsequent <EmailForm> tags insert the values posted by the user so that the message variables can be verified.

The "sendto" argument (<emailform sendto="noreply at kenny lucius dot com" />) defines the email address to which the message is sent. It can be written in natural language to deter email harvesting via the "view source" page. For instance "me at my company dot com" is converted to me@mycompany.com by replacing " at " and " dot " to "@" and "." respectively, and by removing all spaces. This site provides extra security from harvesters with the KLNoSourceView extension.

The opening <EmailForm> tag may contain arguments, as shown in the example.

Pre-filling fields

Fields defined in the form may contain the parameter “prefill” to insert default text into the field. For example <emailform subject=40 prefill="A Subject" /> will pre-fill the field with “A Subject”.

If the user is logged in, the form will attempt to pre-fill the fields name and from with information from the user’s profile. This is overridden by pre-fills defined in the form.

Linking to the form’s page

Linking to the page is no different from any other unless to want to override the pre-fills of some of the fields. The link [[Contact?subject=Hello]] ought to work but it doesn’t. MediaWiki interprets the entire link as an article name, like this: Contact?subject=Hello.

I created an extension that sends parameters to any page. You may use it to send overriding pre-fill parameters like this: {{#linkparam:Article | url parameters | linked text }}. For example, this little link is done with the following code.

 For example, {{#linkparam:Contact
| subject=Just testing the link
  & message=Kenny,

I tested the link. It worked. If you’re reading this, I actually sent the message instead of canceling.
| this little ''link''}} is done with the following code.

The extra returns in the message become part of the message. Other returns simply make it easier to read the code. Remember: only use ampersands to dividing the URL parameters—never use them in your message.

Examples

Nothing clarifies like an example, so here are a few.

Basic structure

The first example is extremely basic but clearly illustrates the basic tag structure.

  • <emailform sendto="noreply at kenny lucius dot com" >: Opening tag and set “sendo” to noreply@kennylucius.com
    • <emailform name=40 /> : The textfield “name”, 40 characters wide.
    • <emailform from=40 />: The textfield “ from”, 40 characters wide.
    • <emailform subject=70 /> : The textfield “ subject”, 40 characters wide.
    • <emailform message=70x8 /> : The textfield “ message”, 70 characters wide and 8 rows high.
    • <emailform submit="Send Email" />: The submit button containing the text "Send Email".
    • <emailform result>: What follows is what the user sees after the message is sent. Form fields in this section print the submitted values instead of the form field.
      • <emailform name /> &lt;<emailform from />&gt;: This prints the submitted name and from in such a way as to look like Kenny <noreply@kennylucius.com>
      • <emailform subject />: This prints the submitted subject.
      • <emailform message />: This prints the submitted message.
  • </emailform>: Closing tag ends the definition of the email form.

That should explain the process adequately, but you wouldn't want to use it as-is.

A real example

The following example uses a table to format the fields so that:

  • There is some introductory text to explain the purpose of the form. It is with the <EmailForm> but outside <EmailForm result> so that it shows with the form and not the result.
  • Each field is identified.
  • Some fields are marked optional or required as desired.
<div style="border:solid black 1px;padding:0 1em;background:#def">
<emailform sendto="noreply at kenny lucius dot com" >
Use the form below to send an email to Kenny. Be sure to include your email address.
 {| 
 |align="right" valign="top"|Your Name: || <emailform name=40 /> (optional)
 |-
 |align="right" valign="top"|Your Email: || <emailform from=40 /> (required)
 |-
 |align="right" valign="top"|Subject: || <emailform subject=70 prefill="Hi, Kenny"/> 
 |-
 |align="right" valign="top"|Message:
 | colspan="2" | <emailform message=70x8 />
 |-
 | colspan="3" align="center" | <emailform submit="Send Email" />
 |}

<emailform result>
Thank you for your comments. The email has been sent.
 {| 
|-
|style="border:solid gray 1px;border-collapse:collapse;padding:0.5em 1em;"|
'''From:''' <emailform name /> <<emailform from/>>

'''Subject:''' <emailform subject />

'''Body:''' <emailform message />
|-
|}
</emailform>
</div>

The previous wikitext is displayed below. Since it is set to go to a dummy address, feel free to type some things into the fields and submit it. After you submit it, you will be returned to this page and the result will show here. You’ll have to scroll down to see the result, so remember to put the form at the top of your contact page so the user won’t have to scroll.

Use the form below to send an email to Kenny. Be sure to include your email address.

Your Name: (optional)
Your Email: (required)
Subject:
Message:


Code

The PHP code for this extension is posted here.

 
Personal tools