User guide

HolmesPortfolio Forms

How to build a form, put it on a page, and handle what people send in. Work through the quick start first, then use the rest as a reference.

Overview #

A form is a set of fields arranged on one or more pages. You build it in the visual editor, then place it on any page or post with a shortcode or a block. When someone submits it, the plugin can email the answers to one or more people, show the person a thank-you message, and keep a copy in Entries.

Forms follow the GOV.UK Design System by default, so they look consistent and work with a keyboard and a screen reader. You can switch to Bootstrap or to your own theme's styling in Settings.

A fresh install starts with four ready-made forms — a Simple enquiry form, a Freedom of Information request, a Subject Access Request and a Make a complaint form. Open any of them to see how the pieces fit together, or copy one as a starting point. See The forms you start with.

Quick start #

Put a form on a page #

Every form has a shortcode. Find it on the Forms list, or on the builder screen after the first save.

[hpf_form id="123"]

In the block editor you can instead add the HolmesPortfolio Form block and pick the form from a dropdown — no id to copy. The form renders the same either way.

The builder screen #

Select two or more fields and save them together as a named preset to reuse on other forms.

The ? help dots #

Every field and every setting in the builder has a small ? to its left. Click it for a one-line explanation, plus a Read more in the guide link that opens this page at the part that covers it. There is one on the Computed variables heading too.

The Read more links open the online user guide at holmesportfolio.co.uk/holmesportfolio-forms. The ? dots show their one-line text with or without a connection.

Fields #

Every field shares the options in Every field's common options. The tables below cover only the settings specific to each type.

Text #

A single-line box. Use the input mode to collect an email, phone number, web address or number.

Text area #

A multi-line box for longer answers.

Radio buttons #

Pick one from a short list. The list is a group, so the Label becomes its legend — always fill it in.

Checkboxes #

With no options, it's a single yes/no tick (good for “I agree”). Add options and it becomes a “choose any” list.

Dropdown #

Pick one from a longer list. Options work the same as radio buttons, including Pre-select from the query string. Set a field width to stop a long list stretching the box.

Slider #

A number chosen on a track, with a matching number box. A slider always has a value, so “required” does nothing for it.

Date #

Three boxes — day, month, year — following the GOV.UK pattern.

Address #

Line 1, optional line 2, town, optional county, and postcode. Line 1, town and postcode are required once anything is typed, and the postcode is checked against the UK format. After the visitor fills it in they can press Save address to collapse it to a read-only summary, with a Change address button to reopen it.

File attachments #

Drag-and-drop or browse for files. Files are attached to the email only — they are never saved on the server or in Entries. The first time you add this field the builder shows a short note about handling uploads safely; tick “don't show this again” once you have read it.

Handling uploads safely

An accepted file type is not the same as safe contents — a genuine PDF or image can still carry something harmful, and checking and handling what people send is your responsibility as the site owner. Any email that carries uploads ends with a short line reminding whoever receives it to scan the files and only open ones they were expecting. On each email action you can turn Attach files uploaded through the form off — useful for a copy sent back to the person who filled in the form. Route form mail through a gateway that scans attachments (Microsoft 365 and Google Workspace both do) and keep readers patched.

Content & controls #

Alert / notice #

A block of text on the page — guidance, a warning, or something to agree to. Basic HTML is allowed in the text. It is read out to screen readers along with the fields.

Built-in presets

Three presets ship with the plugin and can't be deleted:

• Privacy notice and Terms and conditions — each is one alert with its “confirm you have read this” checkbox turned on, so the visitor can't submit until they tick it. Both carry placeholder wording you must replace: the builder shows a red reminder on the alert, and the words “replace before publishing” appear in the text. Change the text and the example.com link before the form goes live.
• Customer contact — a ready-to-use name, email and phone group, nothing to change.

Pick one from the Find a preset… box under the field list and press Insert. Whether each built-in appears there is set once for the whole site in Settings → Presets. A confirmed alert shows as Yes in the answers summary, emails and the CSV export.

Hidden field #

Not shown to the visitor, and nothing about it is written into the page — the value is worked out on the server at submit and included in the entry, the emails and the answers summary. Use it to record where an enquiry came from, to copy an answer, or to calculate something.

Navigation button #

One button component that does different jobs by its action: Continue to the next page, Back to the previous one, or Submit the form. A Back button appears on its own whenever there is a previous page, so you rarely need to add one. Leave the label blank to use the default for the action.

Email action #

Sends an email when the form is submitted. Add as many as you need — each one on an in-scope page fires. Mail goes out through WordPress's wp_mail(), so how much actually gets delivered depends on your host and mail setup, not the plugin. See Emails for the detail.

Submit message #

What the visitor sees after a successful submit, in place of the form. HTML or plain text. Supports the same tokens as an email, including [reference].

Answers summary #

A “check your answers” block. Put [all-fields] in its editable template and it expands to the answers grouped by page, each group with a Go to… button back to that page. Adding this component replaces the automatic review step.

Every question on a shown page appears here — an unanswered one is left blank. A question or page hidden by a rule does not appear at all. A confirm alert shows Yes / No; a multi-select checkbox lists each option with Yes or No; a radio or dropdown shows just the chosen option.

Conditional container #

A box you drag fields into. Give the box a show/hide rule and everything inside appears or disappears together. When it's hidden, the fields inside leave the page and their answers are cleared from the entry and the emails.

Repeatable Pro — with the paid add-on active, the container's options gain a Repeatable tick, plus a fewest / most count and the wording for an “Add another” button. The visitor then fills the group in as many times as they need. Only plain question fields repeat (text, choices, date, address) — not alerts, buttons, email actions or summaries. Each entry is numbered #1, #2 … with every field's label in the answers summary, the email and the stored record.

