PostBox Pro / Documentation

PostBox Pro — Documentation

Powerful multi-step forms for Joomla 5 & 6.

Documentation for PostBox Pro 1.3.2.

PostBox Pro extends the free PostBox component with multi-page forms, conditional field logic, calculated results, file uploads, a submission review step, and auto-save — all without jQuery and with no third-party dependencies. A built-in import tool migrates your existing PostBox forms in one step.

PostBox Pro admin dashboard showing total forms, total submissions, unread submissions count, and a recent submissions list

PostBox Pro dashboard — at-a-glance stats with quick access to forms and submissions.

Requirements

  • Joomla 5.0 or later (including Joomla 6)
  • PHP 8.1 or later
  • MySQL 5.7+ or MariaDB 10.3+

What’s Included

    • com_postboxpro< /strong> — Component with admin dashboard, form builder, submissions manager, and import tool

 

  • plg_content_postboxpro — Shortcode content plugin for embedding forms in articles
  • plg_task_postboxpropurge — Scheduled task plugin for GDPR auto-purge of expired submissions
  • plg_system_postboxpro — Licence Sync plugin that copies your licence key to the update site automatically

 

Installation

  1. Log in to your Joomla administrator.
  2. Go to System → Install → Extensions.
  3. Upload pkg_postboxpro_1.3.2.zip using the Upload Package File tab.
  4. Click Install.
  5. Navigate to Components → PostBox Pro to get started.

The installer sets up the component, the shortcode content plugin, the GDPR purge task plugin and the Licence Sync system plugin in a single step. On a fresh install all three plugins are enabled for you; updates leave your existing plugin settings alone.

Licence Key Setup

After installation, enter your licence key to enable automatic updates.

Step 1 — Component Options

  1. Go to Components → PostBox Pro → Options.
  2. Click the Pro License tab.
  3. Paste your licence key into the License Key field and click Save.

Your licence key can be found on your account page at extensions.thedesigncompany.co.nz.

Step 2 — Update Sites (automatic)

The PostBox Pro – Licence Sync system plugin (enabled on install) copies your key to the PostBox Pro update site whenever you save the component options, so Joomla passes it automatically when checking for updates.

If the update manager still can’t find new releases (for example, if the Licence Sync plugin has been disabled), add the key manually:

  1. Go to System → Update Sites.
  2. Find PostBox Pro in the list and click to open it.
  3. Enter your licence key in the Download Key field and save.

Upgrading from PostBox (free)

PostBox Pro installs alongside the free version — they use separate database tables and do not conflict. Once Pro is installed, use the built-in import tool to migrate your forms, fields, and optionally your submissions. See Importing from PostBox below.

Field Types

PostBox Pro supports fourteen field types, plus the Page Break. Types marked Pro are not available in the free version.

  • Text — single-line text input with optional placeholder.
  • Email — email input with format validation.
  • Textarea — multi-line text area with optional placeholder.
  • Dropdown Select — dropdown menu with custom options (one per line).
  • Checkbox — single checkbox or multiple checkboxes from an options list.
  • Radio Buttons — radio button group from an options list.
  • Number (Pro) — numeric input with optional minimum and maximum value constraints.
  • Calculated result (Pro) — a live total, estimate, measurement or percentage built from number fields, choice amounts and fixed values. See Calculated Results.
  • Date (Pro) — date picker input with optional min/max constraints. Supports relative values such as today, today+7, or today+30 as well as static dates in YYYY-MM-DD format.
  • Telephone (Pro) — telephone number input.
  • URL (Pro) — URL input with format validation.
  • File Upload (Pro) — file upload input with configurable accepted types and size limit. See File Uploads.
  • HTML Content (Pro) — static HTML block rendered within the form — useful for instructions, section headings, or notices.
  • Hidden (Pro) — sends a value with each submission without showing it on the form, e.g. which page an enquiry came from. See Hidden Fields.
  • Page Break (Pro) — splits the form into multiple pages. See Multi-Page Forms.

All field types are validated on the server: required fields, email, URL, phone, number and date formats, number and date min/max limits, a maximum length (10,000 characters for textareas, 1,000 for other fields), and — for dropdown, radio and multi-option checkbox fields — that every submitted value is one of the configured options.

Managing Fields

  • Fields are ordered by drag-and-drop in the list view.
  • Click the check/cross icon in the Required column to toggle required status without opening the field.
  • Calculated results are filled automatically and cannot be marked as required.
  • Each field’s Name (the HTML name attribute) is auto-generated from the label if left blank.

