Subscription Forms and Shortcodes

On this page, you will find all the information you need to know how our shortcodes work and how you should use them to insert a subscription form on your pages.

Shortcodes are an essential and very versatile feature of Newsletter, as they allow users to insert subscription forms in landing pages, widgets, and posts. When you need to insert a form on a page, all you have to do is to add the shortcode [newsletter_form]: our plugin will automatically display a form with the fields and options you have chosen from the settings (detailed information below).

What's inside

The [newsletter_form] shortcode
Shortcode Attributes
The fields Attribute
The [newsletter_form] single-line version
The [newsletter_field] shortcoded
Labels and Placeholders
Lists
All the public lists at once
All supported field names
Styling the form

Do not use this shortcode on the Newsletter’s public page, that page should contain only the [newsletter] shortcode.

There are several options to insert those forms on your site, like landing pages, widgets, posts, popups, and top/bottom bars. We created a specific shortcode, [newsletter_form /]to allow our users to insert a form where they need it, for example on:

Landing pages. You can create a specific landing page where send your readers to subscribe. Remember that also the Newsletter public page can be used as a landing page, but that page shows also all the service messages. To add a subscription form to a landing page you just have to insert the [newsletter_form] shortcode, and the Newsletter plugin will automatically do the work for you, using the parameters you set during configuration. You can also create different forms on different pages, and for the most advanced users, you can build your own form from scratch.
Subscription forms inside posts. You can easily add a subscription form inside posts. If you use Gutenberg as editor, you just need to find the Newsletter custom block and add it to your post. If you use other composers, you should use the [newsletter_form /] shortcode, as this option works with every visual composer.

The shortcode [newsletter_form] accepts several attributes to change the default behavior. An attribute is specific by writing the shortcode as [newsletter_form attribute="attribute-value"].

Even if not strictly required, a shortcode should be used with the syntax [newsletter_form /], with a trailing /, except when it “wraps” some content, as exemplified later.

Shortcode Attributes

The following attributes can be used to change the default behavior:

