Advanced Fields adds two checkout field types to J2Commerce: Reference Number and Confirm Another Field. A Reference Number field cleans up what the shopper types, checks its format and check digit, and can look it up in an allow-list you import.
It is for stores that collect a customer number, herd number, creditor reference or similar identifier at checkout and need it to be right before the order is placed.
Requirements
- Joomla 6.0 or later and PHP 8.3 or later
- J2Commerce 6.6.4 or later
Advanced Fields is a separate add-on available from the J2Commerce Extensions Store. It does not ship with J2Commerce 6.
Installation
- Download the plugin zip from your J2Commerce Extensions Store account.
- In Joomla, go to System -> Install -> Extensions and upload the zip.
- Go to System -> Plugins, search for Advanced Fields and switch the plugin on.
- Open Checkout Fields in J2Commerce and add a field of type Reference Number.
Info
The plugin is installed but not enabled. Until you enable it, the two field types are not offered.
Plugin Settings
Open the plugin from System -> Plugins -> Advanced Fields. These settings apply to every Reference Number field.
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Allow-List Lookup | Lets the checkout look up a reference number in its allow-list while the shopper types. The list is checked again when the step is submitted. | Yes | Yes, No |
| Lookups per 15 Minutes | How many different numbers one shopper session may check against a list in 15 minutes. After that the instant result stops, and a step that needs the list asks the shopper to wait a few minutes. Shown only when Allow-List Lookup is Yes. | 10 | 3 to 60 |
| Show the Review Line | Shows the confirmed reference and its list result on the order review step, with a link back to change it. | Yes | Yes, No |
| Debug Logging | Writes field names and pass or fail outcomes to logs/app_advancedfields.php. Reference values and account names are never logged. | No | Yes, No |
Tip
If the site sits behind a proxy or CDN, switch on Behind Load Balancer in Global Configuration. Each shopper is then counted by their own address and not all together.
Field Types
Both types appear in the Field Type list of a checkout field. Once one is chosen, an Advanced tab opens on the field form.
- Reference Number: a text field whose value is cleaned up, checked and optionally looked up.
- Confirm Another Field: a field that must match the value of another checkout field, such as an email address.
Reference Number Settings
The value is cleaned up first. What remains is the canonical value that the format rule, the check digit and the allow-list all use.
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Required | Use this instead of the Required switch on the Basic tab when the field has conditions or is shown in more than one checkout section. Saving moves the Basic tab setting here. The field is then required only while it is shown. | No | Yes, No |
| Fold Full-Width Characters | Converts full-width and other compatibility characters to their plain form, so a pasted full-width digit still matches. | Yes | Yes, No |
| Trim the Ends | Removes spaces, tabs and line breaks from the start and end of the value. | Yes | Yes, No |
| Collapse Repeated Spaces | Turns any run of spaces, tabs and line breaks inside the value into a single space. | Yes | Yes, No |
| Convert to Upper Case | Makes letters upper case, so ie12345 and IE12345 are the same value. This is the only step that makes the comparison ignore case. | Yes | Yes, No |
| Characters to Remove | Separators removed from the value before it is checked, compared and stored. | Space, Dash, Slash, Dot | Space, Dash (-), Slash (/), Dot (.), Underscore (_), Comma (,) |
| Format | The shape the canonical value must have. The presets are written for the canonical form, so a preset that expects no slash works because the slash is removed first. | No Format Check | No Format Check, Digits Only, Letters and Digits Only, UK Holding Number (9 Digits), EU Ear Tag (2 Letters, 1 to 12 Digits), Creditor Reference (RF), Custom Pattern |
| Pattern Body | The pattern body only, matched against the whole canonical value, for example IE\d{5,7}. Do not add delimiters, anchors or flags. Up to 200 characters. Shown when Format is Custom Pattern. | Empty | Text |
| Minimum Length | Fewest characters the canonical value may have. Use 0 for no minimum. | 0 | 0 to 128 |
| Maximum Length | Most characters the canonical value may have, up to a ceiling of 128. Use 0 for the ceiling. | 64 | 0 to 128 |
| Example | Shown to the shopper as hint text and in error messages, for example IE1234567. Required whenever a format or a check digit is set. A language key or plain text. | Empty | Text |
| Custom Error Message | Optional. Shown instead of the standard message when the format check fails. A language key or plain text. | Empty | Text |
| Check Digit | Checks the value against a check-digit algorithm. Leave it on None unless your numbers really carry a check digit; many reference schemes, including herd numbers, do not. | None | None, Luhn (Mod 10), Creditor Reference (ISO 11649, Mod 97) |
| Display Template | How the value is shown on the order, in emails and on invoices. Each # takes the next character of the canonical value, for example ##/###/####. Ignored unless the number of # signs equals the length of the value. | Empty | Text |
| Ask Twice | Shows a second input where the shopper enters the value again. Pasting is always allowed. A mismatch is refused. | No | Yes, No |
| Confirm Label | Optional label for the second input. Use %s where the field label should appear. Leave empty for Confirm followed by the field label. Shown when Ask Twice is Yes. | Empty | Text |
| Show Value Toggle | Masks both inputs and adds a button next to each that reveals what was typed. | No | Yes, No |
| Allow-List | Checks the value against one of your imported lists. | None | Any allow-list you created |
| Allow-List Mode | What happens when the value is not on the list. Shown when an Allow-List is chosen. | Accept and Flag the Order | Refuse Unknown Values, Accept and Flag the Order, Show the Name When Found, Never Refuse |
| Show the Account Name | Shows the name of the matching list entry to the shopper as soon as they leave the field, and on the order review step. When off, the shopper sees only whether the number was found. The admin order view always shows the name. | No | Yes, No |
Warning
Showing the account name lets anyone with a checkout session find out whether a number belongs to a named account. Leave Show the Account Name off if this matters to you.
Confirm Another Field Settings
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Required | Same as on a Reference Number field. | No | Yes, No |
| Field to Confirm | The field whose value this one must match. Only enabled fields that share a checkout area with this one are listed. | Select a Field | Enabled checkout fields |
Saving a Confirm Another Field switches off Show on Frontend and Show on Admin Order View, because it only repeats the value of the field it confirms. A field that is the target of a Confirm Another Field cannot be deleted until those fields are deleted or pointed elsewhere.
Conditions
Both types can be shown or required only for certain carts. Add one row per rule.
| Setting | What It Does | Default | Options |
|---|---|---|---|
| When the Conditions Are Met | Show: the field appears only while the conditions are met. Require: the field always appears and is required only while the conditions are met. Without conditions the field always appears. | Show the Field, Hide It Otherwise | Show the Field, Hide It Otherwise; Always Show It, Require It Only Then |
| Group | Rules with the same group number must all be true. The conditions are met when every rule in any one group is true. | Empty | Number |
| Rule | What the cart is tested for. | Empty | Cart Contains Product, Cart Contains Category, Cart Contains Product Type, Cart Contains Option Type |
| Operator | Whether any of the values is in the cart, or none of them is. Option types only support Any of. | Empty | Any of, None of |
| Values | Comma-separated. Product and category rules take numeric ids; product type and option type rules take keys such as simple or donation. | Empty | Text |
Allow-Lists
An allow-list holds the reference numbers you expect, with an account name for each. Open J2Commerce -> Apps -> Advanced Fields to manage them.
Creating a List
- Choose New and enter a title for the allow-list.
- Choose the Characters to Remove. Use the same characters as the fields that use this list, so entries match what shoppers type.
- Save, then add entries one at a time or import a CSV file.
- On a Reference Number field, choose the list in Allow-List.
Each entry has a Value, an optional Account Name and optional Notes. Notes are for your own use and are never sent to the browser. A value cannot be empty after the removed characters are taken out, cannot be longer than 128 characters and cannot repeat on the same list.
Importing a CSV File
- Open the list and choose Import CSV in the toolbar.
- Choose a
.csvfile of up to 5 MB. - Choose what happens to existing entries: Keep them and update the ones in the file, or Delete them and use only the file.
- Choose Upload and Preview, read the counts and the sample rows, then choose Import.
The first row must be a header with a column named Value. Name and Notes columns are optional and any other column is ignored. A file may hold up to 50,000 rows.
The preview shows Rows Read, New, Updated, Duplicates in File and Rejected. Choose Download Rejected Rows to correct and import them again.
Warning
In replace mode, every entry now on the list is deleted when you choose Import. Deleting an allow-list also deletes every entry on it, and the fields that used it stop checking a list.
How the Checkout Behaves
- The shopper sees the example as hint text under the field.
- A value that fails the format or check digit is refused with a message that includes the example.
- With a list chosen, the shopper sees the result as soon as they leave the field. With Show the Account Name on, the result reads You are paying for: Smith Farm; otherwise it reads Found in our records.
- In Refuse Unknown Values mode, the shopper cannot continue until the number is on the list. In Accept and Flag the Order mode, the order is placed and marked Not on List. In Show the Name When Found, Never Refuse mode, the name is shown when found and nothing is refused.
- The value is checked again when the order is confirmed.
Submissions
Choose Submissions in the toolbar of the Advanced Fields screen to see a row for every Reference Number field on every order placed while the plugin is enabled. Columns are Order, Field, Reference, As Typed, Status, Account and Date. Status is On List, Not on List or No List Check.
Filter by field, status or date range, search by order number or reference, and choose Export CSV to download the rows.
The same value also appears on the admin order view, in the customer's order history, in emails and on invoices, shown through the Display Template when one is set.
Troubleshooting
The Field Types Are Missing
Enable the plugin in System -> Plugins. A fresh install leaves it off.
A Confirm Field Is Not Checked
The message The field to confirm is disabled, so this field is not checked at checkout means the target field is switched off. Enable it or choose another field.
Too Many Checks
A shopper who passes Lookups per 15 Minutes sees Too many checks. You can still continue; we will check the number when you place the order.
A step that needs the list asks them to wait a few minutes. Raise the limit, or check that Behind Load Balancer is on when the site sits behind a proxy.
Installation Is Refused
The plugin needs J2Commerce 6.6.4 or later. Update J2Commerce first, then install again.
Uninstalling
Uninstalling removes the plugin and its tables. Checkout fields of an Advanced Fields type are disabled, not deleted, because past orders refer to them.