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. Basically, when you need to insert a form on a page, all you have to do is to add the shortcode [newsletter_form] and 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 explained
- Shortcode attributes
- The Minimal Form
- Advanced features: create the form using the field shortcodes
- Labels and placeholders
- Lists
- All supported field names
- Styling the form
The [newsletter_form] shortcode explained
There are different 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 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
[newsletter_form]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
[newsletter_form], 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 [newsletter_form] accepts some custom attributes to change the default behavior (the same attributes are supported by the [newsletter] shortcode, used in the Newsletter dedicated page, but do not replace that shortcode, otherwise, service messages will not be displayed).
Shortcode attributes
The following parameters (attributes) can be used to change the default behavior:
- 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
listsattribute and the work is done (e.g.[newsletter_form list="1"]or[newsletter_form lists= "1,4"]). Visit the page dedicated to lists for more information. - 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
listattribute, which is only used to force the subscription to one or more lists. - 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).
- 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. 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, 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.
- 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
singleanddouble. - button_color – the color of the submit button, eg, #ff0000.
- id – the form id attribute
If you need complex forms, you can use other more flexible shortcodes described later on this page. 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”]
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:
[newsletter_form type="minimal"]
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.
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 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.
Note: this kind of form supports only the standard HTML5 form validation.
To create a minimal 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!"] [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 the switch the two fields to ask first the name and then the email.
Labels and placeholders
To show a placeholder inside the field, you can use the attribute placeholder. If you want to disable the external text label, you can set it to an empty value. For example in the form below, the field email is shown the “Your best email” placeholder and no label. Placeholders are a feature of HTML 5 supported by substantially every browser.
[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]
Extra fields
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"] [/newsletter_form]
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 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
- 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"]
Read more about it on this page.
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.