Hand Coded Forms
This page explains how to create a custom subscription form in pure HTML. Newsletter automatically generates subscription forms using its short codes, but designers may want to totally restructure a subscription form to obtain better user experience.
An HTML version of the generated form is available on “Subscription forms” panel and that code reflects exactly the form configuration. You can start from that code an move further.
Custom forms can be pasted directly in a page or in the theme code or in a text widget, or they can be stored in the forms repository of Newsletter (see the “Subscription forms” panel) and recalled with short codes.
Recall a stored form on posts
The short code [newsletter_form] can be used to recall a stored custom form adding the form number you need: [newsletter_form form="X"] (where X is the form number).
Hand coding the form
To do that you need HTML skills and knowledge on HTML forms.
To help in this task, Newsletter (since version 3.0) has a special panel where to get and copy the pre-generated form, created following the setting of the form fields panel. The simple and straight format should be easy enough to elaborate it.
The field names
One of the most common mistake on hand coded forms, are the field names. Newsletter 3.0 introduced some simplifications, removing the need of hidden fields, but the fields names has been kept for compatibility.
An example of field is:
<input type="text" name="ne" value="" size="40">
The “name” attribute is what really matters. HTML 5 introduced some new types, like email, with the ability to auto validate and those new features will be included on newsletter on future versions.
Here a list of field names. Only the email field, named “ne”, is required, since the simplest form you can use if the one with only an email address.
- ne – the subscriber email
- nn – the subscriber complete name or first name
- ns – the subscriber last name
- nl (combined with a value) – represent a preference
- npX – the subscriber profile number X
- nx – the subscriber sex (valid values are m, f, n)
- ny – for the privacy acceptance check box (the alert is shown only if the privacy checkbox is active on subscription form configuration panel)
The field(s) named nl (newsletter list, now preferences) must be check boxes with this format.
<input type="checkbox" name="nl" value="X">Preference name
The field value X must be a preference number and that preference must be set as active on form fields panel (either as to be collected on profile edit page or on subscription form). There is a reason for that: a preference marked as not active can still be used by administrators to classify users and to send emails to ones with that “private” preference active – but such a private preference should never be modifiable by subscribers.
The profile fields, npX, are always stored as texts so a text type field is perfect. You can even use a select (drop down list) HTML field as is configurable on form fields panel. Here some examples for profile fields (on example we suppose to collect the profile number 1 so we use the name np1).
As a normal one line text:
<input type="text" name="np1" value="">
as a textarea
as select (drop down list)
<select name="np1"> <option value="red">I love red</option> <option value="red">I love red</option> </select>
Be warned: if you let subscribers to edit their profile fields on profile edit page, remember that profile edit page is always generated so you should configure the fields to be generated on a compatible format than what presented on subscription form. Of course, if you use the generate subscription form there should no problem.
A complete form need the <form> tag with an action attribute. The action attribute, since version 3.0, points always to a newsletter plugin file:
http://www.domain.tld/wp-content/plugins/newsletter/do/subscribe.phphttp://www.domain.tld/?na=s (since version 3.9)
My suggestion is always to start from the generated form code you can find on subscription panel: configure adequately the form fields and then start from the generated code to obtain your final complete form.
Where can I use a form?
Is there a best practice?
In my humble opinion, less is better. Ask for email, may be for the name, may be let the user to choose some preferences, but do not make your subscription module as a tax refund request form!
After the user is subscribed and confirmed, you can show the profile editing form and ask him to give you some more data.
Adding lists without user explicit selection
If you want to force every new subscriber with some preference, you can set that on subscription panel: Newsletter will take care to add those preferences to the new subscriber. If you even expose those preferences and the users does not select them, their are added anyway.
A second case is when you code a form by hand and want users which subscribe on that form to have a preference set. That is like the list concept of email marketing services. To force the user which subscribe in a particular form to have a specific preference, you can add an hidden field that activate it:
<input type="hidden" name="nl" value="X">
where X is the preference number.
Since you may have old subscriber interested on that activity, you should not count of them to re-subscribe to your blog, but mail them inviting to change their profile and activate that preference. Of course more than one hidden field can be added to “point” more than one preference.
Anyway, regular automated setting of preference should be made configuring the subscription process on administrative panels.