CBX on Joomla — Platform Guide

Version

4.0 preview

Updated

7 Sept 2026

View markdown

Audience: integrators and developers running CBX on Joomla · Scope: what is specific to the Joomla edition — installation, the extensions that ship, storefront wiring, ACL, the Joomla 4/5 wrapper and the CLI · Last reviewed: 2026-07-21

Store admins: the task-oriented manual is the Admin Guide — start with CBX on Joomla, which covers the same ground in plain language. This document is the technical counterpart.

TL;DR — Joomla is CBX's reference host: CBX owns the entire shop (configurator, cart, checkout, orders, customers, email, tax, shipping, payment) and Joomla supplies the site around it — pages, menus, users, template and ACL. Nothing in the general documentation is switched off. The Joomla-specific work is wiring the storefront with menu items, which is also what drives SEF routing.

---

1. Division of labor — what Joomla owns, what CBX owns

Unlike the Magento edition, almost everything belongs to CBX. This table exists mainly to show how little Joomla is responsible for:

Concern	Owned by	Notes
Configurator (pages, questions, answers, rules, calculations, visualization)	CBX	The whole configurator reference applies unchanged.
Product lists, product pages	CBX	Surfaced through Joomla menu items — see §4.
Cart & checkout	CBX	CBX runs its own storefront checkout.
Orders, invoices, manufacturing slips	CBX	cbcheckout_* tables; the Orders screen is fully present.
Customers & customer groups	CBX, on top of Joomla identities	Shoppers authenticate as Joomla users; the CBX customer record holds address, group and B2B data. See §6.
Transactional email	CBX	The Notifications screen drives per-status emails; CBX sends them through Joomla's mailer.
Tax, currencies, shipping, payment	CBX	All configured in the CBX menu.
Languages	Joomla site languages + CBX's own strings	Joomla supplies the language list; CBX translates its content in its own edit screens (EAV #__configbox_strings), not through Joomla language files.
Pages, menus, navigation	Joomla	Menu items are how the storefront becomes reachable — §4.
Users, groups, access levels, ACL	Joomla	CBX adds its own actions to Joomla's permission system — §5.
Template / look and feel	Joomla	CBX views render inside the site template.

2. Installing and updating

CBX ships as a Joomla package (pkg_configbox) installed through System → Install → Extensions. The package installs the component plus the module and plugins listed in §3, and sets blockChildUninstall, so the parts cannot be removed individually.

• Requirements (enforced by the installer script, which aborts with a readable message): Joomla 3.0 – 6.99, PHP 7.4 – 8.5.99, and the extensions gd, json, mbstring, mysqli among others. The pricing/rule engine ships ionCube-encoded, so the server also needs the ionCube Loader for its PHP version.
• Updating is a re-install of the package over the existing one (method="upgrade"). The manifest carries an <updateservers> entry but it is commented out, so Joomla's Update component will not offer CBX updates — do not expect one-click updates in System → Update.
• Database schema and data updates are CBX's own, not Joomla's: versioned scripts under helpers/updates/<version>.php, applied by ConfigboxUpdateHelper::applyUpdates() on init and from the CLI. A failed script sets failed_update_detected and freezes further updates. Full detail: migrations.
• Licensing is domain-bound; the key is entered in the CBX dashboard.

3. What the package installs

Extension	Type	Job
CBX (com_configbox)	component	The application itself — site and administrator
System - CBX (plg_system_configbox)	system plugin	Boots CBX into the request; serves the /cbx-api/… XHR endpoint
User - CBX (plg_user_configbox)	user plugin	Keeps Joomla users and CBX customer records in step
Authentication - CBX (plg_authentication_cbcheckout)	authentication plugin	Lets customers authenticate during checkout
CBX - Console commands (plg_console_configbox)	console plugin	Registers the configbox:* CLI commands — §7
CBX Currencies (mod_configboxcurrencies)	site module	Optional currency switcher for a template position

