Themes & widgets

Appearance in the admin panel is where you install and switch themes, and where you place widgets into the sections a theme offers.

The bundled theme

New installs get Storefront: a real, maintained theme, not a placeholder. It has light and dark modes, three colour palettes that meet WCAG-AA (the standard for readable colour contrast) and its own settings screen, and it is the theme the live demo runs.

Start by configuring it rather than replacing it. Most sites need a logo, a palette and their own hero copy, which is a settings change, not a theme change.

Installing another theme

Appearance → Manage themes has three tabs:

Tab	What it shows
Themes	What is installed. Current theme is the live one; Other themes follow.
Browse	The theme registry: the same catalog oc-cli.php reads. One click installs.
Updates	Installed themes with a newer version, with a count in the tab.

Each theme is a card carrying its version, its author, a short description and a state badge (Live, Installed), with the buttons that apply to it: Activate, Preview, Delete.

Plugins → Manage plugins works the same way, with Installed, Browse and Updates tabs and the same card layout.

A theme zip can also be uploaded directly, for something you built or bought outside the catalog.

From a shell:

php oc-cli.php theme:list
php oc-cli.php theme:activate --theme=storefront
php oc-cli.php market:install storefront --type=theme

theme:activate is the way back when a theme breaks the site badly enough that you cannot reach the admin panel.

Before you switch

Themes are not interchangeable. Check three things:

• Widget sections differ between themes. A theme declares its own sections, so widgets placed for one theme may have nowhere to go in another. They are not deleted; they stop rendering until you place them again.
• Compatibility. A theme declares the ShopClass and PHP versions it supports, and the card says plainly whether it runs here (Needs 6.5 or newer, Needs PHP 8.2) instead of leaving you to compare numbers.
• Try it on a copy. Especially for a site with traffic.

Deleting a theme removes its files. Switch away from it first.

Widgets

A widget is a block of content placed into a section of the page. Theme templates declare which sections exist: a sidebar, a footer column, a strip above the listing grid.

Appearance → Manage widgets shows every section with what is in it. Add widget picks a type, then Add to which section? places it. Drag to reorder within a section; the order is the order visitors see.

Built-in widget types

Type	What it is
Rich text	A block of formatted text. Blank lines become paragraphs.
Image	An image from your media library, optionally linking somewhere.
Custom Code (HTML / JavaScript)	Raw markup and script.

Plugins register further types, which appear in the same picker.

Only full admins can add a Custom Code widget; moderators cannot.

Custom Code runs on your visitors’ browsers

Anything you paste there executes on every page the widget appears on. Paste only code you understand, from a source you trust. A “free analytics snippet” from a forum post is the classic way a classifieds site starts serving malware to its own users.

Page builder

The same widget system composes whole pages. A static page can use the Page builder (blocks) template instead of the text editor, and is then assembled from widget blocks.

See pages.

Customising a theme

You can edit a theme’s files directly, and it will work, until the theme updates and overwrites your changes.

Two durable approaches:

• A child theme. Declare Parent Theme in the child’s header block and override only the templates you change. The parent keeps updating underneath. See Child themes for what is inherited and the two rules that stop a child breaking its parent.
• A plugin. Styles, scripts and behaviour can be added from a plugin with the functions that register them, leaving the theme untouched entirely.

For building a theme from scratch, see the package specification.