🔵 other: Rename project and publish
This commit is contained in:
Keith Solomon
+73
-61
@@ -1,46 +1,56 @@
|
||||
# VDI-Starter-v5 Theme Reference
|
||||
# SoloFrame Evo Theme Reference
|
||||
|
||||
> Quick-lookup reference for the VDI-Starter-v5 WordPress theme. Covers hooks, filters, design tokens, CSS architecture, JS modules, helper functions, class APIs, CLI commands, deployment, and testing.
|
||||
> Quick-lookup reference for the SoloFrame Evo WordPress theme. Covers hooks, filters, design tokens, CSS architecture, JS modules, helper functions, class APIs, CLI commands, deployment, and testing.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Hooks and Filters](#hooks-and-filters)
|
||||
- [hooks.php (BasicWP Namespace)](#hooksphp-basicwp-namespace)
|
||||
- [extras.php](#extrasphp)
|
||||
- [helpers.php](#helpersphp)
|
||||
- [class-enqueue.php](#class-enqueuephp)
|
||||
- [class-breadcrumbs.php](#class-breadcrumbsphp)
|
||||
- [class-resources.php](#class-resourcesphp)
|
||||
- [theme.json Design Tokens](#themejson-design-tokens)
|
||||
- [Colors](#colors)
|
||||
- [Font Sizes](#font-sizes)
|
||||
- [Font Family](#font-family)
|
||||
- [Layout](#layout)
|
||||
- [Spacing Units](#spacing-units)
|
||||
- [CSS Architecture](#css-architecture)
|
||||
- [Import Order](#import-order)
|
||||
- [Adding a New Stylesheet](#adding-a-new-stylesheet)
|
||||
- [JS Module Dependency Graph](#js-module-dependency-graph)
|
||||
- [Script Module IDs](#script-module-ids)
|
||||
- [Navigation Class API](#navigation-class-api)
|
||||
- [Helper Functions](#helper-functions)
|
||||
- [Class Reference](#class-reference)
|
||||
- [CLI Commands](#cli-commands)
|
||||
- [Deployment (GitHub Actions)](#deployment-github-actions)
|
||||
- [Testing](#testing)
|
||||
- [SoloFrame Evo Theme Reference](#soloframe-evo-theme-reference)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Hooks and Filters](#hooks-and-filters)
|
||||
- [hooks.php (SoloFrameEvo Namespace)](#hooksphp-soloframeevo-namespace)
|
||||
- [extras.php](#extrasphp)
|
||||
- [helpers.php](#helpersphp)
|
||||
- [class-enqueue.php](#class-enqueuephp)
|
||||
- [class-breadcrumbs.php](#class-breadcrumbsphp)
|
||||
- [class-resources.php](#class-resourcesphp)
|
||||
- [theme.json Design Tokens](#themejson-design-tokens)
|
||||
- [Colors](#colors)
|
||||
- [Font Sizes](#font-sizes)
|
||||
- [Font Family](#font-family)
|
||||
- [Layout](#layout)
|
||||
- [Spacing Units](#spacing-units)
|
||||
- [CSS Architecture](#css-architecture)
|
||||
- [Import Order](#import-order)
|
||||
- [Adding a New Stylesheet](#adding-a-new-stylesheet)
|
||||
- [JS Module Dependency Graph](#js-module-dependency-graph)
|
||||
- [Script Module IDs](#script-module-ids)
|
||||
- [Navigation Class API](#navigation-class-api)
|
||||
- [Constructor](#constructor)
|
||||
- [Methods](#methods)
|
||||
- [Helper Functions](#helper-functions)
|
||||
- [Class Reference](#class-reference)
|
||||
- [Breadcrumbs Method Details](#breadcrumbs-method-details)
|
||||
- [CLI Commands](#cli-commands)
|
||||
- [Deployment (GitHub Actions)](#deployment-github-actions)
|
||||
- [Deployment Steps](#deployment-steps)
|
||||
- [rsync Flags](#rsync-flags)
|
||||
- [Testing](#testing)
|
||||
- [Accessibility Tests](#accessibility-tests)
|
||||
- [PHP Linting](#php-linting)
|
||||
- [Playwright Configuration](#playwright-configuration)
|
||||
|
||||
---
|
||||
|
||||
## Hooks and Filters
|
||||
|
||||
### hooks.php (BasicWP Namespace)
|
||||
### hooks.php (SoloFrameEvo Namespace)
|
||||
|
||||
All hooks in this file live under the `BasicWP` namespace.
|
||||
All hooks in this file live under the `SoloFrameEvo` namespace.
|
||||
|
||||
| Hook | Type | Priority | Args | Description |
|
||||
|------|------|----------|------|-------------|
|
||||
| ------ | ------ | ---------- | ------ | ------------- |
|
||||
| `wp_head` | Action | 0 | — | Adds Google Fonts `<link rel="preconnect">` tags |
|
||||
| `register_nav_menus()` | Direct call | — | — | Registers three menus: `main_navigation`, `aux_navigation`, `footer_navigation` |
|
||||
| `widgets_init` | Action | — | — | Registers four sidebars: `sidebar-primary`, `sidebar-page`, `footer-1`, `footer-2`, `footer-3` |
|
||||
@@ -57,6 +67,7 @@ All hooks in this file live under the `BasicWP` namespace.
|
||||
**The `init` (priority 1) hook performs aggressive cleanup:**
|
||||
|
||||
Removes:
|
||||
|
||||
- Emoji detection and styles (`remove_action` on `wp_head`)
|
||||
- Block library styles (`wp-block-library`)
|
||||
- Global styles (`global-styles`)
|
||||
@@ -67,6 +78,7 @@ Removes:
|
||||
- WLW manifest link (`wlwmanifest_link`)
|
||||
|
||||
Adds theme supports:
|
||||
|
||||
- `post-thumbnails`
|
||||
- `title-tag`
|
||||
- `html5` (search-form, comment-form, comment-list, gallery, caption, style, script)
|
||||
@@ -80,7 +92,7 @@ Adds theme supports:
|
||||
### extras.php
|
||||
|
||||
| Hook / Filter | Type | Description |
|
||||
|---------------|------|-------------|
|
||||
| --------------- | ------ | ------------- |
|
||||
| `hasSidebar` | Filter | Controls sidebar display based on an ACF true/false field on the current page |
|
||||
| `body_class` | Filter | Appends `has-sidebar` class to `<body>` when a sidebar is present |
|
||||
| `the_content` | Filter | `divWrapper()` wraps `<iframe>` and embed elements in `<div class="embed">` |
|
||||
@@ -94,10 +106,10 @@ Adds theme supports:
|
||||
### helpers.php
|
||||
|
||||
| Hook / Filter | Type | Priority | Args | Description |
|
||||
|---------------|------|----------|------|-------------|
|
||||
| --------------- | ------ | ---------- | ------ | ------------- |
|
||||
| `custom_menu_order` | Filter | 10 | 1 | Enables custom admin menu ordering |
|
||||
| `menu_order` | Filter | 10 | 1 | Defines the custom admin menu order |
|
||||
| `block_categories_all` | Filter | 10 | — | Adds the `vdi-blocks` category to the block editor |
|
||||
| `block_categories_all` | Filter | 10 | — | Adds the `sf-blocks` category to the block editor |
|
||||
| `init` | Action | — | — | Registers the ACF "Global Fields" options page |
|
||||
|
||||
---
|
||||
@@ -105,7 +117,7 @@ Adds theme supports:
|
||||
### class-enqueue.php
|
||||
|
||||
| Hook | Type | Method | Description |
|
||||
|------|------|--------|-------------|
|
||||
| ------ | ------ | -------- | ------------- |
|
||||
| `wp_enqueue_scripts` | Action | `enqFEAssets()` | Loads frontend CSS and JS |
|
||||
| `admin_enqueue_scripts` | Action | `enqBEAssets()` | Loads admin CSS and JS |
|
||||
| `enqueue_block_editor_assets` | Action | `enqEditorAssets()` | Loads block editor CSS |
|
||||
@@ -117,7 +129,7 @@ Adds theme supports:
|
||||
The `Breadcrumbs` class generates Schema.org-compatible breadcrumb markup. Context-specific methods:
|
||||
|
||||
| Method | Context |
|
||||
|--------|---------|
|
||||
| -------- | --------- |
|
||||
| `getHomeBreadcrumb()` | Site front page |
|
||||
| `getBlogPostsIndexBreadcrumb()` | Blog posts index |
|
||||
| `getSinglePostBreadcrumbs()` | Single post |
|
||||
@@ -134,7 +146,7 @@ The `Breadcrumbs` class generates Schema.org-compatible breadcrumb markup. Conte
|
||||
### class-resources.php
|
||||
|
||||
| Hook | Type | Description |
|
||||
|------|------|-------------|
|
||||
| ------ | ------ | ------------- |
|
||||
| `init` | Action | Registers the `resources` custom post type |
|
||||
| `post_type_link` | Filter | Customizes resource permalinks to `/resources/{term-slug}/{post-name}` |
|
||||
|
||||
@@ -149,7 +161,7 @@ The `resources` CPT uses a URL rewrite pattern that incorporates the first taxon
|
||||
All theme colors map to CSS custom properties. Use the CSS variable in your stylesheets or reference the slug in the block editor.
|
||||
|
||||
| Slug | CSS Variable | Name | Value |
|
||||
|------|-------------|------|-------|
|
||||
| ------ | ------------- | ------ | ------- |
|
||||
| `black` | — | Black | `#000` |
|
||||
| `white` | — | White | `#fff` |
|
||||
| `theme-bg` | `var(--color-background)` | Theme Background | Dynamic |
|
||||
@@ -187,7 +199,7 @@ The dynamic colors (`theme-*`) resolve to CSS custom properties that can be over
|
||||
### Font Sizes
|
||||
|
||||
| Slug | CSS Variable | Name |
|
||||
|------|-------------|------|
|
||||
| ------ | ------------- | ------ |
|
||||
| `base` | `var(--text-base)` | Base |
|
||||
| `text-14px` | `var(--text-14px)` | Text 14px |
|
||||
| `text-16px` | `var(--text-16px)` | Text 16px |
|
||||
@@ -223,7 +235,7 @@ The dynamic colors (`theme-*`) resolve to CSS custom properties that can be over
|
||||
### Font Family
|
||||
|
||||
| Slug | CSS Variable | Name |
|
||||
|------|-------------|------|
|
||||
| ------ | ------------- | ------ |
|
||||
| `theme-sans` | `var(--font-sans)` | Theme Sans |
|
||||
|
||||
```css
|
||||
@@ -237,7 +249,7 @@ body {
|
||||
### Layout
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| --------- | ------- |
|
||||
| `contentSize` | `100%` |
|
||||
| `wideSize` | `1536px` |
|
||||
|
||||
@@ -259,7 +271,7 @@ The entry point is `styles/theme.css`. All imports use the CSS `@import` syntax
|
||||
|
||||
### Import Order
|
||||
|
||||
```
|
||||
```plain
|
||||
styles/theme.css
|
||||
|
|
||||
+-- @import "tailwindcss" # Tailwind CSS v4 base
|
||||
@@ -325,12 +337,12 @@ Example -- adding a new `cards.css` component:
|
||||
|
||||
## JS Module Dependency Graph
|
||||
|
||||
```
|
||||
```plain
|
||||
theme.js (entry point)
|
||||
├── Navigation.js # Mobile menu, sliding viewport, keyboard nav
|
||||
├── Navigation.js # Mobile menu, sliding viewport, keyboard nav
|
||||
├── backToTop.js # BackToTopButton custom element
|
||||
├── button.js # ButtonComponent custom element, registerButtonComponent
|
||||
├── GetHeaderHeight.js # Sets --header-height CSS variable
|
||||
├── GetHeaderHeight.js # Sets --header-height CSS variable
|
||||
└── TagExternalLinks.js # Adds target="_blank" rel="noopener" to external links
|
||||
|
||||
admin.js
|
||||
@@ -342,16 +354,16 @@ admin.js
|
||||
WordPress registers these script modules via `wp_register_script_module()`:
|
||||
|
||||
| Module ID | Source | Dependencies |
|
||||
|-----------|--------|--------------|
|
||||
| `basicwp-theme` | `theme.js` | None |
|
||||
| `basicwp-button` | `button.js` | `basicwp-theme` |
|
||||
| `basicwp-admin` | `admin.js` | `basicwp-button` |
|
||||
| ----------- | -------- | -------------- |
|
||||
| `sf-evo-theme` | `theme.js` | None |
|
||||
| `sf-evo-button` | `button.js` | `sf-evo-theme` |
|
||||
| `sf-evo-admin` | `admin.js` | `sf-evo-button` |
|
||||
|
||||
**Loading in a template:**
|
||||
|
||||
```php
|
||||
wp_enqueue_script_module('basicwp-theme');
|
||||
wp_enqueue_script_module('basicwp-button');
|
||||
wp_enqueue_script_module('sf-evo-theme');
|
||||
wp_enqueue_script_module('sf-evo-button');
|
||||
```
|
||||
|
||||
---
|
||||
@@ -371,7 +383,7 @@ const nav = new Navigation(toggleId, menuSelector);
|
||||
### Methods
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| -------- | ------------- |
|
||||
| `desktopMenuDropdowns()` | Enables dropdown menus for desktop navigation |
|
||||
| `mobileMenuToggle()` | Toggles the mobile hamburger menu open/closed |
|
||||
| `initializeSlidingViewport()` | Sets up the sliding mobile menu structure |
|
||||
@@ -400,11 +412,11 @@ nav.initializeSlidingViewport();
|
||||
## Helper Functions
|
||||
|
||||
| Function | File | Signature | Description |
|
||||
|----------|------|-----------|-------------|
|
||||
| ---------- | ------ | ----------- | ------------- |
|
||||
| `getFieldValue` | helpers.php | `getFieldValue($field_path)` | Retrieves nested ACF values using dot notation. E.g., `getFieldValue('contact_info.phone')` resolves `get_field('contact_info', 'option')['phone']`. Uses `'option'` for Global Fields. |
|
||||
| `blockWrapperAttributes` | helpers.php | `blockWrapperAttributes($classes, $is_preview)` | Returns block wrapper attributes. In preview mode returns `class="..."`; on frontend returns `get_block_wrapper_attributes()`. |
|
||||
| `customMenuOrder` | helpers.php | `customMenuOrder($menu_ord)` | Customizes WordPress admin menu order. |
|
||||
| `blockCategories` | helpers.php | `blockCategories($categories)` | Adds the `vdi-blocks` category to the block editor. |
|
||||
| `blockCategories` | helpers.php | `blockCategories($categories)` | Adds the `sf-blocks` category to the block editor. |
|
||||
| `consoleLog` | helpers.php | `consoleLog($data)` | Outputs data to the browser console via `<script>console.log()</script>`. |
|
||||
| `customExcerpt` | helpers.php | `customExcerpt($text, $number_of_words, $more)` | Generates custom excerpts that end at sentence boundaries instead of mid-sentence. |
|
||||
| `escEmbeds` | helpers.php | `escEmbeds()` | Returns an allowed HTML array for iframe/embed content (used with `wp_kses`). |
|
||||
@@ -435,7 +447,7 @@ $excerpt = customExcerpt(get_the_content(), 30, '...');
|
||||
## Class Reference
|
||||
|
||||
| Class | File | Key Methods | Description |
|
||||
|-------|------|-------------|-------------|
|
||||
| ------- | ------ | ------------- | ------------- |
|
||||
| `Enqueue` | `class-enqueue.php` | `enqFEAssets()`, `enqBEAssets()`, `enqEditorAssets()` | Manages all asset loading: frontend, admin, and editor |
|
||||
| `ACF` | `class-acf.php` | `saveJson($path)`, `loadJson($paths)` | Sets ACF JSON save/load paths for field group synchronization |
|
||||
| `Breadcrumbs` | `class-breadcrumbs.php` | `generate()`, `render()`, plus per-context methods (see below) | Generates Schema.org-compatible breadcrumb markup |
|
||||
@@ -446,7 +458,7 @@ $excerpt = customExcerpt(get_the_content(), 30, '...');
|
||||
### Breadcrumbs Method Details
|
||||
|
||||
| Method | Returns | Description |
|
||||
|--------|---------|-------------|
|
||||
| -------- | --------- | ------------- |
|
||||
| `generate()` | `array` | Builds breadcrumb data array for the current context |
|
||||
| `render()` | `string` | Outputs breadcrumb HTML with Schema.org markup |
|
||||
| `getHomeBreadcrumb()` | `array` | Breadcrumb for the front page |
|
||||
@@ -472,7 +484,7 @@ echo $breadcrumbs->render();
|
||||
## CLI Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| --------- | ------------- |
|
||||
| `npm run build` | Compiles Tailwind CSS v4 from `styles/theme.css` to `static/dist/theme.css` with `--optimize` |
|
||||
| `npm run start` | Starts BrowserSync dev server with live reloading (alias for `npm run watch`) |
|
||||
| `npm run watch` | Runs `.watch.js` -- BrowserSync with CSS injection on changes |
|
||||
@@ -488,11 +500,11 @@ echo $breadcrumbs->render();
|
||||
The deployment workflow is defined in `.github/workflows/wpengine.yml`.
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| --------- | ------- |
|
||||
| Trigger | `workflow_dispatch` (manual). Push to `main` trigger is commented out. |
|
||||
| Skip condition | Commits containing `#skipGA` in the message are skipped |
|
||||
| Target path | `wp-content/themes/vdi-v5` |
|
||||
| WP Engine environment | `vdiv5` |
|
||||
| Target path | `wp-content/themes/ soloframe-evo` |
|
||||
| WP Engine environment | `soloframe-evo` |
|
||||
| SSH key secret | `WPE_SSHG_KEY_PRIVATE` |
|
||||
|
||||
### Deployment Steps
|
||||
@@ -506,12 +518,12 @@ The deployment workflow is defined in `.github/workflows/wpengine.yml`.
|
||||
|
||||
### rsync Flags
|
||||
|
||||
```
|
||||
```plain
|
||||
-azvr --inplace --delete --exclude=".*"
|
||||
```
|
||||
|
||||
| Flag | Meaning |
|
||||
|------|---------|
|
||||
| ------ | --------- |
|
||||
| `-a` | Archive mode (preserve permissions, timestamps, etc.) |
|
||||
| `-z` | Compress during transfer |
|
||||
| `-v` | Verbose output |
|
||||
@@ -554,4 +566,4 @@ Auto-fixes PHPCS violations where possible.
|
||||
|
||||
### Playwright Configuration
|
||||
|
||||
The Playwright config (`playwright.config.js`) is currently set to run on **Chromium only**. Firefox and WebKit browsers are commented out but available for enabling.
|
||||
The Playwright config (`playwright.config.js`) is currently set to run on **Chromium only**. Firefox and WebKit browsers are commented out but available for enabling.
|
||||
|
||||
Reference in New Issue
Block a user