The release is built by tools/make-package.sh; the shipped set is declared by the MODULES / PLUGINS tables at the top of that script and <files> in tools/pkg_configbox.xml — adding an extension means editing both, and nowhere else.

The component manifest is the install contract, not the zip. Two rules, both learned the hard way on an upgrade of an existing 3.4.4 site (2026-09-06):

• It declares <element>com_configbox</element>. Joomla derives the element from <name> when none is given, and the name has read CBX since 2026-08-28 — a site that installed ConfigBox as com_configbox would otherwise get a second component com_cbx (with a colliding admin menu item) while its com_configbox stays at the old version.
• Its <files folder="site"> / <files folder="admin"> lists name every top-level folder and file the package ships. Joomla copies what the manifest names and nothing else, silently: a release once shipped generated/ inside the zip but not in the manifest, and every install fataled on the first record class. make-package.sh now fails the build when a staged entry is not named; adding a top-level directory to the component means adding it to the manifest in the same change.
• The installer deletes nothing on its own. An upgrade keeps every file of the old version that the new one does not overwrite, and ConfigBox discovers some parts by scanning directories (classes/rule_condition_types, classes/calc_term_types, the payment providers) - on the 3.4.4 site the retired ConfigboxConditionElementAttribute.php was still there and the rule editor offered it as a second "Answers to questions" category. So the component keeps the list of what earlier versions shipped and this one does not in helpers/retired_files.txt; the installer script's postflight removes those paths (best effort, never failing the install), and make-package.sh refuses a package whose staged files include any entry on the list, because the removal runs after the copy. Retiring a file, a view or a vendored library version means adding it to that list in the same change.

4. Wiring the storefront — menu items and SEF

A CBX view reaches visitors only through a published Joomla menu item. This is the one structural difference from the other hosts (WordPress uses a shortcode; Magento uses the catalog).

The CBX group of the Menu Item Type picker offers: Product List, Product, Configurator Page, Shopping Cart, Customer Account Page, Customer Login Page, Customer Registration Page, Edit Customer Account Page, Order Listing for Shop Managers, Terms and Conditions Page, Refund Policy Page and Custom. There is deliberately no Checkout type — checkout is reached from the cart.

You need far fewer items than it looks. The router resolves a configurator URL by walking from the most specific menu item to the least: an exact configuratorpage item → a parent product item → any productlist item. One Product List item therefore gives every product and configurator step a URL beneath it; per-product items are for deliberate site structure, not a requirement.

Readable paths (/en/demo-products/car/motor.html) come from the SEF Segment field on products and pages, which is translatable and must be unique per language. The full round trip — ConfigboxRouter, the controller SEF hooks, custom-view anchors and the /cbx-api/ endpoint — is documented separately in SEF URLs; read that before adding a custom view with its own clean URL.

5. ACL — the actions CBX registers

CBX declares its own actions in access.xml, so they appear in Joomla's System → Global Configuration → CBX → Permissions and per-group permission screens:

Action	Meaning
core.manage	Manage the component (the backend gate)
core.quickedit	Show the frontend quick-edit buttons. Display only — saving still needs backend permission
core.edit_templates	Edit CBX templates
core.edit_connectors	Edit connectors (plugin-like extensions to CBX behavior)
core.see_orders	See the front-end order listing for shop managers
core.release_invoices	Release invoices to the customer
core.upload_invoices	Upload and release invoices (with manual release configured)
core.download_invoices	Download invoices
core.change_invoices	Change invoices
core.edit_orders	Edit orders

The invoice and order actions are for shop staff, not customers — the language strings say so explicitly, and granting them to a public-facing group exposes other people's orders.

6. Identity — Joomla users and CBX customers

Shoppers sign in with their Joomla account; CBX does not run a second login. The user plugin maps the Joomla user to a CBX customer record, and a guest cart is moved onto the account on login rather than discarded. Address, company and VAT data live on the CBX side, not in the Joomla user profile. Guest ordering is available where the configuration allows it.

