Readme
=== PlayForge ===
Contributors: playforge Requires at least: 6.0 Tested up to: 7.0 Requires PHP: 7.4 Version: 1.0.21 License: GNU General Public License v2 or later License URI: http://www.gnu.org/licenses/gpl-2.0.html Tags: business, e-commerce, portfolio, custom-logo, custom-menu, featured-images, footer-widgets, left-sidebar, right-sidebar, full-width-template, translation-ready, threaded-comments
A Bootstrap 5 business and catalogue theme for indoor playground, trampoline park and family entertainment centre manufacturers. Ported from the Hugo theme of the same name.
== Description ==
PlayForge is a classic (PHP template) WordPress theme built on Bootstrap 5.3.3. It is a port of the Hugo theme "Playforge", carrying over its design tokens, page header band, product cards and blog cards, and rebuilding the rest on WordPress-native foundations: the Settings API, nav menu locations, widget areas, WooCommerce hooks and Elementor.
Features:
- Bootstrap 5.3.3 and Bootstrap Icons 1.11.3, bundled locally — the theme makes no external requests at runtime.
- A Theme Options panel (Appearance → PlayForge Options, also a top-level menu) with eight tabs: License, Contact Info, Header & Footer, Homepage, Social Media, Layout, Import / Export, and Author & Help.
- A Homepage builder — one switch turns the front page into a banner, product categories, latest products, a tabbed Editor's Choice block, an About Us block with a click-to-play video, and latest news, each section switchable on its own, with four custom HTML slots between them for anything else.
- Serial-key license activation against a remote license server, with a footer reminder when inactive. Activation is never required for any front-end feature to work.
- Four nav menu locations: Main Menu, Foot Menu 1, Foot Menu 2, Foot Menu 3.
- Six page layouts, selectable globally and per post/page: full-box (default), full-screen, elementor-full-canvas, elementor-boxed, 2-cols-with-left-sidebar, 2-cols-with-right-sidebar.
- WooCommerce support, including styled product listing and product detail pages, plus WhatsApp and email enquiry buttons on products.
- Elementor and Elementor Pro Theme Builder compatible.
== Installation ==
- Upload the
playforgefolder towp-content/themes/, or install the ZIP through Appearance → Themes → Add New. - Activate the theme through Appearance → Themes.
- Go to PlayForge Options in the admin menu and fill in the Contact Info and Header & Footer tabs.
- Go to Appearance → Menus and assign menus to the four locations.
- Optional: enter your serial key on the License tab.
== Theme Options ==
= License =
Enter the serial key supplied with your purchase and press Activate. The theme contacts the license server, which returns a JSON verdict.
If the license is not active, a single line — "License not activated, please activate" — appears in the site footer, and an admin notice appears in the dashboard. Nothing else changes. Every template, option, layout, menu, widget area and WooCommerce feature works identically whether or not the license is active. The theme never degrades, watermarks or disables front-end output.
The endpoint defaults to the theme author's server. To point it elsewhere, define the constant in wp-config.php before WordPress loads the theme:
define( 'PLAYFORGE_LICENSE_API', 'https://example.com/wp-json/playforge/v1/license' );or filter it:
add_filter( 'playforge_license_api_url', function () {
return 'https://example.com/wp-json/playforge/v1/license';
} );The theme POSTs action (activate | deactivate | check), license_key, site_url, theme and version, and expects JSON:
{ "success": true, "status": "active", "expires": "2027-01-31", "message": "..." }
{ "success": false, "status": "invalid", "message": "Unknown serial key" }License checks fail open. If the server is unreachable, returns a non-2xx status, or returns a body that is not a JSON object, the stored status is left untouched — a network outage can never deactivate a working site. Only an explicit, well-formed negative response from the server marks a license inactive. A background check runs once a day and its result is cached for 12 hours.
To short-circuit the check in development:
add_filter( 'playforge_pre_is_licensed', '__return_true' );= Contact Info =
Company name, physical address, landline phone, mobile phone, email and WhatsApp number. These feed the top strip, the footer contact column, the floating contact buttons and the WooCommerce product enquiry buttons.
The WhatsApp number falls back through WhatsApp → mobile → landline, and non-digits are stripped before the wa.me link is built.
= Header & Footer =
Header logo, footer logo, company brief introduction, footer copyright, the top strip message, the header call-to-action button, and the default page header image. Two checkboxes toggle the top strip and the floating contact buttons.
Leave Footer copyright empty to get "© {year} {Company name}. All rights reserved." automatically.
The header logo falls back to the WordPress Custom Logo (Appearance → Customize), and then to the site title.
Under Custom code are two boxes for snippets no theme can anticipate. Custom HTML on header is printed inside <head> on every page and Custom HTML on footer just before </body> — analytics and tag manager code, a search-console verification tag, a <style> block, a chat widget, JavaScript of your own. Both are printed exactly as typed: no paragraph tags, no shortcode pass, nothing rewritten, because a tracking snippet that has been reformatted is a tracking snippet that no longer works.
The header box goes in after the theme stylesheet, so CSS there overrides the theme, and the footer box after the theme's own scripts, so JavaScript there can call into them. Anything that does not have to run early belongs in the footer, where it does not delay rendering. Both are empty by default, and while a box is empty nothing whatsoever is printed for it.
Whether a <script> tag survives saving depends on who is saving it. WordPress calls that capability unfiltered_html, and an administrator on a single-site install has it; on multisite only a Super Admin does, and any site that defines DISALLOW_UNFILTERED_HTML gives it to nobody. Without it a snippet is filtered on save exactly as a post's content would be, which drops <script> and <iframe> — so if a snippet appears to save but comes back shortened, that is why, and the fix is the capability rather than the field.
= Homepage =
Enable Homepage builder is off by default, and while it is off this tab changes nothing: the front page renders through the usual template, from its own content. Turning it on hands the front page to the layout_homepage.php template, which assembles the six sections below, plus four custom HTML slots between them. The page you have set as your front page keeps its content untouched in the database and gets it back the moment the switch goes off again.
The template also carries a Template Name, "Homepage (PlayForge)", so you can pick it under Page Attributes → Template on any page and lay the homepage out on a draft before switching it on for the live front page.
Each section has its own Enable box, and every title and subtitle is optional — leave one empty and the heading above that section is simply not printed.
- Section 1 — Banner. One content field, printed edge to edge with no container of its own so a hero or slider shortcode fills the width. Shortcodes, HTML and embeds all work; wrap the content in a
<div class="container">yourself to keep it boxed. - Section 2 — Product Categories. WooCommerce product categories as cards, four per row. Tick the categories to show and they appear in the order set on Products → Categories, empty ones included; tick nothing and the section falls back to the first n by name with empty categories hidden — the same rules as WooCommerce's own
[product_categories]. Each card is an image and a heading linking to the category, with that category's subcategories under them as a list of text links, one per line, up to twenty. Three lines are reserved so the cards in a row stay level; a category with no subcategories shows the card with an empty list. The card uses the theme's.product-card, so it matches the product grid below it. - Section 3 — Latest Products. The newest WooCommerce products, through WooCommerce's own loop, so the cards are identical to the shop page's. Hidden and out-of-catalogue products are skipped, and the "hide out of stock items" setting is respected. Four per row.
- Section 3A — Editor's Choice. A tab per product category, with a grid of that category's newest products under it. Tick the categories to offer, and set how many products each tab shows — the count applies per tab, not across the section. The grid swaps as a visitor moves the pointer across the tabs, and when one is tapped on a touch screen. Tab order follows the drag-and-drop order on Products → Categories, so it is arranged there rather than in Theme Options. A ticked category with no visible products is dropped rather than left as a tab that opens onto nothing, and with no category ticked the section renders nothing at all.
- Section 4 — About Us. Title, subtitle, a content field that takes shortcodes, a video URL and a cover image. Two columns: media on the left, copy on the right — or full-width copy when neither a video nor a cover is set.
- Section 5 — Latest News. The newest posts in the same three-per-row card grid as the blog index, plus an optional button. The button needs both its text and its URL to appear.
Between them sit four Custom HTML slots — after Section 1, after Section 3A, after Section 4 and after Section 5 — for a row the five built-in sections do not cover. Each has its own Enable box and one field, and an empty field renders nothing at all, not even a wrapper.
A slot's content is printed exactly as typed, edge to edge. Shortcodes run, but no paragraph tags are added and no line break becomes a <br>, unlike the banner and About Us copy fields — hand-written markup comes out the way you wrote it. To make a slot line up with the sections around it, wrap it in a <section class="pf-section"> holding a <div class="container">; add band to that section for the tinted background the built-in sections alternate with. All of the theme's design classes are available: section-title, section-kicker, btn-brand, product-card, blog-card, tag, hero, metric-row.
An author without the unfiltered_html capability — anything below Administrator on a single site — has their markup filtered through wp_kses_post() on save, the same rule WordPress applies to post content, which drops <script> and <iframe>. Shortcodes survive that filtering, so an embed plugin's shortcode is the way to place a player in a slot as a non-administrator.
Sections 2, 3 and 3A read WooCommerce data and print nothing at all while WooCommerce is inactive; anything you have entered stays stored and takes effect again on reactivation. Every panel of Editor's Choice is in the page from the start rather than fetched when a tab opens, so the products are indexed and the first tab shows a complete grid with JavaScript off.
The About Us video accepts a YouTube, Vimeo or other oEmbed page address, or a direct link to an .mp4. With a cover image set, the cover is shown with a play button over it and the provider's player is only fetched once a visitor presses play — the homepage makes no third-party request until then. A direct video file uses <video> with the cover as its poster, which behaves the same way natively. The oEmbed lookup is cached for a day, keyed by the address, so changing the address refreshes it by itself.
= Social Media =
Facebook, LinkedIn, Instagram, Twitter, YouTube and TikTok. Only the ones you fill in are rendered.
= Layout =
Sets the default layout for Pages and for the Blog & archives separately. Individual posts and pages can override it in the "PlayForge Layout" box in the editor sidebar; leaving that set to "Inherit from Theme Options" uses the default.
Resolution order: per-post setting → the relevant Theme Options default → full-box.
The two-column layouts only render a sidebar when the widget area they would show actually contains widgets, so an empty sidebar never leaves a blank column.
Shop and product pages do not follow these two settings; they have their own on the WooCommerce tab.
= WooCommerce =
Shown only while WooCommerce is active. Three settings:
- Product list layout — the shop page and the product category and tag archives.
- Product detail layout — single product pages. An individual product overrides it from the "PlayForge Layout" box on its edit screen.
- Products per page — 12, 16 or 20. Each is a whole number of four-product rows.
Both layout settings offer a deliberately short list: full-box (labelled "Full Width", the boxed container with no sidebar) or 2-cols-with-left-sidebar. A shop archive is a grid the theme builds itself, so the Elementor bare layouts have nothing to hand the canvas to, and a right sidebar would put filters after the grid in reading order.
The sidebar those layouts show is the WooCommerce Sidebar widget area, separate from the general Sidebar — see "Widget Areas".
Cart, checkout and account are ordinary Pages and follow the Pages default on the Layout tab.
= Import / Export =
Every setting from the other tabs, shown as JSON in an editable box, grouped by the tab it belongs to and in the same order as the tabs. Three things can be done with it:
- Copy to clipboard — the whole document, for pasting somewhere you keep records.
- Export (download) — the same document as a file named for the site and the date, so several sites' backups can share a downloads folder.
- Upload a .json file — reads a file into the box. The file is read in the browser and never uploaded to the server, so nothing is written to your uploads directory. Loading a file saves nothing on its own; the contents still have to be imported deliberately, which leaves room to read what arrived first.
Choosing Save & Refresh writes what the box contains. Only the settings the file mentions are written — anything absent keeps its current value, so a partial or hand-trimmed file is safe. Entries that are not settings of this theme are counted and ignored rather than stored. Every value is checked on the way in exactly as it would be if it had been typed into its own field: limited HTML on copy fields, disallowed protocols turned away on links, counts clamped to their bounds, layout choices matched against the offered ones, and category IDs verified against real categories. An import can therefore write nothing the options panel itself could not write.
License details are in neither the export nor anything an import is permitted to write, because a license belongs to the site it was activated on. This tab holds no settings of its own, so it cannot appear in its own export.
= Author & Help =
Theme author and version details, plus the help documentation: getting started, the menu locations, the page layouts, Elementor notes, WooCommerce notes and the widget areas.
== Menu Locations ==
main— Main Menu, in the sticky navbar. Nests to any depth.footer-1— Foot Menu 1, second footer column.footer-2— Foot Menu 2, third footer column.footer-3— Foot Menu 3, fourth footer column, at the right-hand end.
A menu item whose title is a single hyphen (-) renders as a dropdown divider instead of a link, carried over from the Hugo theme's convention.
On the desktop layout a submenu opens when the pointer is over its parent item; on touch screens and the collapsed mobile menu it opens from the chevron button beside the parent. Either way the item text stays a normal link, so a parent page is always reachable.
Each footer location renders a column of its own, and the heading above it is the name of the menu you assign — so a column is renamed by renaming its menu in Appearance → Menus, not in the theme. A location with no menu assigned and no widgets in its matching area renders no column at all, so the footer simply has one fewer column rather than an empty space under a heading.
Where a footer location has both a menu assigned and widgets in its matching widget area, the widgets are what render: the widget area overrides the menu for that column, heading included.
== Widget Areas ==
- Sidebar (
playforge-sidebar) — the two-column layouts on pages, posts, the blog and archives. - WooCommerce Sidebar (
playforge-woo-sidebar) — the two-column shop layouts only: the product list and the product detail page. Registered while WooCommerce is active. - Footer Column 1 (
playforge-footer-1) — overrides Foot Menu 1's column. - Footer Column 2 (
playforge-footer-2) — overrides Foot Menu 2's column. - Footer Column 3 (
playforge-footer-3) — overrides Foot Menu 3's column.
The two sidebars are deliberately separate: product filters, a category list and a mini cart belong beside the shop, not beside every blog post, and the blog's own widgets have no business on a product page. Cart, checkout and account are ordinary Pages and use the general Sidebar.
Which one a request uses is resolved by playforge_sidebar_id(), and is filterable:
add_filter( 'playforge_sidebar_id', function ( $id ) {
// One shared sidebar again, the pre-1.0.12 behaviour.
return 'playforge-sidebar';
} );Both render inside .pf-sidebar and so share its widget styling. Each also carries a modifier — .pf-sidebar--woo or .pf-sidebar--general — for styling one without touching the other.
Both are 20% of the container wide from 992px up, the main column taking the remaining 80%. One token sets it, so the pair can never disagree:
:root { --sidebar-width: 24%; }The markup keeps Bootstrap's col-lg-4 / col-lg-8 as the no-CSS fallback — a twelfth grid cannot express 20% — and the token overrides both. Below 992px the sidebar stacks under the content, as Bootstrap's own grid does.
== Page Layouts ==
full-box— centred Bootstrap container. The default.full-screen— edge-to-edge fluid container, for Elementor sections and full-width hero designs.elementor-full-canvas— edge-to-edge and bare: no page header band, no breadcrumb, no padding and no prose-width wrapper, so the design begins flush against the navbar. For a home page or landing page built entirely in Elementor. The navbar and footer still render; replace those with an Elementor Theme Builder template or Elementor's own Canvas page template.elementor-boxed— the same bareness inside the boxed container: no page header band, no breadcrumb, no prose-width wrapper and no vertical spacing, but the width stays capped by--box-widthand the container's side gutters remain. For an Elementor design that should not run edge to edge.2-cols-with-left-sidebar— sidebar first in source order, then content.2-cols-with-right-sidebar— content first in source order, then sidebar.
Filter the resolved layout for a request with:
add_filter( 'playforge_layout', function ( $layout ) {
return is_front_page() ? 'full-screen' : $layout;
} );== Design Tokens ==
Every colour, font, weight, radius, shadow and band background in style.css is
read from a CSS custom property declared in one place: the :root block that
opens the file, under the heading "1. Design tokens". No rule below that block
contains a literal colour. The same tokens drive assets/css/woocommerce.css, so
the shop and product pages follow the palette too.
The tokens come in two tiers:
- Scale tokens hold raw values —
--brand,--accent,--radius,--fw-bold,--shadow-card. Redefine one and everything built on it moves together. - Role tokens point at a scale token and name the job —
--radius-btn,--fw-nav,--card-hover-border,--price-block-bg. Redefine one and only that component moves.
So retinting the whole theme is one line (--brand), and squaring off just the
buttons is one line (--radius-btn), and neither needs a selector.
Two things to know before you edit them:
- Palette colours have channel companions. CSS cannot take a hex apart, so
the translucent overlays read
--brand-rgb,--brand-dark-rgband--accent-rgb, written as comma-separated channels (15, 118, 110). Change a hex without changing its companion and the overlays keep the old hue. - Bootstrap follows the palette. A short bridge block maps
--bs-primary,--bs-link-color,--bs-border-color,--bs-border-radiusand--bs-focus-ring-coloronto the theme tokens, so Bootstrap's own components, Elementor widgets and plugin markup pick up the brand colour without being restyled one selector at a time.
Set tokens anywhere that loads after style.css — a child theme stylesheet, Appearance → Customise → Additional CSS, or an Elementor page's custom CSS:
:root {
--brand: #0b5cab;
--brand-rgb: 11, 92, 171;
--radius-btn: 4px;
}= Page metrics =
Three tokens control the page's own dimensions, so the common adjustments need no template edits:
--box-width(default1320px) — the widest the boxed.containerbecomes. Bootstrap steps its container max-width up per breakpoint; the theme caps each step withmin(), so a smaller value narrows the page at every breakpoint and a larger one widens it from 1400px up, where the viewport has the room.--page-padding(default2rem 0) — padding on the content area, written as a normal padding shorthand.--page-margin(default0) — margin on the same element, likewise a shorthand.
--section-padding (homepage .pf-section bands) defaults to whatever
--page-padding is, so the two stay in step unless you give it its own value.
= Narrow screens =
Under 576px the theme applies a separate set of tokens rather than retuning the
shared ones: --page-padding-sm, --section-padding-sm,
--quote-band-padding-sm, --page-header-padding-sm, --hero-title-size-sm
and --spec-label-width-sm. Setting --page-padding therefore changes the wide
layout only, and the phone layout keeps its own value — set the -sm token to
change that one.
This matters because of the cascade: a child theme's :root is unconditional
and loads after style.css, so it would outrank anything the parent retuned
inside a media query, quietly restoring the desktop value on phones. Separate
-sm tokens are applied at rule level and cannot be shadowed that way.
= What the layouts ignore =
The elementor-full-canvas layout ignores --box-width, --page-padding and
--page-margin, since its whole purpose is to have no spacing of the theme's
own; elementor-boxed ignores the vertical part of --page-padding and
--page-margin but still honours --box-width and the container's side
gutters.
== Child Themes ==
A child theme of PlayForge should be a stylesheet of variables, not a copy of
the parent's rules. playforge-child-blue ships as the worked example: it is a
complete visual redesign — cool blues instead of teal, restrained weights,
tighter geometry, printed-circuit textures on the dark bands — in about 430
lines, most of which are token overrides inside a single :root.
Three notes:
-
Do not enqueue the parent stylesheet in the child's functions.php. The parent's inc/enqueue.php detects a child theme and prints both sheets itself, in the order that works:
bootstrap → bootstrap-icons → parent style.css → child style.css → woocommerce.css
The child-theme boilerplate that most generators emit registers the parent sheet with no dependencies, which places it before Bootstrap — Bootstrap's reboot then beats the parent's own base rules, and the child has to restate all of them to look like anything.
-
You need no
!important, and no repeated base rules. The child sheet loads last, so a plain:rootin it wins. -
If you find yourself copying a parent rule into the child just to change a value, that value wants a token in the parent instead. Add one there — the parent's own defaults are chosen so that introducing a token changes nothing until someone overrides it.
== Elementor ==
The theme declares elementor and header-footer-elementor support and registers the core Theme Builder locations (header, footer, single, archive) when Elementor Pro is present. The theme's own header and footer act as fallbacks, so a location with no Elementor template assigned still renders.
On a page built with Elementor, the theme suppresses its own page header band and prose-width wrapper, because the Elementor design supplies its own hero and spacing. Choose the full-screen layout for edge-to-edge Elementor designs, or elementor-full-canvas when the design should also lose the page header band, the breadcrumb and every last bit of the theme's spacing — a home page, typically. elementor-boxed is the same thing width-limited: bare, but inside the boxed container. Neither depends on the page actually being built with Elementor; they apply to whatever the content is.
Note: the theme deliberately does not style the bare section element. The Hugo original had section { padding: 5rem 0 }, which would add padding to every Elementor section; that rule is scoped to .pf-section here instead.
== WooCommerce ==
Product listing and product detail pages are styled to match the theme, and both use the theme's page header, breadcrumb and layout wrappers rather than WooCommerce's defaults.
Product listing: four products per row in every layout — the sidebar takes only 20%, so the count no longer drops beside one — and 12, 16 or 20 per page as set on the WooCommerce tab of Theme Options, cards matching the theme's .product-card, brand-coloured add-to-cart buttons, an accent sale badge, and Bootstrap-styled pagination and sort controls. The grid itself is WooCommerce's own float layout — the theme sets only the column count, via loop_shop_columns — so a plugin or child theme that expects the stock arrangement finds it intact.
Layout: the product list and the product detail page each have their own default on the WooCommerce tab, independent of the Pages and Blog & archives settings — full width, or two columns with a left sidebar for filters and category widgets. The sidebar shown is the WooCommerce Sidebar widget area, not the general one. Resolution for a single product is per-product meta → layout_product → full-box; for an archive it is layout_shop → full-box.
Product list introduction: the shop page's own content, or a product category or tag description, is rendered below the breadcrumb and above the grid, at the full content width even when a sidebar is beside the products. Long text, images, blocks and shortcodes are all supported — the content passes through do_blocks(), then wp_kses_post(), then wc_format_content(), in that order, so block markup survives kses and a shortcode's own output is never stripped. Shown on the first page of results only. WooCommerce's own copies of the same description are unhooked from woocommerce_archive_description so it is never printed twice; the source and the markup are filterable by unhooking playforge_shop_intro from woocommerce_before_main_content.
Product detail: a two-column gallery and summary, the gallery thumbnails restyled as the Hugo theme's thumbnail row, a bordered price panel, Bootstrap-style tabs, and the attributes table styled as a specification table. WhatsApp and email enquiry buttons are added below the add-to-cart area when a WhatsApp number or email address is set in Theme Options — useful for made-to-order equipment where a quote matters more than checkout. The header band on a product carries the title alone: the short description appears beside the gallery, so repeating it above would be a duplicate.
Unpriced products: a product with no price, or a price of exactly zero, shows no price line at all — neither in the listing nor on the detail page. It reads as "ask us for a quote", which is what the enquiry buttons are for, rather than as free. Variable and grouped products keep their price range, since a single free child should not blank it out. To show zero prices as $0.00 instead, unhook the theme's replacements in a child theme:
remove_action( 'woocommerce_single_product_summary', 'playforge_template_single_price', 10 );
add_action( 'woocommerce_single_product_summary', 'woocommerce_template_single_price', 10 );The theme ships no woocommerce/ template overrides. Everything is done with hooks and CSS against WooCommerce's stock markup, so there are no copied templates to fall out of date when WooCommerce bumps a template version.
== Frequently Asked Questions ==
= Does the theme stop working if I do not activate the license? =
No. An unactivated site shows one line in the footer and an admin notice. Every front-end feature keeps working.
= Where is the homepage design from the Hugo theme? =
The Hugo homepage's hero, product lines, manufacturing band, process, cases and quality sections are built with Elementor in this port rather than hard-coded into a template. The theme supplies the design tokens, the card and section styles and the layout options; Elementor supplies the composition.
= Can I use the theme without Elementor? =
Yes. Nothing in the theme requires Elementor — all of its Elementor code is behind a feature check. Without it you get the standard WordPress templates, the four layouts and the WooCommerce pages.
== Copyright ==
PlayForge WordPress theme, 2026. PlayForge is distributed under the terms of the GNU GPL v2 or later.
Bootstrap 5.3.3 Copyright 2011-2024 The Bootstrap Authors Licensed under MIT — https://github.com/twbs/bootstrap/blob/main/LICENSE
Bootstrap Icons 1.11.3 Copyright 2019-2024 The Bootstrap Authors Licensed under MIT — https://github.com/twbs/icons/blob/main/LICENSE
The theme bundles no images or stock photography. The page header renders as a brand gradient until you set a default header image under Theme Options → Header & Footer, or a featured image on the individual post or page.