PostBox Pro / Documentation

PostBox Pro — Documentation

Powerful multi-step forms for Joomla 5 & 6.

PostBox Pro extends the free PostBox component with multi-page forms, conditional field logic, 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 — 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

Installation

  1. Log in to your Joomla administrator.
  2. Go to System → Install → Extensions.
  3. Upload pkg_postboxpro_1.1.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, and the GDPR purge task plugin in a single step.

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

  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.

Joomla will now pass your key when checking for updates. Without this step, the update manager will not find new releases.

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 twelve field types. 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.
  • 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.
  • Page Break (Pro) — splits the form into multiple pages. See Multi-Page Forms.

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.
  • Each field’s Name (the HTML name attribute) is auto-generated from the label if left blank.

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, their previous answers are restored. 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 Conditional Logic section.
  3. Click Add Rule 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 must match or Any rule must match.
  6. Save the field.

The field is hidden by default and only shown when its conditions are met. On the frontend, visibility updates instantly as the visitor fills in the form — 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.

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 to be configured in component options.
  • 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.
Form settings — per-form configuration across tabbed panels including Pro-only options.

Submissions

All form submissions are stored in the admin panel at Components → PostBox Pro → Submissions.

  • 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, 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. 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.

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.

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}

All Pro features — multi-page navigation, conditional logic, 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-page — multi-page step wrapper (Pro only)
  • .postbox-progress — multi-page progress bar container
  • .postbox-progress__bar — progress fill element
  • .postbox-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--hidden — conditionally hidden field
  • .postbox-html-content — HTML content field wrapper
  • .postbox-option — checkbox/radio option label
  • .postbox-required — asterisk marker
  • .postbox-button — submit / next button
  • .postbox-button--prev — previous page button
  • .postbox-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

Support

For help, feature requests, and bug reports, visit the PostBox Pro page on the TDCLab extensions site at extensions.thedesigncompany.co.nz.

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

We use cookies

We use cookies to enhance your browsing experience and analyse site traffic. Please choose which cookie categories you consent to.