Hidden Fields (Pro)

Enter the value in the field’s Options box. It can be plain text, tokens, or a mix of both, e.g. Enquiry from {page_title}.

TokenValue
{page_title} Title of the page the form is on
{page_url} Full URL of the page the form is on
{referrer} The page the visitor came from before reaching the form
{user_name} Logged-in user’s name (empty for guests)
{user_email} Logged-in user’s email (empty for guests)
{user_id} Logged-in user’s ID (empty for guests)
{date} Date the form was loaded, as YYYY-MM-DD
{datetime} Date and time the form was loaded, as YYYY-MM-DD HH:MM (site time zone)
{site_name} Your site name from Global Configuration

Hidden values are included in the notification email and the stored submission. They are never required and don’t appear in the multi-page review summary. The page tokens are filled in by the browser. If JavaScript is unavailable, {page_url} and {referrer} fall back to the browser’s referer and {page_title} is left blank.

Field Width (Pro)

Each field has a Field Width setting that controls how much of the row it takes up:

  • Full width (default) — the field has the row to itself.
  • Half — two Half fields in a row sit side by side.
  • One third — three One third fields share a row.
  • Two thirds — pairs with a One third field, e.g. Street address + Postcode.

Fields fill each row in order. If the next field doesn’t fit in the space left, it starts a new row. When a field is hidden by conditional logic, the fields after it move up to fill the gap. On narrow screens, and when the form sits in a narrow column, every field stacks to full width. The width setting doesn’t apply to Hidden or Page Break fields.

Calculated Results (Pro)

Add a Calculated result field to show a total, estimate, measurement or percentage as visitors fill in the form. Choose fields and operations using the guided builder; no formula or code is needed. Visitors can read the result but cannot edit it.

Setting Up a Calculation

  1. Add and save the number or choice fields that visitors will answer.
  2. For a dropdown, radio or checkbox field, expand Assign amounts to these choices in its settings. Give every option an amount, using 0 where appropriate, then save. Amounts are optional for choice fields that are not used in calculations.
  3. Add a new field and choose Calculated result as its type. Give it a label such as Total donation (NZ$) or Estimated cost.
  4. Under Start with, select a field by its label, or choose Fixed amount and enter a number.
  5. For each following value, choose Add (+), Subtract (−), Multiply by (×), Divide by (÷) or Take percentage (%), then select its field or fixed amount.
  6. Use Add value for additional rows. Each new row defaults to Add. A calculation accepts 2–20 values.
  7. Choose Number or Currency under Display as, and select the decimal places. Currency display supports NZD, AUD, USD, GBP, EUR and CAD, for example NZD 117.50.
  8. Enter sample values to check the preview, then save. Sample values only test the calculation; they are not default answers on the visitor’s form.

Examples

UseValues and operationsExample result
Donation total Start with Project A donation; Add Project B donation 25 + 50 = NZD 75.00
Enquiry estimate Start with Number of people; Multiply by a fixed amount of 25; Add Selected extras (4 × 25) + 17.50 = NZD 117.50
Base fee plus labour Start with a fixed amount of 100; Add Hours; Multiply by a fixed amount of 25 100 + (2 × 25) = 150.00
Area Start with Width; Multiply by Height 3 × 4 = 12.00
Percentage amount Start with 200; Take percentage with a fixed amount of 15 200 × 15% = 30.00

Calculation Order and Percentages

Multiplication, division and percentages are calculated first, from left to right within each group. Addition and subtraction follow. The explanation above the rows inserts brackets automatically, so Base fee + (Hours × Rate) clearly shows which values are multiplied.

Take percentage (%) uses the value as a rate: enter 15 for 15%. It calculates the percentage amount itself. For example, start with 100, add 200, then take a percentage of 15: the preview shows 100 + (200 × 15%), giving 130. The percentage applies to the preceding multiplied/divided group, not the whole total.

Amounts for Choice Fields

Amounts are stored separately from option labels. A visitor still sees choices such as Standard and Premium, and the selected label remains in their submission. A calculation uses the amount assigned to that label. When several checkboxes are ticked, their amounts are added together. A checkbox without options can have an amount for When checked.

Only published number fields and choice fields with an amount for every option are offered as calculation sources. Save choice amounts before adding the calculated result. If you add an option later, assign its amount too. If you rename, unpublish or delete a source field, update any calculations that use it.

