WBAMS is extended by modules. An addon module adds a feature and its own administration pages; a gateway module takes money. They are separate contracts and are configured in different places.
Addon modules
An addon lives in its own directory under the extensions tree, declares its configuration, and is activated from Settings. Once active it can add administration pages, register hooks, define permissions and create its own tables.
Activating an addon that takes over an earlier addon’s settings in its own activation keeps what that activation did: since 1.11.0 the list of active addons is no longer read before the addon runs and written back afterwards. Updates never remove an addon — an update deletes only files a release lists as obsolete, and no release lists an addon — so an addon’s files, tables and settings stay as they are until you remove it.
Page-builder sections from an addon
An active addon offers sections by adding a cms-sections.json file to its own directory, without changing the CMS or a theme:
{
"schema": 1,
"sections": {
"ExampleOpeningTimes": {
"title": "Opening Times",
"description": "Today's opening times, from the add-on.",
"category": "Example",
"script": "cms/ExampleOpeningTimes.js",
"template": "cms/ExampleOpeningTimes.tpl",
"prepare": "WBAMS\\Extension\\Addon\\Example\\Website::openingTimes"
}
}
}
example gives Example…, my_shop gives MyShop… — followed by a capital letter or a digit and more letters and digits, up to 64 characters in all.WbamsSectionKit.define({...})). It is loaded after the core sections, and the shared Section design panel wraps it like any other.$block (the section’s saved data, as prepared), $blockkey, $section, $WEB_ROOT and $WLANG. Start it with {if $block.sechidden neq "true"} so the Show/Hide switch works, and reuse the CMS section classes (sec, container, sec-title…): addons do not add stylesheets to CMS pages.method(array $block, string $type) before the template is rendered. It returns the data the template prints, or null to leave the section out of the page. An exception leaves the section out and is written to the activity log.The script, the template and the prepare method must all be valid, and the files must be inside the addon’s directory, or the section is not offered. A name that two addons declare, or that a core section uses, is offered by neither. Only active addons are read. Data the builder needs for its fields, such as the choices of a select, is printed by the addon as a JavaScript global through the OnControlHeadOutput hook.
Checking settings and showing status
An addon can check its own settings on Settings › Addon Modules and show how it stands on its card, with three optional functions in its main file. They follow the pattern a gateway module follows on its own settings page.
<module>_preferences_validate(array $settings)<module>_preferences_saved(array $settings)$settings['existing']. This is the place for a check that calls another service, such as a license or a connection test. Return ['status' => 'success'|'info'|'error', 'description' => '…'] to add a line to the save’s confirmation. An exception is shown as an error, and the settings stay saved.<module>_preferences_status(array $settings)null, or ['label' => '…', 'tone' => 'positive'|'neutral'|'warning'|'danger', 'detail' => '…']: the label is a pill beside Active on the card, and the detail a line under the card’s heading.The first two run for the addon whose Save button was pressed, and for any other addon whose values change in the same save.
It runs on every view of the page. Keep the result of the check your post-save function makes, with your own settings, and report that. Tie it to the values it was made for, so that after a change the status reads as not checked rather than as the old answer, and never keep a key or password in it.
What an addon returns is shown as plain text. Tags are removed; a label is cut at 40 characters, a detail at 240 and a message at 500; an unknown tone shows as neutral. An error that is not an exception, such as a TypeError or a missing class, is written to the activity log with its details and shown to the administrator in general words. Anything the function prints is discarded.
function example_preferences_validate(array $settings): void
{
if (($settings['api_key'] ?? '') !== '' && ($settings['account'] ?? '') === '') {
throw new \WBAMS\Fault\Extension\InvalidPreferences('Enter the account that goes with the API key.');
}
}
function example_preferences_status(array $settings): ?array
{
if (($settings['api_key'] ?? '') === '') {
return ['label' => 'Not connected', 'tone' => 'warning', 'detail' => 'Enter the API key, then save.'];
}
return ['label' => 'Connected', 'tone' => 'positive'];
}
Uploading a theme or an app
Since 1.13.8 a theme or an app is added from its zip file in the admin area, without the server, cPanel or FTP: Upload a theme on Setup › Website themes, and Upload an app on Setup › Addon Modules. It takes an administrator whose role has the Install Themes and Apps permission (Full Administrator gets it with the update), and WBAMS asks for that administrator's password again before the page opens. An update of a theme or app you uploaded is uploaded the same way.
- Choose the file.The theme's or app's zip, from its seller. Nothing is installed in this step.
- Check.WBAMS reads the zip without unpacking it and shows what it found: the name, version, who made it, its folder and size, and what it checked (its folder, its files, its size, the WBAMS it needs and its license). A file that fails is refused with the reason in plain words, and nothing on the website changes. A paid package can take its license key here, or later.
- Install.WBAMS checks the file again, keeps the installed copy first when this is an update, puts the files in place and writes each step to the activity log. When a step cannot finish, it stops before changing anything or puts the earlier copy straight back.
A new theme waits among your themes, and visitors keep the current one until you choose it with Use on the website. A new app is switched off until you activate it on the Apps page; an updated app that is switched on finishes its update the next time the Apps page opens.
What a package holds
aurora/…) or at its place in a site (themes/aurora/…, extensions/apps/example/…). Finder's __MACOSX folder and .DS_Store files are left out.theme.yaml that gives the theme its name, and header.tpl and footer.tpl unless it builds on another theme. Its folder name takes lower-case letters, digits, - and _.example/example.php), described by its wbams.json. Its folder name takes lower-case letters, digits and _, starting with a letter..htaccess, .user.ini, .phar and .phtml files, programs, hidden files, links, password-protected entries, and any path that leaves the package's folder.requires: { wbams: "1.13.8" } names the oldest WBAMS it works on; an older site is asked to update WBAMS first. A theme that builds on a theme the website does not have is refused.# theme.yaml
name: "Aurora"
version: "1.0.0" # or a VERSION file beside theme.yaml
author: "Your company"
description: "A short line about the theme."
requires: { wbams: "1.13.8" }
license: { product: "aurora", option: "theme_aurora", name: "Aurora", buy: "https://example.com/aurora" }
config: { parent: "serepok" } # only for a theme that builds on another
{
"type": "wbams-addons",
"version": "1.0.0",
"description": { "name": "Example", "tagline": "A short line about the app." },
"authors": [{ "name": "Your company" }],
"requires": { "wbams": "1.13.8" },
"licensing": { "product": "example", "option": "app_example", "name": "Example", "buy": "https://example.com/example" }
}
An app without a version in its wbams.json takes the one in its own <name>.php, where that file is plain PHP. Leave out license (a theme) or licensing (an app) for a free package.
Paid themes and apps
A paid package names its license: product is the product on the WBAMS license service whose key unlocks it, option an option of a WBAMS license that includes it without a key of its own (either may be left out), and buy the page where it is bought.
The demo bar
For a website that shows off themes. The Demo bar card on Setup › Website themes puts a slim bar along the bottom of every page that tells visitors which theme they see, with its Buy button.
buy address in its theme.yaml.Gateway modules
A gateway module implements one payment provider. WBAMS 1.12.0 ships 20 of them: Stripe, Stripe ACH, Stripe SEPA and Stripe Dynamic Payments; PayPal, Credit/Debit Card (PayPal), PayPal Basic, PayPal Website Payments Pro, PayPal Pro Reference Payments and Payflow Pro; Authorize.net, Authorize.net CIM and Authorize.net Echeck; Helcim, Payment Express, PayJunction and Payments Gateway; and Bank Transfer and Mail In Payment. A gateway declares its configuration fields, renders the payment step, and receives the provider’s callback.
Callbacks are the part that breaks
A gateway callback is an unauthenticated request from a third party. It must verify the message is genuinely from the provider before acting on it, using whatever signature or verification call the provider offers.
Anyone can post an invoice ID. Verify the message against the provider before recording a payment.
- Confirm the callback URL the provider holds matches the System URL currently configured.
- Read the gateway log to see what actually arrived, rather than what the provider’s dashboard says it sent.
- Check the module log for what the module did with it.
Provider vocabulary is not yours to change
Payment providers define their own event names and status values, and WBAMS uses them verbatim. PayPal’s BILLING.SUBSCRIPTION.CANCELLED keeps the provider’s spelling even though WBAMS itself now uses Canceled. Respelling one of these to match house style stops the events matching.
Logging
Modules log their requests and responses to the module log. Log enough to diagnose a failure without logging credentials, card data or full customer records. A module that logs nothing is a module you cannot support.
Retiring a module
Deactivate the module before removing its files, so the product stops calling it. A module whose files are deleted while still active produces fatal errors on the pages that expected it, not a graceful absence.