Custom Form for Magento 2: User Guide

Custom Form Builder lets you create your own storefront forms in the Magento admin: contact forms, product enquiries, quote requests, surveys, return requests or job applications. You build the form by dragging fields onto it, place it on its own page, in a CMS page or block, or behind a button that opens it in a popup, and handle what customers send in a submissions grid with replies by email.

Requirements

Installation

Install with Composer from the CommerceGears Composer repository (repo.commercegears.com). How to set up access: https://commercegears.com/composer-access/

composer require commercegears/module-custom-form
bin/magento module:enable CommerceGears_Core CommerceGears_CustomForm
bin/magento setup:upgrade
bin/magento setup:di:compile            # production mode
bin/magento setup:static-content:deploy # production mode
bin/magento cache:flush

On Hyvä, rebuild the theme CSS afterwards (npm run build in your theme's web/tailwind folder) so the form styles are included. The module registers itself for Hyvä's Tailwind source scanning.

To start with an example, create a ready-made contact form from the command line (or use "Add Form" in the admin):

bin/magento commercegears:custom-form:create-sample --template=contact

Configuration

Stores > Configuration > CommerceGears > Custom Forms (also linked from CommerceGears > Custom Forms > Configuration).

General

• Enabled: No hides every form, makes form pages return "page not found" and stops new submissions. Default: Yes.
• Form Page URL Prefix: forms with their own page are shown at /<prefix>/<URL key>. Default: forms.

Spam Protection (a hidden honeypot field is always used)

• Minimum Seconds Before Sending: forms sent faster than this after they appeared are refused with a friendly message. 0 turns the check off. Default: 3.
• Submissions per IP Address per Hour: for all forms together. The IP address is stored only as a one-way hash. 0 means no limit. Default: 10.
• Google reCAPTCHA: No, reCAPTCHA v2 ("I am not a robot"), v2 Invisible or v3 Invisible. Uses Magento's reCAPTCHA modules with the keys from Stores > Configuration > Security > Google reCAPTCHA Storefront. Each form can turn it off. Default: No.

File Uploads

• Maximum File Size (MB): the upper limit for every upload field, 1 to 50; a field can set a lower limit. PHP's upload_max_filesize and post_max_size also apply. Default: 5.

Email

• Email Sender: the store email identity for all emails of this module. Default: General Contact.
• Default Staff Email Address(es): used for forms without their own recipients. Empty: the General Contact address.
• Staff Notification Template, Automatic Reply Template, Reply Template: the default templates.

My Account

• Show "My Form Submissions": signed-in customers see what they sent and your replies. Default: Yes.
• Customers Can Delete Their Submissions: deletes the submission with its files and replies. Default: Yes.

Data Retention

• Delete Submissions After (Days): a daily cron job deletes older submissions with their uploaded files. A form can set its own period. 0 keeps them. Default: 0.

Creating a form

Go to CommerceGears > Custom Forms > Forms and click Add Form. The arrow next to it offers ready-made templates: blank form, contact form, product enquiry, quote request (3 steps) and feedback survey. Nothing is saved until you click Save.

Form settings

• Active, Title (shown above the form, as the page title and in emails), URL Key (made from the title when empty), Own Page (show the form at /forms/<URL key>).
• Store Views and Customer Groups: where and to whom the form is shown. No customer group selected means everyone.
• Introduction: optional text above the form; simple HTML (paragraphs, bold, links, lists) is allowed.

The builder (Fields and Pages)

• Add fields: drag a field type from the left column onto the form, or click it to add it below the selected field. Field types: text, text area, email, phone, number, date, dropdown, radio buttons, checkboxes, multi-select, country, rating (stars), file upload, consent checkbox, hidden value and text block (HTML).
• Arrange: drag fields to a new position or onto another page tab, or use the arrow buttons. Each card shows a preview of the field as customers will see it, its type, its code and whether it has conditions.
• Pages: "Add page" creates a step. Multi-page forms show the step names and a progress bar, check each step before "Next", and keep the answers when customers go back. Pages can be renamed, moved and deleted.
• Field settings (click a field): label, field code, required, placeholder, help text, default value, width (full or half; half-width fields sit side by side on desktop), and depending on the type:
• text: format (any text, letters only, letters and digits, web address, or your own regular expression with its own error message), minimum and maximum length;
• text area: length limits and height;
• number: minimum, maximum, whole numbers only;
• date: earliest and latest date;
• dropdown, radio buttons, checkboxes, multi-select: options with a label (shown) and a value (stored and used in conditions);
• file upload: allowed file types (documents and images only), maximum size and number of files;
• rating: number of stars (3 to 10);
• consent checkbox and text block: the text, with simple HTML such as a link to your privacy policy.
• Default values can use placeholders: {customer.name}, {customer.firstname}, {customer.lastname}, {customer.email}, {customer.telephone}, {customer.company}, {customer.country} (filled in for signed-in customers from their account and default billing address), {product.name}, {product.sku}, {product.url} (when the form is shown on a product page), {page.url}, {page.title} and {store.name}. A hidden field with {product.sku} records which product an enquiry was about.
• Conditional logic: "Show this field: Only when all/any of these are true", then rules such as "Topic is A return" or "Rating is less than 4". Operators: is, is not, contains, is empty, is not empty, is greater than, is less than. Rules can use fields above the current one. A hidden field is not required and its answer is not stored; a page whose fields are all hidden is skipped.
• Store view texts: choose a store view in "Edit texts for" at the top of the builder. You can then enter that store view's labels, placeholders, help texts, option labels, consent and HTML texts, page titles, and the form title, introduction, button label and success message. Empty boxes use the default text.

Sending

• Submit Button Label (default "Send"), Success Message (shown in place of the form; simple HTML allowed) and Redirect After Sending (optional page such as /thank-you, instead of the message).

Email

• Email Staff About New Submissions, Staff Email Address(es) (this form's recipients) and Staff Email Template. The notification's Reply-To is the customer, so you can answer from your mail program.
• Send an Automatic Reply: a short "we have received your message" e-mail to the first email field of the form. The default template does not repeat the answers or the name, so the form cannot be used to send your store's e-mails with someone else's text. Off by default; we recommend reCAPTCHA when you switch it on.
• Templates can be copied and changed in Marketing > Email Templates ("CommerceGears Custom Forms: ..."). Variables: {{var form_title}}, {{var customer_name}}, {{var customer_email}}, {{var submission_id}}, {{var store_name}}, {{var answers_html|raw}} (all answers as a table) and {{var fields.CODE}} for a single answer (CODE is the field code).

Spam protection, My Account and privacy

• Google reCAPTCHA: used when reCAPTCHA is set up for custom forms in the configuration.
• Show in My Account: list this form's submissions under My Form Submissions.
• Delete Submissions After (Days): this form's retention period. Empty uses the configuration, 0 keeps them.

Where to show it

The "Where to Show It" section of a saved form lists its page address and the codes to copy:

• Own page: https://your-store/forms/<URL key>.
• CMS page or block: Insert Widget > "CommerceGears: Custom Form", or paste {{widget type="CommerceGears\CustomForm\Block\Widget\Form" form_id="contact-us"}}. form_id takes the URL key or the ID.
• Popup button: the same widget with "Show As: Button that opens the form in a popup" and a button label, for example {{widget type="CommerceGears\CustomForm\Block\Widget\Form" form_id="request-a-quote" display_mode="popup" button_label="Request a quote"}}. The popup is a native dialog: Escape and a click outside close it, and focus returns to the button.
• Page Builder: add an HTML Code element and insert the widget.
• Layout XML (for example on product pages): a CommerceGears\CustomForm\Block\Form block with the argument form_id.
• Widget instances: Content > Widgets > Add Widget > "CommerceGears: Custom Form" to place a form in a container of chosen pages (for example the product page).

Submissions

CommerceGears > Custom Forms > Submissions lists every submission with the date, form, status, name, email and a summary of the answers. Filter by form, status, date or text; the "Submissions" link in the forms grid opens the list for one form. Mass actions: Mark as Answered, Mark as New, Export to CSV, Delete.

Click a row to open the submission:

• all answers with the labels at the time it was sent, uploaded files as download links;
• details: date, name and email, customer account (link), store view and the page it was sent from;
• Status and Note: set New or Answered and keep an internal note;
• Replies: write a subject and message and click Send Reply. The reply is emailed with a copy of the answers, kept with the submission, shown to the customer in My Account, and the submission is marked as answered.

CSV export has one column per field (the union of the fields in the selection), the files and the note. Values that spreadsheet programs would run as formulas are prefixed with a quote.

My Account

With "Show My Form Submissions" on, signed-in customers find My Form Submissions in their account: date, form, summary and status (Received or Answered). The detail page shows their answers and your replies, and, when allowed, a "Delete submission" button. Submissions sent as a guest are not linked to an account.

Uploaded files

Files are kept in var/commercegears_custom_form/ under random names without an extension, outside the public web folder, and can only be downloaded by admin users with the "Download Uploaded Files" permission. Only document and image types can be allowed (PDF, JPG, PNG, GIF, WebP, HEIC, TXT, CSV, RTF, DOC, DOCX, XLS, XLSX, ODT, ODS, ZIP); the content of each file must match its extension. Deleting a submission (in the admin, by the customer, or by the retention job) also deletes its files.

Privacy (GDPR)

• Add a Consent checkbox with your text and a link to the privacy policy; the exact text is stored with the answer.
• Set a retention period globally or per form; the daily cron job (03:17) deletes older submissions with files.
• Delete single submissions or many at once in the admin; customers can delete their own.
• IP addresses are never stored, only a keyed one-way hash for the hourly limit.

Command line

• bin/magento commercegears:custom-form:create-sample [--template=contact|blank|product_enquiry|quote|feedback] [--title="..."] [--url-key=...] [--inactive]
• bin/magento commercegears:custom-form:cleanup [--dry-run]: runs the retention deletion now (or only counts).
• bin/magento commercegears:custom-form:email-preview <submission ID> [--type=admin|auto_reply|reply]: shows an email without sending it.

Permissions (ACL)

System > Permissions > User Roles > Role Resources > CommerceGears > Custom Forms:

• Forms: view; Create and Edit; Delete.
• Submissions: view; Change Status, Notes and Reply; Download Uploaded Files; Export to CSV; Delete.
• Stores > Configuration > CommerceGears Custom Forms.

For developers

• After a successful submission the form element dispatches the DOM event commercegears-custom-form:sent with detail.formId and detail.submissionId, for analytics tags.
• Repositories: CommerceGears\CustomForm\Api\FormRepositoryInterface, CommerceGears\CustomForm\Api\SubmissionRepositoryInterface.

Troubleshooting

• The form does not appear: check that the form is active, assigned to the store view and the customer group, and that the module is enabled for the store view. Saving the form clears the full page cache of pages that show it.
• "The form was sent very quickly": a browser extension filled the form instantly; sending again works. Lower Minimum Seconds Before Sending if needed.
• "Your session has expired": the page was open for a long time or cookies are blocked; reload the page.
• No emails arrive: check Stores > Configuration > Advanced > System > Mail Sending Settings ("Disable Email Communications" must be No) and the recipients. The admin shows a notice when email sending is switched off.
• Uploads fail for large files: raise PHP's upload_max_filesize and post_max_size.
• Hyvä styles missing: rebuild the theme CSS.

Uninstall

bin/magento module:disable CommerceGears_CustomForm
composer remove commercegears/module-custom-form
bin/magento setup:upgrade

The tables commercegears_customform_form, commercegears_customform_form_store, commercegears_customform_submission, commercegears_customform_file and commercegears_customform_reply and the folder var/commercegears_custom_form stay in place; remove them yourself if you no longer need the data.