Results, Empty Answers and Validation

  • Empty answers and fields hidden by their own conditions contribute 0. Fields on another page of a multi-page form still count.
  • Results update as visitors type, after saved answers are restored and after a form reset.
  • Number and currency display support 0–6 decimal places. Results round halves away from zero.
  • Division by zero, invalid numbers and missing sources prevent submission until corrected. Inputs and the unrounded result must be finite and within ±1,000,000,000,000.
  • The server recalculates each result from validated, active answers before storing or emailing it. A total altered in the browser is ignored.
  • Results appear in the review step, stored submissions, notification emails, auto-reply body placeholders and CSV exports. Use the result field’s usual {field_name} placeholder in an email body.
  • Calculated results are never required inputs. They cannot use other calculated results as sources or act as sources for conditional rules.
  • Existing calculations created with the original one-operation builder keep their results and open with the equivalent operation on each row.

Calculated results work in both menu-item forms and shortcode-embedded forms.

Multi-Page Forms (Pro)

Divide long forms into multiple steps by adding Page Break fields. Each Page Break creates a new page — fields above it appear on the current page, fields below it appear on the next.

How It Works

  1. Add fields to your form as normal.
  2. Insert a Page Break field wherever you want the page to change.
  3. Add the next group of fields after the Page Break.
  4. Repeat for as many pages as needed.

On the frontend, visitors navigate between pages using Previous and Next buttons. Each page is validated before advancing — required fields must be completed before the visitor can move forward. A progress bar shows the current step out of the total.

Multi-page form — step-by-step navigation with a progress bar and per-page validation.

Summary / Review Step (Pro)

Enable the Show Summary Before Submit option on the Pro Features tab to add an optional review step after the final page. The visitor sees all their answers displayed before they confirm and submit. This is useful for longer forms where mistakes are easy to miss.

Auto-Save / Resume (Pro)

Enable Save Progress on the Pro Features tab to automatically save the visitor’s answers to browser storage as they fill in the form. If they navigate away and return, a prompt lets them choose Continue to restore their saved answers or Start fresh to clear them. Progress is cleared on successful submission.

Conditional Field Logic (Pro)

Show or hide any field based on the value of another field in the same form. Conditions are configured per field using the visual rule builder.

Setting Up Conditions

  1. Open a field for editing.
  2. Scroll to the Conditions section.
  3. Click Add condition to create a condition.
  4. Select the field to watch, the operator, and the value to match.
  5. Add more rules if needed and choose whether All rules match or Any rule matches.
  6. Save the field.

Visibility follows the rules as soon as the form loads and updates instantly as the visitor fills it in — no page reload required.

Operators

  • equals — the watched field has this exact value.
  • does not equal — the watched field has any other value.
  • is not empty — the watched field has any value entered.
  • is empty — the watched field is blank.

For dropdown, checkbox, and radio fields, the value input becomes a dropdown showing the available options. For text-based fields it is a free-text input.

Checkbox Conditions

For a checkbox with options, equals means the named option is selected, even when other options are also selected. does not equal means that option is not selected. Use is not empty for any ticked box, or is empty for none. Comparisons ignore letter case.

For a checkbox without options, the value dropdown offers Checked and Not checked.

Example: Show an Address for a Tax Receipt

  1. Add and save a checkbox field labelled Would you like a tax receipt? with the option Yes, please send me a receipt.
  2. Add a textarea labelled Name and address for your receipt.
  3. In the textarea’s Conditions, click Add condition. Select the receipt checkbox, choose equals, and select Yes, please send me a receipt.
  4. Save and preview the form. The textarea appears when the option is ticked and disappears when it is unticked.

You can make the textarea required. Required validation applies while its conditions match; when hidden, the textarea is disabled and omitted from the review and processed submission. Restoring saved answers or resetting the form also updates visibility.

PostBox Pro 1.3.2 corrects checkbox option matching in the browser and on the server. Existing rules comparing an option label do not need to be recreated. Older hand-written rules using checked to mean any selected box remain supported; if an actual option is labelled checked, only that specific option matches.

Condition rule builder — configure show/hide logic visually without writing code.

File Uploads (Pro)

Add a File Upload field to your form to accept file attachments from visitors. Uploaded files are attached to the admin notification email.

Configuring File Upload Settings

Allowed file types and the size limit are configured per field in the field editor:

  • Allowed File Types — comma-separated list of accepted extensions (e.g. jpg,jpeg,png,pdf,doc,docx). Defaults to jpg,jpeg,png,gif,pdf,doc,docx.
  • Max File Size (MB) — maximum upload size for this field, between 1 and 50 MB. Defaults to 5 MB.