7. Command line

The configbox:* suite runs on Joomla's console:

php cli/joomla.php configbox:cache:clear
php cli/joomla.php configbox:migrate [--status]
php cli/joomla.php configbox:migrate:unblock
php cli/joomla.php configbox:run-task <controller> [<task>] [key=value ...] [--user=<selector>]
php cli/joomla.php configbox:config:get|config:set|config:list ...
php cli/joomla.php configbox:sysvar:get|sysvar:set|sysvar:list ...

Note the colon-separated names here — the WP-CLI wrapper hyphenates the same commands (wp configbox cache-clear), because WP-CLI subcommands cannot contain colons. --user accepts an e-mail, a CBX user id or platform:<host-user-id>; on WordPress the same option is --cb-user, since WP-CLI reserves --user. migrate --status reports whether work is outstanding without applying anything, so deploy scripts can gate on its exit code.

Commands are classes under the administrator component's src/Console, registered by the console plugin — the plugin must be enabled for php cli/joomla.php list to show them. The real work sits in the platform-agnostic ConfigboxCliHelper shared with the WordPress and Magento wrappers, so behavior matches across hosts. Full reference: CLI commands.

8. The Joomla 4/5 component wrapper

CBX predates Joomla 4's namespaced component model and does not use Joomla MVC. A thin adapter bridges the two:

• administrator/components/com_configbox/services/provider.php binds ComponentInterface to ConfigboxComponent.
• ConfigboxComponent delegates dispatch to Joomla's LegacyComponentDispatcher (which runs the existing configbox.php entry files) and returns the existing global ConfigboxRouter.
• The manifest registers the PSR-4 namespace Joomla\Component\Configbox for the wrapper only. CBX's own Kenedo-based code is intentionally un-namespaced and keeps its own bootstrap.

The stock MVCFactory / ComponentDispatcherFactory / RouterFactory providers are deliberately not registered: CBX uses neither Joomla MVC, nor Joomla categories, nor a RouterView router, so they would have nothing to resolve. Treat the wrapper as a boundary adapter — extend CBX through Kenedo, not by growing this layer.

9. File locations

What	Where
Application code	components/com_configbox/ (site side — models, views, controllers, helpers, Kenedo)
Admin wrapper, ACL, console commands	administrator/components/com_configbox/
Customization layer	components/com_configbox/data/customization
Encoded engine	components/com_configbox/helpers/encoded/{13,14,15}/
Logs	logs/configbox/

10. Reading map — the general docs from a Joomla seat

Joomla is the reference host, so everything applies: nothing is hidden and no system is owned by the host. Read in this order:

1. Admin Guide — the operator manual, screenshots taken from a Joomla store, plus the Joomla host article.
2. functional/ — behavior specs.
3. technical/ — implementation reference, including migrations and CLI commands.
4. customization/ — the upgrade-safe customization layer.
5. SEF URLs — Joomla-only routing detail.

11. Gotchas

• No Joomla update-server updates. The <updateservers> entry is commented out; updating means installing the package again.
• The package blocks child uninstall. Remove CBX through the package, not by uninstalling the component or a plugin on its own.
• A missing menu item silently degrades URLs. Without a matching published item, links fall back to index.php?option=com_configbox&… instead of clean paths — see §4 and the SEF doc.
• core.quickedit is display-only. It shows the frontend edit buttons; saving still requires backend permissions. Granting it alone does not create an editing role.
• The console plugin must stay enabled or the CLI commands vanish from joomla.php list.
• Schema updates run on init. Opening any CBX page after deploying new code applies outstanding migration scripts — take a database snapshot before deploying, not after.
• CBX's language content is not in Joomla language files. Product, question and answer text lives in #__configbox_strings and is edited in the CBX screens; the .ini files only cover the interface chrome.