# CBX on Joomla — Platform Guide

> > Audience: integrators and developers running CBX on Joomla · Scope: what is specific to the Joomla edition — installation, the extensions that ship, storef…

Source: CBX documentation, version 3.x (released). Canonical page: https://docs.configbox.at/docs/platform/joomla/joomla_platform_guide. Last updated 2026-08-01.

---
> **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](https://docs.configbox.at/docs/admin-guide/) —
> start with [CBX on Joomla](https://docs.configbox.at/docs/admin-guide/getting-started/platform/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](https://docs.configbox.at/docs/technical/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 `/cb-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.

## 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 `/cb-api/` endpoint — is
documented separately in [SEF URLs](https://docs.configbox.at/docs/platform/joomla/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:

```bash
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](https://docs.configbox.at/docs/technical/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](https://docs.configbox.at/docs/admin-guide/) — the operator manual, screenshots taken from a
   Joomla store, plus the [Joomla host article](https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-joomla).
2. `functional/` — behavior specs.
3. `technical/` — implementation reference, including
   [migrations](https://docs.configbox.at/docs/technical/migrations) and
   [CLI commands](https://docs.configbox.at/docs/technical/cli_commands).
4. `customization/` — the upgrade-safe customization layer.
5. [SEF URLs](https://docs.configbox.at/docs/platform/joomla/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.