Skip to main content
Version: 3.x

CBX — Customization Guides

Version
3.x
Updated
View markdown

How-to guides for extending CBX through its upgrade-safe customization layer — one directory per install, resolved by KenedoPlatform::p()->getDirCustomization(). Its location is per platform: data/customization/ inside the component on Joomla, wp-content/plugins/configbox-customization/ on WordPress (a sibling of the plugin), and the Rovexo_ConfigboxCustomizations module's view/customizations/ directory on Magento 2 — see the overview's §1.1 table. The guides write paths in the Joomla spelling (data/customization/<x>); resolve <x> against your platform's directory. Where functional/ describes what the app does and technical/ describes how the current code is built, this track is task-oriented: concrete recipes for adding your own behavior without modifying (and later losing) core component files.

The customization layer is the supported extension point: files placed under data/customization/ extend or shadow their core counterparts and survive component updates. (Exactly how each kind resolves — shadow, merge, register, or boot-time pre-emption, and which direction wins — varies per mechanism; the overview maps all of it.) It is gitignored in this repository (it is the developer's/integrator's local code), so these guides describe the structure and contracts you build against rather than checked-in examples.

Start here​

  • com_configbox_customization_overview.md — Overview & extension-point map. The orientation guide: what the customization layer is, the one resolution rule that governs almost all of it (a customization path and a core path, one preferred over the other — which way depends on the mechanism), a table of every extension point with where it resolves in code, and a decision guide ("I want to change X → use mechanism Y"). Read this before the individual guides.

New extension points, and what changed under them: Latest features → platform & extensibility — the what's-new cut for integrators: site-specific CLI commands, question types the AI can operate, custom calc term types, payment connectors, on-screen help, and the move from a silent false to exceptions. Latest features is the whole track.