Every field's common options #

Confirm a field #

The Must match another field setting on a Text field blocks submit unless it is typed identically to another field. Trailing spaces are ignored. It works for any pair — an email typed twice, a reference confirmed — not just email.

Pre-fill choices from the query string #

Turn on Pre-select from the query string on a radio, checkbox or dropdown field and each option gains a small query string match box. When the form loads, it looks through the query string (everything after the ?); if an option's match text appears anywhere in it — case-insensitive — that option is selected. Blank match means look for the option's stored value itself. The query string is captured once and kept with the form's draft, so the pre-select still works after moving to a later page. A real answer the visitor picks always wins.

The match text is only ever used to pick one of the field's own options; nothing from the query string is shown on the page or saved with the entry, so a crafted link can at most choose a legitimate answer.

Multi-page & conditional pages #

Add pages with the + tab. Each gets a Continue button automatically, and a Back button whenever there is a previous page. Give every page a title — it becomes the page heading a screen reader announces and names the step in the progress text.

A page can have its own show/hide rule, set on the Logic tab. A page whose rule fails is skipped entirely: its fields aren't shown, aren't required, and its email actions don't fire. The step count adjusts — a visitor who skips a page sees “Step 2 of 3”, not “of 4”.

Variables & calculations #

Both a computed variable (on the Logic tab) and a hidden field set to “a calculation” work from other answers. They never appear on the form and nothing about them is sent to the browser; use them in rules, tokens and email content. A variable is referenced as {var:key} in formulas and [key] in tokens.

The formula box #

Type a calculation left to right, no brackets, no operator precedence — what you type is the order it runs. Insert field and variable names from the chips.

{quantity} * {price} + 5
"Ref " & {order_no}
{start_date} + 7 workdays

For anything that needs a condition — “add 2 only when urgency is high” — switch to the step list under Advanced. Each step has an operator (set to, add, append text, add working days…), a value, and an optional only when condition.

Operators — conditions

Working with dates #

The date maths in a formula, a date default, and the check against another date all read the same shapes: a date field's answer, today, an ISO date like 2026-06-10, or an expression like today + 20 workdays. Results come back as YYYY-MM-DD, which is what a token such as [date_due] prints.

Tokens #

Tokens are placeholders in square brackets that get replaced with real values in email subjects, email bodies and the submit message.

Emails #

Use one Email action per recipient group. A common pattern is one email to the visitor and one to your team.

Under Settings → Email appearance you can add a block of CSS, a header and a footer that wrap every email the plugin sends — a logo at the top, an address or unsubscribe note at the bottom. Leave them blank to send the plain message. Many email clients ignore external CSS, so for a reliable look put inline style attributes in the header and footer HTML.

An email leaves out any question with no answer, so the body only ever shows what was filled in. The check-your-answers page is the opposite — it keeps blank questions so the visitor can see what they skipped.

Add as many email actions as you need — there is no limit in the plugin, and every one on an in-scope page fires on submit. Delivery, though, depends on your site's mail setup, not the plugin. Mail is sent with WordPress's own wp_mail(); on its own that uses the web server's mail program, which often lands in spam because the sending domain is not properly authenticated.

You can also ask internal recipients to add the site's From address to their safe-senders list — that helps their inbox, but it does nothing for the person who filled in the form and cannot rescue mail a receiving server rejects outright.

Entries #

Forms → Entries lists every stored submission. Filter and sort by form. Open one to see all its answers and its reference.

Export to CSV from the toolbar or the bulk actions. The export is one file per form (zipped when you pick several), with the form name in column A and the reference in column B, so a spreadsheet clearly belongs to one form. There is a column for every question in the form, whether or not anyone answered it; an unanswered cell is simply empty. Tick Delete these entries after exporting to clear them straight after the download — you'll be asked to confirm, and only the rows in that export are removed.

Settings #

Accessibility check #

The button at the bottom of the builder shows a running count of problems in the build. Click it for the list, grouped as Errors, Warnings and Notes. Each finding says where it is, what's wrong and why it matters, and how to fix it, with a Go to field link. A count also appears against each form on the Forms list.

It reads the structure only — labels, legends, choices, keys, error messages, autofill. It's a starting point, not a full audit: colour contrast, text zoom, reading age, focus visibility and whether the wording actually makes sense still need a person. The panel lists exactly what it can't check, and links to the W3C guide to accessible forms. It never blocks saving.

Import / Export #

Forms → Import / Export moves forms, the field-preset library and the Settings between sites as a single JSON file. Choose which forms to include; the page shows each one's size and warns if the file is too large to upload elsewhere. Submissions are never included. Up to 250 forms per file.

Spam protection #

Three checks run on every form with no setup: a hidden honeypot field that only a bot fills, a signed timing check (a submit under three seconds or older than a day is rejected), and a per-IP rate limit on submits. Page navigation has its own looser per-IP ceiling. Spam these catch is dropped — not emailed, not stored.

GOV.UK and the NCSC advise against CAPTCHA, so the Additional challenge setting is None by default. Turn on Turnstile or reCAPTCHA only if you have a specific problem; both add a visible challenge and send the visitor's token and IP to that provider.

The forms you start with #

A fresh install creates four forms so there is something working to open, copy or drop on a page. Every email recipient defaults to the site admin address; swap it per form. None of them are set in stone — edit or delete them freely.

The Pro add-on #

HolmesPortfolio Forms Pro is a separate plugin you install alongside this one. It does not replace anything — switch it off and your forms carry on with the free feature set. A licence key entered under Forms → Pro licence unlocks updates and support; the check is soft and never disables a feature you have set up.