These settings appear in the field editor when the field type is set to File Upload. If you have multiple file upload fields on the same form, each can have different type and size settings. The accepted types and size limit are enforced client-side with immediate feedback and validated server-side on submission.

The Pro Features tab on the form also has Allowed File Types and Max File Size fields — these act as fallback defaults for any file upload field that has not had its own values set.

Form Settings

Each form has its own settings across several tabs in the edit view.

General

  • Title — the form heading shown on the frontend.
  • Alias — auto-generated URL slug.
  • Description — optional text shown below the title on the frontend.
  • Submit Button Text — defaults to “Send”.

Pro Features (Pro)

  • Show Summary Before Submit — display a review step showing all answers before final submission.
  • Save Progress — auto-save form state to browser storage so visitors can resume if they navigate away.
  • Allowed File Types — fallback accepted file extensions for file upload fields. Individual file upload fields can override this.
  • Max File Size (MB) — fallback maximum file size for upload fields. Individual file upload fields can override this.

Email Notification

  • Email To — recipient address(es), comma-separated. Falls back to the Joomla system email if blank.
  • CC — carbon copy recipients.
  • BCC — blind carbon copy recipients.
  • Email Subject — supports {field_name} placeholders. Defaults to “New submission from [form title]”.
  • Email Template — HTML body with {field_name} placeholders. Leave blank for an auto-generated table layout.

Auto-Reply

  • Enable Auto-Reply — sends a confirmation email to the person who submitted the form.
  • Auto-Reply Field (Pro) — specify which field contains the recipient’s email address (e.g. your_email). If left blank, the first email-type field is used automatically.
  • Auto-Reply Subject — supports {field_name} placeholders.
  • Auto-Reply Template — HTML body with placeholders. Leave blank for a generic thank-you message.

Thank You

  • Thank You Type — choose between an inline message or a redirect to a URL.
  • Thank You Message — shown on the form page after successful submission.
  • Redirect URL — redirects the visitor to this URL after submission.

Spam & GDPR

  • Enable Captcha — requires a captcha provider, site key and secret key in component options. If captcha is enabled but not fully configured, the form rejects submissions (and the form editor shows a warning) rather than silently skipping the check.
  • Store Submissions — Yes (default) saves submissions in the database. No switches the form to email-only mode: submissions are validated and emailed, but nothing is stored.
  • Require Consent — shows a consent checkbox on the form.
  • Consent Text — the label for the consent checkbox.
  • Data Retention (days) — auto-delete submissions older than this. Set to 0 to keep forever (or to use the global default from component options, if one is set). Hidden in email-only mode.
Form settings — per-form configuration across tabbed panels including Pro-only options.

Submissions

Form submissions are stored in the admin panel at Components → PostBox Pro → Submissions (unless the form is in email-only mode — see GDPR Compliance below).

Each submission is saved before the notification email is sent, so a message is never lost if the mail server fails. If the email can’t be sent, the submission is marked Email failed and the error is written to administrator/logs/com_postboxpro.php.

  • Filter by form, read/unread status, and date range.
  • Search across form data and form titles.
  • Unread submissions show a blue dot; read submissions show a grey eye icon.
  • Click a submission to view the full field data, metadata (date, notification email status, IP address, user agent), and any attached files.
  • Submissions are automatically marked as read when viewed.
  • Use the toolbar to mark read, mark unread, delete, or Export CSV.

Spam Protection

PostBox Pro uses three layers of spam protection.

Honeypot (Always Active)

A hidden field is included on every form. Bots that auto-fill all fields trigger it and receive a fake success response to prevent retrying.

Rate Limiting (Always Active)

Limits submissions per IP address within a configurable time window. Raw IP addresses are not stored for rate limiting — PostBox Pro keeps a keyed hash for up to 24 hours. Configure in Components → PostBox Pro → Options → Rate Limiting.

Captcha (Optional)

Supports hCaptcha and Cloudflare Turnstile. To enable:

  1. Go to Components → PostBox Pro → Options → Captcha Settings.
  2. Select a provider and enter your Site Key and Secret Key.
  3. Edit your form and set Enable Captcha to Yes on the Spam & GDPR tab.

Verification always happens on the server. If a form has captcha enabled but the provider, site key or secret key is missing, PostBox Pro rejects submissions to that form instead of letting them through unchecked.

