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.

A form is nothing else than a piece of HTML and a bit of JavaScript to pre-validate field values. The code generated can be easily copied from the original, reworked and reused elsewhere (we see later where the form can be inserted and how).

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

<textarea name="np1"></textarea>

as select (drop down list)

<select name="np1">
 <option value="red">I love red</option>
 <option value="red">I love red</option>

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/?na=s (since version 3.9)

That should prevent a lot of problems I had with caching plugin or optimizer or request checker interfering with a legitimate process of subscription. Another attribute set on generate for is the “onsubsmit” which recall a JavaScript function to check the field values. Note that JavaScript checking can be bypassed easily but the same kind of validation is made by Newsletter before store the data and, if errors are detected, it show a message and blocks the operation.

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.


If you’re coding a custom form you should even care about user input validation. You can take advantage of the new “required” HTML 5 attribute and the input field types (text, email, number, …). You probably need to add some JavaScript to be executed on form submit as well.

Newsletter injects a little JavaScript with the function newsletter_check(form) which loops between the form fields and checks its validity: you can use it or start from its code to craft your own validation code.

Where can I use a form?

Everywhere, even on external sites. The generated code is complete of all, JavaScript included (with prevention for double inclusion of the same code, stay safe).

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.