Building a custom them for BaOmBaKaTaRa.com Ray 2051 May 19

Baombakatara Custom WordPress Theme – Complete Summary & Build Documentation

This document summarises the entire development of the Baombakatara custom WordPress theme. Use it to understand the architecture, replicate the setup, or continue integrating additional features (points system, surveys, etc.). The theme is built from scratch, with no third‑party page builders or premium themes – only custom code.

---

🧱 Theme Structure & Key Files

File	Purpose
style.css	Theme metadata (name, author, description). Minimal styling; most CSS is in template files.
functions.php	All theme setup, custom post types, custom fields, enqueues, duplication, block editor support, Customizer settings.
header.php	Fixed red clock bar (compact digital clock + Kagodora logo), transparent main header (custom logo, site title, navigation menu).
footer.php	Simple footer with copyright, wp_footer() hook.
front-page.php	Scroll‑snap homepage that loops through custom post type “Homepage Sections”.
page.php	Individual page template: full‑width hero image (featured image) at top, white content area below.
single.php	(Optional) For blog posts – not built yet.
page-home.php	(Not used – we use static front page with page.php.)
/js/compact-clock.js	Fetches authoritative time from kagodora.com API, updates the clock values in the red bar.
/assets/logo.png	Placeholder for the custom logo (can be overridden via Customizer).
/js/editor.js	Empty file for block editor enqueue (required to avoid missing file errors).

---

⏰ Compact Clock (Red Bar)

Features

• Fixed at top of all pages (z‑index 1000).
• Background colour: #dc2626 (red).
• Displays Ring, Turn, Ray, AhDo, AhGo, AhSa, AhTa, SaOnDo.
• Includes a Kagodora logo (image URL can be changed) as the first item.
• Updates automatically every second (local time calculation) and re‑syncs with kagodora.com every 60 seconds.

JavaScript (compact-clock.js)

• Fetches https://kagodora.com/wp-json/kagodora/v1/current-time.
• Falls back to local incremental time if API fails.
• Uses the same time formulas as the Kagodora plugin (ring = 6 + floor((ray-1801)/360), etc.).

---

📌 Header (Main Header – Below Red Bar)

Structure

• .logo-area contains:
  • .circle-logo (50×50px, yellow fallback). Displays custom logo if set via Customizer → Site Identity; otherwise uses assets/logo.png.
  • .site-title – dynamic site name (bloginfo('name')).
• Navigation menu (wp_nav_menu) – centred, with main-menu class.

Customizer Controls (in functions.php)

Section	Setting	Default	What it controls
Header Background	Background colour	transparent	.main-header, .logo-area background colour.
Header Background	Background image	(empty)	Background image (overrides colour).
Header Text	Site Title Colour	#ffffff	Colour of the .site-title text.
Menu Text	Menu Text Colour	#ffffff	Colour of .main-menu li a links.
Page Titles	Page Title Colour	#1e3a8a	Colour of <h1> inside .page-content-area (individual pages).

All customizer CSS is output inline in <head> with !important to override any inline styles.

---

🏠 Homepage (Scroll‑Snap Sections)

Custom Post Type: section

• Admin menu: Homepage Sections.
• Supports: title, editor, thumbnail (featured image).
• Orderable by drag & drop (via menu_order).
• Custom meta box: Button Link (URL) – optional.

Template: front-page.php

• Wrapper .sections-container with vertical scroll‑snap (scroll-snap-type: y mandatory).
• Each .section:
  • Background image: featured image of the section (fallback to default farm image).
  • Overlay (::before) with semi‑transparent black.
  • Centred content: title, content (from editor), optional button link.
• The default background image (from header.php) is hidden on the homepage (<style>.full-bg { display: none !important; }).

---

📄 Individual Pages (e.g., Farm, Water, Retreat)

Template: page.php

• Hero area: Uses the page’s featured image (fallback to default farm image).
  • Full width (width: 100vw with negative margin trick to break out of any parent constraint).
  • Height: 60vh on desktop, 40vh on mobile.
  • Background‑size: cover (ensures image fills area without distortion).
• Content area: White background, padding, centred text. Displays:
  • Page title (<h1>) – colour adjustable via Customizer.
  • Page content (the_content() – block editor ready).

Notes

• The default .full-bg (global background) is automatically hidden on pages that have a featured image (via inline CSS).
• If no featured image is set, the default hero image appears (same as default background).

---

🧩 functions.php – Key Components

Theme Setup

• Post thumbnails support.
• Custom logo support (WordPress native).
• Navigation menu registration (primary).

Custom Post Type: Homepage Sections

• section post type.
• Supports thumbnails, block editor.
• Orderable by menu_order.

Custom Field: Button Link

• Meta box for _section_button_url.
• Saves as URL.

Duplicate Post Functionality

• Adds “Duplicate” link in admin list for pages and sections.
• Copies post content and custom field.

Block Editor Support

• add_theme_support for wide alignment, responsive embeds, etc.
• Enqueues empty editor.js to satisfy the editor.

Customizer Sections

• Header Background, Header Text, Menu Text, Page Titles (all documented above).
• Outputs CSS inline in <head>.

Enqueues

• compact-clock.js (front‑end).
• style.css (main theme styles).

---

🛠️ Major Issues Resolved

Issue	Solution
JSON error when saving posts	Plugin conflict with custom AJAX actions. Fixed by isolating plugin code (not a theme issue).
Missing “Set featured image” box	Added add_theme_support('post-thumbnails') and ensured thumbnail support in CPT registration. User also needed to enable via Screen Options.
Scroll‑snap jumping, menu hidden	Used scroll-margin-top on sections (120px) and removed padding-top from container. Adjusted to match fixed header height.
Hero image not full width, gaps on sides	Used left: 50%; margin-left: -50vw; width: 100vw; trick to force full viewport width.
Default background image showing over page hero	Conditionally hid .full-bg when page has a featured image (inline CSS).
Header had white background	Removed !important from inline styles and used Customizer CSS with !important to override.
Customizer site title / menu text / page title not updating	Added specific CSS selectors and output in <head> with high priority (99).
Logo and site title not editable	Added native custom logo support and used bloginfo('name').
Compact clock not syncing with kagodora.com	Created REST API endpoint on kagodora.com and modified JS to fetch and re‑sync every minute.

---

📦 Dependencies & External APIs

• No external plugins required – everything is built into the theme.
• Kagodora.com API endpoint (must remain active for compact clock to show real time):
  • URL: https://kagodora.com/wp-json/kagodora/v1/current-time
  • Returns JSON: { ahta, ahsa, ahgo, ahdo, ray, ring, turn, timestamp }