GDPR Compliance

Consent Checkbox

Enable per form on the Spam & GDPR tab. The checkbox must be ticked before submission and is validated server-side regardless of client-side checks.

Email-Only Mode

Set Store Submissions to No on a form’s Spam & GDPR tab to stop PostBox Pro storing that form’s submissions. Submissions are still fully validated and emailed, but no names, messages, IP addresses or user agents are written to the database, and uploaded files are deleted from the server once the email has been sent (attach files to the email if you need to keep them). Because the email is the only copy, the visitor sees an error if the notification email can’t be sent.

Data Retention & Auto-Purge

Set a retention period (in days) per form. To enable automatic deletion:

  1. Go to System → Scheduled Tasks.
  2. Create a new task and select Task - PostBox Pro Purge.
  3. Set the schedule (e.g. daily) and save.

Component Options

Access via Components → PostBox Pro → Options.

  • From Name / From Email — sender details for notification emails. Leave blank to use Joomla’s global mail settings.
  • Captcha Provider — None, hCaptcha, or Cloudflare Turnstile.
  • Site Key / Secret Key — from your captcha provider’s dashboard.
  • Max Submissions — maximum submissions per IP per form within the time window.
  • Time Window (minutes) — the rate limit cooldown period.
  • Default Retention (days) — default retention period for new forms. Set to 0 to keep submissions indefinitely.

Pro License

  • License Key — your PostBox Pro licence key. Find it on your account page at extensions.thedesigncompany.co.nz. To enable automatic updates, also enter this key under System → Update Sites → PostBox Pro (Download Key field).

Shortcode Embedding

The included content plugin lets you embed forms in articles and custom HTML modules.

{postboxpro 1}

Replace 1 with your form’s ID (visible in the Forms list). To embed without the card border:

{postboxpro 1 border=false}

To embed without the form title:

{postboxpro 1 title=false}

All Pro features — multi-page navigation, conditional logic, calculated results, file uploads, and auto-save — work identically in shortcode-embedded forms.

Importing from PostBox (free)

If you have been using the free PostBox component, the import tool migrates your existing forms, fields, and submissions into PostBox Pro without affecting the original data.

  1. Ensure both PostBox (free) and PostBox Pro are installed.
  2. Go to Components → PostBox Pro → Import.
  3. Choose whether to also import existing Submissions.
  4. Click Import.

All forms and fields are copied across. Pro-specific settings (conditional logic, file upload limits, multi-page options) are initialised to their defaults and can be configured after import. The free PostBox component and its data are left untouched.

Template Overrides

To customise the form output, create a template override:

templates/{your-template}/html/com_postboxpro/form/default.php

CSS Classes Reference

  • .postbox-form-wrapper — outer container (max-width 640px, centred)
  • .postbox-form-wrapper--no-border — borderless modifier (applied via shortcode)
  • .postbox-form-header — title and description area
  • .postbox-form-title — form heading
  • .postbox-form-description — form description text
  • .postbox-form — the form element
  • .postboxpro-progress — multi-page progress bar container
  • .postboxpro-step, .postboxpro-step-dot, .postboxpro-step-label — progress step, marker and label
  • .postboxpro-page — individual page wrapper in a multi-page form
  • .postbox-field — individual field wrapper
  • .postbox-field--required — required field modifier
  • .postbox-field--error — error state modifier
  • .postbox-field[data-condition-active="0"] — a field whose conditions are inactive (hidden with inline styling)
  • .postbox-field--calculated — calculated result field wrapper
  • .postbox-calculated-result — read-only result display
  • .postbox-calculation-hint — calculation guidance or error hint
  • .postbox-field--w-half, .postbox-field--w-third, .postbox-field--w-two-thirds — field width modifiers (Full width fields have no modifier)
  • .postbox-html-content — HTML content field wrapper
  • .postbox-option — checkbox/radio option label
  • .postbox-required — asterisk marker
  • .postbox-button — submit / next button
  • .postboxpro-prev, .postboxpro-next — previous and next page buttons
  • .postboxpro-summary — review step wrapper
  • .postboxpro-autosave-notice — auto-save status notice
  • .postbox-message — success/error message area
  • .postbox-message--success — success state
  • .postbox-message--error — error state

Licence

PostBox Pro is commercial software sold and distributed by The Design Company. Your purchase entitles you to install PostBox Pro on a single production site. Please refer to the licence terms on the extensions site for full details.

← Back to PostBox Pro