This page explains how to create a custom subscription form in pure HTML. Newsletter automatically generates subscription forms by using shortcodes, but designers may want to totally restructure a subscription form to obtain a 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 and 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 shortcodes.
1. 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 format we provide should be easy enough to elaborate.
To recall a stored custom form you have to use the shortcode
[newsletter_form] by adding the form number you need:
[newsletter_form form="X"], where “X” is the form number. Read more about forms and shortcodes.
2. The field names
One of the most important issues when dealing with custom forms is the field names. They also are common mistakes on hand-coded forms, so pay extra care to this aspect. Newsletter 3.0 introduced some simplifications, removing the need for hidden fields, but the names of the fields 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 in Newsletter on future versions.
Here you have a list of field names. Only the email field, named “ne”, is required, since the simplest form you can use is 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 gender (valid values are
ny– for the privacy acceptance checkbox (the alert is shown only if the privacy checkbox is active on the subscription form configuration panel)
The field(s) named
nl (as is this is exactly the field name required by PHP) must be checkboxes 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 the form fields panel (either as to be collected on the profile edit page or on the 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 the ones with that “private” preference active – but such a private preference should never be modifiable by subscribers.
You can even make that field hidden to set the list automatically for a subscriber who uses that particular form. In this case, the list X must be set as public.
<input type="hidden" name="nl" value="X">
The profile fields, npX, are always stored as texts so a text type field is perfect. You can even use a select (dropdown list) HTML field as it is configurable on the form fields panel. Here some examples of profile fields (for 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 (dropdown list)
<select name="np1"> <option value="red">I love red</option> <option value="red">I love red</option> </select>
- If you let subscribers edit their profile fields on the profile edit page, remember that the profile edit page is always generated, so you should configure the fields to be generated in a compatible format as the one presented on the subscription form. Clearly, if you use the subscription form generated by Newsletter, there should no problems.
- A complete form needs 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)
3. Frequently asked questions and some best practices
Where can I use a form?
Is there a best practice?
Generally, to keep the process smooth, it may be worth asking for less information on the subscription form. Ask for email, maybe for the name, maybe let the user 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.
Can I add subscribers inside a list automatically on subscription?
Of course. If you want to insert every new subscriber inside a list, you can set that on the subscription panel. Newsletter will take care to add those preferences to the new subscriber. If you even expose those preferences and the users do not select them, they are added anyway.
You can refer to the lists documentation page for more information.
A second case is when you want a subscriber using a specific form to be added to one or more specific lists (without showing them), in order to distinguish people coming from that form from the other subscribers. In this situation you have to add a special hidden field to the HTML form:
<input type="hidden" name="nl" value="X">
where “x” is the number of the list where you want to add the new subscriber. If you need to add more than one list, just add more of those hidden fields, changing the “x” value.
Important: note: those “forced” lists must be configured as public lists, otherwise they will be ignored.
Can I change the opt-in method in a custom form?
You can override the global opt-in method selected on the subscription configuration page by using a special hidden form field. That works only if you enable the opt-in override on subscription main settings.
For example, to force the opt-in method to be “single” you can add the following line:
<input type="hidden" name="optin" value="single">