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

A general short code [newsletter] is defined and used 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.

Many plugin users 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 display.

This short code 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.

Custom attributes

The [newsletter_form] and the [newsletter] short codes accept few custom parameter to change the default behavior.

  • confirmation_url – is an alternative URL where the subscriber is redirected instead to show him the confirmation required message or to be redirected to the custom confirmation required page configured in the subscription steps panel. 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)

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 must wrap all other short codes which are then rendered as single form fields.

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
  • surname or last_name
  • gender
  • preference or list (with the number attribute)
  • preferences or 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).