lists – a comma-separated list of list IDs to which the subscriber should be automatically added. Only public lists are supported. Examples: [newsletter_form list="1" /], [newsletter_form lists="1,4" /]. Visit the page dedicated to lists for more information.
lists_field_layout – this parameter, if set to “dropdown”, allows changing the default layout of lists on the subscription form from checkbox to dropdown. This shortcode is not connected to the lists specified in the lists attribute.
lists_field_empty_label – if you choose to show the lists on a subscription form as a dropdown, this is the predefined label shown on the dropdown field. You should personalize it and it could be something like “Choose…”, “Select a…” and so on.
lists_field_label – this is the label shown in the form just before the list selection field (both checkbox and dropdown).
show_labels [true/false] – if set to false the field labels won’t be shown
welcome_page_id – The ID of a WordPress page to be used as a welcome page (immediately with single opt-in or after confirmation with double opt-in
confirmation_url – specifies an alternative URL where the subscriber will be redirected after the subscription. If you use the single opt-in, this URL becomes the welcome page. The confirmation URL can contain tracking parameters, like the Google Analytics one, to track different forms. Setting it to “#”, the current page URL is used.
referrer – this is a textual value that can be used to specify a custom referrer to identify the subscription form. For example, the widget uses “widget” as the referrer, and so on. Statistics by referrer are available under the subscribers’ management panel. This referrer must not be confused with the HTTP referrer, which is also stored.
optin – this overrides the opt-in mode set on the subscription configuration page IF the override is enabled; values can be single or double.
button_color – the color of the submit button, eg, #ff0000.
button_radius – is the corner radius for the submit button, eg. “10px”. Remember to ass the unit (px, em, …)
button_label – is the label for the submit button. If not set the default label is used (the one set on the main form configuration)
id – the form id attribute
show_placeholders – if set to “false” the placeholders are not shown
autoresponders – comma-separated list of autoresponder/email series to activate (the Autoresponder addon is required)

The HTML code produced by the shortcode has this structure and the styles are provided with the style.css general file of the Newsletter plugin. Do not change that file! You can add more styles using the custom CSS styles option on the Newsletter’s general settings or adding them to your theme.

<div class="tnp tnp-subscription ...">
  <form id="...">
    (...fields...)
  </form>
</div>

An easy example of how to use shortcodes is the following, where lists are shown as a dropdown with a personalized label:

[newsletter_form lists_field_layout="dropdown" lists_field_empty_label="Select..." lists_field_label="Our topics” /]

If you need complex forms, you can use other more flexible shortcodes described later on this page.

The `fields` Attribute

With this attribute you can specify the fields you want to show, and their order. The submit button is always added at the end.

Example: [newsletter_form fields="first_name, email, privacy" /]

The complete list is:

first_name – the first name field
last_name – the last name field
email – the email field
gender
lists – the set of lists configured on the general subscription form configuration
privacy – the privacy checkbox
customfields – the set of custom fields configured on the general subscription form configuration

If the email field is not specified, it is added automatically as the first field of the form.

The `[newsletter_form]` single-line version

There is a “single line” version of the subscription form that displays the email field, optionally the name field, and a submit button on a single line.

[newsletter_form type="minimal" /]

This shortcode can be used at the end of posts to invite readers to subscribe.

There are attributes specific to the minimal form:

show_name – set to “true” the name field is shown and the width of the fields is set to 1/3 to fit in a single row
button_* – all button attributes as explained in the [newsletter_form] shortcode description
placeholder – is the placeholder text for the “email” field
name_placeholder – is the placeholder text for the “name” field
class – any CSS class to add to the <div> surrounding the <form> tag
referrer – it’s a text, default “minimal”, recorded with the subscriber’s data for statistical purposes
align – to align the fields (left, right, center)
id – the form HTML id
optin – this overrides the opt-in mode set on the subscription configuration page IF the override is enabled; values can be single or double
lists – a comma-separated list of subscription list IDs to which the subscriber should be automatically added. Only public lists are supported. Examples: [newsletter_form type="minimal" lists="1" /], [newsletter_form type="minimal" lists="1,4" /]
confirmation_url – with this attribute you can specify an alternative URL where the subscriber will be redirected after the subscription. If you use the single opt-in, this URL becomes the welcome page. The confirmation URL can contain tracking parameters, like the Google Analytics one, to track different forms. Setting it to “#”, the current page URL is used.
autoresponders – comma-separated list of autoresponder/email series to activate (the Autoresponder addon is required)

The produced HTML is:

<div class="tnp tnp-subscription-minimal ...">
  <form id="..." style="text-align: ...">
    (...fields...)
  </form>
</div>

and the main styles are provided with the style.css general file of Newsletter. You can add more styles using the custom CSS styles on the Newsletter main settings or adding them to your theme.

The [newsletter_field] shortcoded

Newsletter offers a set of shortcodes that can be used to build a form from scratch, organizing the order of the fields without the need to deal with HTML code.

The main shortcode is always [newsletter_form], and it detects if you wrote other shortcodes in its body. If you did, it will render those codes instead of generating the standard form. In this section, you will find some examples of how to use shortcodes to personalize your forms.

To use the field shortcode, you need to open the form with [newsletter_form] (without a trailing /) and then close the form with [/newsletter_form].

Note: this kind of form supports only the standard HTML5 form validation.

To create a simple form, you can use:

[newsletter_form]
    [newsletter_field name="email"]
[/newsletter_form]

Button and field labels are taken from the form configuration but you can specify alternative values:

[newsletter_form button_label="Go!" button_color="#223344"]
    [newsletter_field name="email" label="Your best email"]
[/newsletter_form]

The email field has a special attribute, “button_label”: if set, a submission button is shown just near the input field, so that the form is on a single line. You can deactivate the submit button of the general form by setting the “button_label” to an empty string on the [newsletter_form] shortcode: in this case, the submission is triggered by the “enter” button on the keyboard or equivalent button on mobile virtual keyboards.

Now we want to collect even the name of the subscriber:

[newsletter_form button_label="Go!"]
    [newsletter_field name="email" label="Your best email"]
    [newsletter_field name="first_name" label="Your name"]
[/newsletter_form]

We could also decide to switch the two fields to ask first for the name and then the email.

Labels and Placeholders

Placeholders are shown automatically using the value configured on the main subscription form configuration. They’re empty by default.

If they’ve been set and you don’t want to show them, use the “show_placeholders” attribute of the [newsletter_form] shortcode to disable them.

If you want to set them individually for each field, you can use the “label” and “placeholder” attributes opportunity combined. Both can be set to an empty value to “disable” them.

[newsletter_form button_label="Go!"]
    [newsletter_field name="email" label="" placeholder="Your best email"]
    [newsletter_field name="first_name" label="" placeholder="Your name"]
[/newsletter_form]

Lists

What about a specific list preference among the ones configured in the form configuration?

[newsletter_form button_label="Go!"]
  [newsletter_field name="email" label="Your best email"]
  [newsletter_field name="first_name" label="Your name"]
  [newsletter_field name="list" number="2" label="Marketing news"]
[/newsletter_form]

The label for the list is optional, if not specified the main form configuration is used. You can even decide to force the list preference, so the user is automatically added to that list (useful to make different forms for different kind of subscriptions).

[newsletter_form button_label="Go!"]
  [newsletter_field name="email" label="Your best email"]
  [newsletter_field name="first_name" label="Your name"]
  [newsletter_field name="list" number="2" hidden="true"]
[/newsletter_form]

A visible list can be pre-checked:

[newsletter_form button_label="Go!"]
[newsletter_field name="email" label="Your best email"]
[newsletter_field name="first_name" label="Your name"]
[newsletter_field name="preference" number="2" label="Marketing news" checked="true"]
[/newsletter_form]

All the public lists at once

A special field name is lists (plural) and it displays all the public lists.

[newsletter_field name="lists"]

By default, a set of checkboxes is shown, but you can use some attributes to change the behavior:

layout – set it to “dropdown” to have a single list selection
first_option_label – to add a “first option” to the selection, like “please select a list”

Custom fields

Field shortcodes support even the custom profile fields, here you have an example:

[newsletter_form button_label="Go!"]
[newsletter_field name="email" label="Your best email"]
[newsletter_field name="first_name" label="Your name"]
[newsletter_field name="profile" number="1" label="City"]
[/newsletter_form]

The label is optional and the kind of field depends on its configuration on the main form configuration panel. You can have simple text fields and selection fields.

If you need to bind a form with one or more lists, you can add them using the special attribute lists (remember those lists must be set a “public”):

[newsletter_form button_label="Go!" lists="1,2"]
[newsletter_field name="email" label="Your best email"]
[/newsletter_form]

As you can see from the last example, the lists attribute accepts a comma-separated list of list numbers.

All supported field names

email
name or first_name
surname or last_name
gender
list (with the number attribute) shown a single list checkbox
lists: displays all lists set to be shown in the subscription form
profile (with the number attribute)
privacy (with optional URL attribute to provide a different privacy URL)

The submission button is added automatically.

Styling the form

You can use the extra CSS field available in the configuration panel to personalize your form. If you need to add an extra class to the form, you can use the class attribute:

[newsletter_form class="my_css_class"]

Special (old) uses

The shortcode [newsletter_form] can even be used to recall saved HTML forms with the syntax [newsletter_form form="x"], where “x” is a number from 1 to 10.

A correspondent version of this shortcode where only PHP is available is the function “newsletter_form()” that should be used in this way:

if (function_exists('newsletter_form')) newsletter_form();

The function accepts even a parameter, from 1 to 10, like the shortcode to recall a stored custom form.