Form Shortcodes

The easy way to create a subscription form to build your contact list is to use the Newsletter’s provided short code and let it to generate the form (for advanced users there is a guide to build the form from scratch).

The [newsletter] shortcode

A general short code [newsletter] is defined and used only on the Newsletter’s dedicated page (see the subscription configuration) to show the messages (confirmation, welcome, goodbye and so on) but as default behavior it shows a subscription form and it generally behaves as the next described short code.

So the page with this short code can be actually used as subscription page, not only as a service page.

The [newsletter_form] shortcode (the one you should use)

Many blog owners prefer to have separated subscription and messages pages so they build a dedicated “landing page” for subscription and use the short code [newsletter_form] where the form should displayed. Sometime they have more than one subscription page or thay want to show a subscription form at the end of each post. This short code is the one to be used.

The short code [newsletter_form] supports a number of parameters (attributes) explained below to change the default behavior.

Custom attributes

The [newsletter_form] accepts few custom parameter to change the default behavior. If you use the dedicated page where there is the [newsletter] short code, the same parameters can be used.

  • lists – is a comma separated list of list numbers to be used as default for each subscription. Every user which subscribes using that form will be added to those lists. The specified lists must be “public”, not marked as “private use”. Usually you don’t want to show the option to selected a list if you’re setting it as default for a that form, so you should mark it as “public but only on profile editing form”. See the list configuration panel.
  • lists_field_layout – can be set as “dropdown” to show the available lists on subscription as a dropdown control instead of a set of checkbox. It is not connected to the lists specified with the lists attribute which is only used to “force” those ones.
  • lists_field_empty_label – when list selection is shown as a dropdown, this value is the predefined label shown in the dropdown field. Since it’s require to select a list from the dropdown, that label should 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 (being it a set of checkbox or a dropdown selector).
  • confirmation_url – is an alternative URL where the subscriber is redirected instead to show him the standard confirmation required message. If single opt-in is used this URL becomea the welcome page. The confirmation URL can contain tracking parameters, like the Google Analytics one, to track different forms.
  • referrer – is a textual valued stored as referrer for the subscription. For example the widget uses “widget” as referrer, the Facebook Extension uses “facebook” and so on. Statistics by referrer are available under the subscribers management panel. This referrer is not the HTTP referrer, which is store also.
  • layout – the only accepted value is “table” which forces Newsletter to generate the old table form (since version 4.7 the default is a table-less  and responsive form). It will be removed in the near future.

If you need complex forms, you can use other more flexible short codes described later in this page.

An example where the lists are shown as a dropdown with labels set is:

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

Special uses

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

The minimal form

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

[newsletter_form type="minimal"]

This form can be used at the end of a post, for example, where you can invite your reader to not miss any news subscribing your newsletter.

Shortcodes to freely build a form

The Newsletter plugin offers a set of short codes that can be used to build a form organizing the field order without the need to deal with HTML. The main short code is always [newsletter_form] which in turn detects if there are other short codes in its body to be rendered instead of generate the standard form.

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

For example, to create the simplest possible 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 side by side with the input field to create a single line form. You should deactivate the general form submit button setting the “button_label” to an empty string  on the [newsletter_subscription] short code.

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]

and of course we can decide the switch the two field to ask first the name and then the email. What about a specific preference between 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 make a list hidden, so the user automatically has it added to his profile (useful to make different forms for different kind of subscription, like lists).

[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 preference can be pre-checked, eventually:

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

Field short codes support even the extra profile fields.

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

Of course 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 (preferences), you can add them with a special attribute “list”:

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

which accepts a comma separated list of list numbers.

Common field names

The supported field names are:

  • email
  • name or first_name
  • surname or last_name
  • gender
  • list (with the number attribute)
  • lists: displays all the configured preferences
  • profile (with the number attribute)
  • privacy (with url attribute to provide a different privacy url)

The submission button is added automatically.

Styling the form

To style the form you can use the extra CSS field available in the subscription configuration panel. You can read more in this page. If you need to add an extra class to the form, you can use the class attribute.

[newsletter_form class="my_css_class"]

Special form attributes

The confirmation_url attribute lets to specify a custom confirmation URL to redirect the subscriber to as alternative to show the standard confirmation message. If you use the single opt-in mode, that URL is used as welcome page as well, since there is no confirmation step.

The referrer attribute can be used to specify a custom referrer to identify the subscription form (for example Newsletter uses “widget” for the subscription form generated by a widget or “facebook” for subscription coming from the Facebook Extension).