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 user to insert subscription forms in landing pages, widgets and posts. Basically, when you need to insert a form on a page, all you have to do is to add the shortcode 

 and our plugin will automatically display a form with the fields and options you have chosen from the settings (detailed information below).

1. The
shortcode explained

There are different options to insert those forms on your site, as landing pages, widgets, posts, popups and top/bottom bars. We created a specific shortcode, 

, 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 to address your readers to subscribe. Remember that also the Newsletter dedicated page can be used as a landing page, but remember that that page shows also all the service messages. To add a subscription form to a landing page you just have to insert the shortcode 
     and Newsletter 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 on your post. If you use other composers, you should use the shortcode 
    , as this option works with every visual composer. If you want, you can add the form automatically on each post by using a plugin that injects ads in your blog, as they usually support shortcodes (for example, you could use Head and Footer plugin). 

The shortcode 

 accepts some custom attributes to change the default behavior (the same attributes are supported by the 
 shortcode, used in the Newsletter dedicated page, but do not replace that shortcode, otherwise service messages will not be displayed).

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

  1. list – this attributes gives you the chance to insert a subscriber by default in a specific list when he subscribes. You just have to add the number (or numbers) of lists to be set by default by using the lists attribute and the work is done (e.g.
    ). Visit the page dedicated to lists for more information.
  2. lists_field_layout – this parameter, if set to “dropdown”, allows to change the default layout of lists on the subscription form from checkbox to dropdown. This shortcode is not connected to the lists specified with the list attribute, which is only used to force the subscription to one or more lists. 
  3. 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. 
  4. lists_fields_label – this is the label shown in the form just before the list selection field (both checkbox and dropdown).
  5. confirmation_url – with this attribute you can specify an alternative URL where the subscriber will be redirected instead of the standard confirmation message. 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.
  6. 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, the Facebook Extension uses “facebook” 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. 
  7. optin – this overrides the opt-in mode set on subscription configuration page IF the override is enabled. Values can be single and double. Values can be single and double.
  8. button_color –  color of the submit button, eg, #ff0000.

If you need complex forms, you can use other more flexible short codes described later in this page. An easy example on 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”]

2. The Minimal Form

There is a minimalist version of the subscription form, made just by an email field and a submit button both on a single line. You can trigger this form by using the following shortcode: 

This post can be used at the end of a post where you can invite your readers not to miss any news by subscribing to your newsletter.

3. Advanced features: create the form using the field shortcodes

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

, 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. On this section you will find some examples on how to use shortcodes to personalize your forms.

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

To create a minimal form, you can use:

[newsletter_field name="email"]

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

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

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 on a single line. You should deactivate the submit button of the general form by setting the “button_label” to an empty string on the [newsletter_subscription] shortcode. 

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"]

We could also decide the switch the two field to ask first the name and then the email. 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"]

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"]

A visible preference 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"]

Field shortcodes support even the extra 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"]

The label is optional and the kind of field depends on its configuration on 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 with a 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"]

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

The supported field names are:

  • 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.

4. 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"]

Read more about it on this page.

5. Special (old) uses

The shortcode 

 can even be used to recall saved HTML forms with the syntax 
, where “x” is a number from 1 to 10.

An correspondent version of this short code 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 short code to recall a stored custom form.