Guides​

  • com_configbox_overriding_views_and_templates.md — Overriding views & templates. The most common task: change a screen's markup via a template override (templates/<view>/<layout>.php), the three-slot template precedence chain, what variables a template has ($this is the view), the view-class vs. template precedence asymmetry (view classes are not "customization wins"), adding a brand-new view, and a worked example.
  • com_configbox_custom_properties.md — Creating custom Kenedo Properties. End-to-end: how a type string resolves to your class + template, every lifecycle hook (request → validate → store → render → list → copy/delete) and when to override it, external storage, conditional applicability, attaching per-property CSS/JS, a complete worked colorpicker example, and a deployment checklist.
  • com_configbox_help_customization.md — On-screen help. Make the admin's help describe your install: append to (or mode: replace) any screen's note, add your own articles in a Customizations section of the guide, or shadow a shipped article by putting a file at the same path. One help/ folder mirroring the guide's layout, images kept in the customization directory beside the file that uses them, nothing registered and no cache to clear. The counterpart to the fields you add — a customized form whose help still describes the stock screen is only half-delivered.
  • com_configbox_extending_stock_models.md — Extending stock models. Add a field to (or tweak a field on) an existing model via model_property_customization/ — the exact file/function/return contract, how the merge replaces vs. adds by name, the clone-then-change pattern for editing one core field, the migration that delivers the column, and a worked example.
  • com_configbox_overriding_controllers_and_models.md — Overriding controllers & models (behavior). The precedence rule — controllers, models, and view classes all load core-first (new-only), so the customization folders add new classes and don't shadow core ones — why changing an existing core class means system_overrides/, when to reach for that vs. observers vs. property injection, the Cbcheckout→Configbox legacy fallback, and worked examples.
  • com_configbox_custom_rule_conditions.md — Custom rule condition types. Add a new "if…" to the Rule Editor: the CustomCondition<Type> naming/resolution contract, the three required methods (getEvaluationResult / getConditionsPanelHtml / getConditionHtml) and optional hooks, the $selections / $conditionData shapes and the data-*→conditionData bridge, performance notes (the evaluator is hot), and a worked Weekday example. (The engine is encoded; condition types are plaintext — no encoder needed.)
  • com_configbox_custom_question_types.md — Custom question types. Add a new kind of configurator input: why the view folder (views/question_<type>/) is what registers the type in the admin dropdown, the optional ConfigboxQuestion<Type> class and its silent fallback to the base class, the five-step template chain, per-type admin fields via model_property_customization/questions.php and appliesWhen, and the composite-value trap (floatval() of a JSON selection is 0).
  • com_configbox_question_types_and_ai.md — Question types the AI understands and controls. The companion contract that makes a custom type self-describing, so the chat advisor and every headless client can operate it like a stock type: designing the selection shape, canonical storage (getStorableValue), the comparison contract (isSameSelection / isEmptySelection), the AI descriptors (getSelectionFormatHint / getSelectionSchema / getChoiceList / getConstraintHints), sub-value delegation for rules and pricing, the frontend registration helper, the reveal contract for collapse/expand page flows, and how to pin it all in API specs.
  • com_configbox_custom_calc_term_types.md — Custom calc term types. Add a building block to formula calculations — usually how a composite question type reaches a price: eager loading from calc_term_types/, the class-name suffix as a stored identifier, the three abstract methods (getTermResult / getTermsPanelHtml / getTermHtml), why getTermResult is hot, and the deleted-question guard that keeps a stale term from taking the formula editor down.
  • com_configbox_events_and_observers.md — Events & observers. React to (or augment/compute for) CBX events — the safest, additive extension point: how the dispatcher works and registers observers (before/after built-ins), the three event styles (react / by-reference augment / returnLast compute), the two-part deployment (file + #__configbox_connectors row), the event catalog with signatures, the onOrderPlaced-aren't-events trap, and a worked order-webhook example.
  • com_configbox_payment_connectors.md — Payment (PSP) connectors. Add a payment method as a convention-based folder (no base class): the customization-first folder resolution, the file contract (administration.php metadata functions, settings.php admin form, bridge.php checkout hand-off, result.php confirmation, ipn.php callback handler), the IPN class-name quirk (Ipn<ucwords(strtolower(name))>), IPN security, and a worked offline-method example.
  • com_configbox_assets_and_amd.md — Assets (CSS) & JavaScript (AMD). Add CSS/JS with no build step: the auto-detected entry points (custom.css, custom.js, custom_questions.js), the configbox/custom AMD namespace, the server→client appConfig gateway, the view-asset engine (per-view/per-property CSS + moduleId::method init calls, XHR-safe), registering third-party libs via cbGetCustomRequirePaths/cbGetCustomRequireShims, and the min/cache-busting rules (don't .min your custom JS).
  • com_configbox_admin_ui_migration.md — Admin UI migration (major release). What changed in the backend form/list markup, CSS class names (the new cb-* prefix, Bootstrap 5 components, .cb-content scoping) and JS — and how to amend custom admin CSS/JS or template overrides. The stable .trigger-* (JS hooks) and .property-* (property styling) conventions that do not change. Maintained as each migration slice ships.
  • com_configbox_custom_cli_commands.md — Custom CLI commands. Add site-specific commands to the ConfigBox CLI suite under the reserved custom namespace (WordPress: wp configbox custom <command>): the one-file contract (cli/commands.php returns name → shortdesc/synopsis/callback), the callback's args/options/exit-code interface, and the failure-isolation design — the file loads only when the custom dispatcher runs, so a broken commands file can never take down the stock commands.
  • com_configbox_language_overrides.md — Language overrides. Change displayed UI text via language_overrides/<tag>/overrides.ini (loaded last, wins): the two-text-systems distinction (INI/UI strings here vs. admin-authored content in #__configbox_strings), the load order, how to find a string's key, INI syntax gotchas, and per-language deployment.
  • com_configbox_system_overrides_and_boot_hooks.md — System overrides & boot hooks (escape hatch). Replace a framework/helper class that has no per-type loader, and run PHP at boot/DB-connect: how eager pre-emption beats the lazy autoloader (and its hard limit — the class mustn't already be loaded), the _-first load order, the boot-hook functions (cbGetCustomRequirePaths, getPostDbConnectQueries, …), the getInitQueries.php DB-connect hook, the data/store/private/settings/ per-install slot, and the standing re-diff-after-update maintenance cost.

The customization track now covers every supported extension point. Future additions would be incremental (new mechanisms introduced by the component) or deeper worked examples.

Version migration​

  • Customization code migration to CBX 4 — now lives inside the component at ../migration-to-cb4/ so it ships with releases and reaches the WordPress/Magento 2 projects (all mount the same component repo). The running record of breaking changes in the CBX 4 refactor and how to realign your customization code — a dated breaking-changes log plus a playbook per affected customization kind (what the core auto-converts for you, and what you must edit by hand). Start here when a customization stops working after an update; it is maintained as each CBX 4 slice ships.

Prerequisites​

Read technical/com_configbox_kenedo_mvc.md (§4, Kenedo Properties) first if the property-driven model is unfamiliar, and technical/com_configbox_migrations.md for delivering any DB schema a customization needs (the customization migration track, data/customization/updates/).

Where customization code lives (quick map)​

Shown at its Joomla location; on WordPress the same tree sits in wp-content/plugins/configbox-customization/, on Magento 2 in app/code/Rovexo/ConfigboxCustomizations/view/customizations/ (overview §1.1).

data/customization/
  controllers/                       ← add NEW controllers (core-first: does NOT shadow a core controller)
  models/                            ← add NEW models (core-first: does NOT shadow a core model)
  views/                             ← add NEW view classes (core-first: does NOT shadow a core view)
  templates/                         ← override view templates / markup (customization-first)
  properties/        + tmpl/         ← custom Kenedo property types (+ form templates)
  model_property_customization/      ← inject/retune property defs on stock models (merge)
  question_types/                    ← custom question type classes (ConfigboxQuestion<Type>)
  rule_condition_types/              ← custom rule condition types (CustomCondition<Type>)
  calc_term_types/                   ← custom calc term types (CustomCalcTerm<Type>)
  custom_observers/                  ← event observers (+ a #__configbox_connectors row)
  psp_connectors/                    ← payment method connectors (folder per method)
  system_overrides/                  ← replace a core class / boot hooks (escape hatch)
  language_overrides/<tag>/          ← overrides.ini — change UI text (loaded last)
  assets/  (css, javascript)         ← custom CSS / AMD JS modules (configbox/custom)
  cli/commands.php                   ← custom CLI commands (`wp configbox custom <command>`)
  updates/                           ← customization-track DB migrations

For the precise resolution rule per mechanism (and the per-kind precedence asymmetries), see the overview.

Last updated on