489 lines
18 KiB
Markdown
489 lines
18 KiB
Markdown
# VDI WordPress Theme Starter v5
|
||
|
||
VDI WordPress Theme Starter v5 is a minimal WordPress theme designed as a starting point for custom theme development. It focuses on modern development approaches with a lean architecture that avoids the overhead of theme frameworks.
|
||
|
||
Repo: [https://github.com/Vincent-Design-Inc/VDI-Starter-v5](https://github.com/Vincent-Design-Inc/VDI-Starter-v5)
|
||
AC Bug/Issue Tracking: [https://next-app.activecollab.com/119590/projects/4553?modal=Task-98192-4553](https://next-app.activecollab.com/119590/projects/4553?modal=Task-98192-4553)
|
||
|
||
## Key Features
|
||
|
||
- Tailwind CSS
|
||
- Namespaced PHP for isolation
|
||
- Built-in support for ACF blocks
|
||
- Fast development workflow with watch and compile functions
|
||
|
||
## Project Structure
|
||
|
||
```plaintext
|
||
VDI-Starter-v5/
|
||
├── acf/ # ACF field group JSON definitions
|
||
├── bin/ # Build scripts
|
||
├── content/ # Sample page and post content for testing
|
||
├── lib/ # PHP library files
|
||
│ ├── class-breadcrumbs.php # Breadcrumb generation
|
||
│ ├── class-acf.php # ACF integration
|
||
│ ├── class-enqueue.php # Assets enqueuing
|
||
│ ├── class-menuitems.php # Navigation menu builder
|
||
│ ├── class-resources.php # Custom Resources post type
|
||
│ ├── extras.php # Miscellaneous theme functions
|
||
│ ├── helpers.php # Helper functions
|
||
│ ├── hooks.php # WordPress hooks and filters
|
||
│ ├── search-features.php # Enhanced search functionality
|
||
│ └── show-template.php # Script to show which template is used for the current page
|
||
├── static/ # Static assets
|
||
│ ├── dist/ # Compiled assets
|
||
│ ├── img/ # Static theme images
|
||
│ └── js/ # JavaScript files
|
||
│ ├── components/ # JS components
|
||
│ │ └── button.js # Button custom component
|
||
│ ├── modules/ # JS theme modules
|
||
│ │ ├── GetHeaderHeight.js # Calculate header height and set it as a CSS variable
|
||
│ │ ├── Navigation.js # Script controlling navigation behavior
|
||
│ │ └── TagExternalLinks.js # Tags external links with appropriate attributes
|
||
│ ├── admin.js # Admin-specific JS
|
||
│ └── theme.js # Main theme JS
|
||
├── styles/ # CSS styles
|
||
│ ├── backend/ # Admin styles
|
||
│ ├── base/ # Base styles
|
||
│ ├── blocks/ # Block styles
|
||
│ ├── components/ # Component styles
|
||
│ ├── fonts/ # Font styles
|
||
│ └── theme.css # Main CSS entry point
|
||
├── tests/ # Automated Playwright tests
|
||
│ └── site-a11y.spec.js # Site Accessibility tests
|
||
├── views/ # Template views
|
||
│ ├── blocks/ # Custom ACF blocks
|
||
│ ├── icons/ # SVG icons
|
||
│ ├── forms/ # Form templates
|
||
│ └── partials/ # Reusable template parts
|
||
├── 404.php # 404 error template
|
||
├── footer.php # Footer template
|
||
├── front-page.php # Front page template
|
||
├── functions.php # Main functions file
|
||
├── header.php # Header template
|
||
├── index.php # Main template
|
||
├── page.php # Page template
|
||
├── search.php # Search results template
|
||
├── sidebar.php # Main sidebar template
|
||
├── sidebar-page.php # Page sidebar template
|
||
├── single.php # Single post template
|
||
├── style.css # Theme metadata
|
||
└── whitelist.php # Tailwind class whitelist
|
||
```
|
||
|
||
## Core Files and Templates
|
||
|
||
### Theme Core Files
|
||
|
||
- **style.css**: Contains theme metadata and registration information
|
||
- **functions.php**: Initializes the theme and loads necessary dependencies
|
||
- **class-acf.php**: Handles Advanced Custom Fields (ACF) functionality
|
||
- **class-breadcrumbs.php**: Generates breadcrumb navigation for the site
|
||
- **class-enqueue.php**: Manages script and style enqueuing for frontend and backend
|
||
- **class-menuitems.php**: Builder for the navigation menus
|
||
- **class-resources.php**: Custom post type management for "Resources", included as an example of CPT usage
|
||
- **extras.php**: Miscellaneous theme functions, including sidebar and page header checks
|
||
- **helpers.php**: Utility functions for common tasks
|
||
- **hooks.php**: Contains WordPress hooks and filters for theme functionality
|
||
- **search-features.php**: Enhances search functionality with custom queries and filters
|
||
- **show-template.php**: Outputs the current template file being used for debugging
|
||
- **whitelist.php**: Contains Tailwind CSS class whitelist for styles used in WordPress editor
|
||
|
||
### Template Files
|
||
|
||
- **header.php**: Defines the site header with primary navigation
|
||
- **footer.php**: Defines the site footer with widget areas and copyright
|
||
- **front-page.php**: Template for the front page of the site
|
||
- **page.php**: Displays individual static pages with optional sidebar
|
||
- **index.php**: Main template file that displays the blog posts list
|
||
- **single.php**: Displays individual posts with author and category information
|
||
- **search.php**: Displays search results with pagination
|
||
- **404.php**: Custom "Page Not Found" template with search form
|
||
- **sidebar.php**: Primary sidebar template
|
||
- **sidebar-page.php**: Page-specific sidebar template
|
||
- **views/forms/search.php** - Search form template for use in various locations
|
||
|
||
### Included Blocks
|
||
|
||
- **Boilerplate**: Example block for custom development
|
||
- **Accordion**: Collapsible content sections
|
||
- **Buttons**: Group of buttons
|
||
- **Button**: Configurable button element
|
||
- **Grid**: Flexible grid layout system
|
||
- **Grid Cell**: Individual grid item
|
||
- **Homepage Hero**: Hero section typically used on homepage
|
||
- **Media Text**: Image or video with accompanying text
|
||
- **Media Text with Inner Blocks**: Media-text with nested block support
|
||
- **Page Children**: Displays child pages of current page
|
||
- **Section**: Container block with background and width (contained and full-screen width) options
|
||
|
||
## Library Functions and Classes
|
||
|
||
### helpers.php
|
||
|
||
```php
|
||
getFieldValue($field_path)
|
||
```
|
||
|
||
- Retrieves a nested value from an ACF field using dot notation
|
||
- **Parameters**: `$field_path` - The dot-notated path to the value (e.g., `contact_info.phone`)
|
||
- **Returns**: The value at the specified path
|
||
|
||
```php
|
||
customMenuOrder($menu_ord)
|
||
```
|
||
|
||
- Customizes the order of admin menu items in WordPress dashboard
|
||
- Add other admin menu URLs to the array to change their order
|
||
- **Parameters**: `$menu_ord` - The existing menu order array
|
||
- **Returns**: Array specifying the custom menu order, or true for default order
|
||
|
||
```php
|
||
blockCategories($categories)
|
||
```
|
||
|
||
- Adds custom block category for theme blocks
|
||
- **Parameters**: `$categories` - The existing block categories
|
||
- **Returns**: Modified array of categories
|
||
|
||
```php
|
||
consoleLog($data)
|
||
```
|
||
|
||
- Utility function to print a variable to the console for debugging
|
||
- **Parameters**: `$data` - The data to print to the console
|
||
|
||
### search-features.php
|
||
|
||
```php
|
||
pageSearch($query)
|
||
```
|
||
|
||
- Modifies the WordPress query for page search functionality
|
||
- **Parameters**: `$query` - The WordPress query object
|
||
- **Returns**: void
|
||
|
||
```php
|
||
postSort($key)
|
||
```
|
||
|
||
- Returns a sorting function for WP_Post objects in reverse order
|
||
- **Parameters**: `$key` - WP_Post object property used for sorting
|
||
- **Returns**: Sorting function
|
||
|
||
```php
|
||
dedupe($posts, $key)
|
||
```
|
||
|
||
- Removes duplicate posts based on a specified key
|
||
- **Parameters**:
|
||
- `$posts` - Array of posts
|
||
- `$key` - Key to check for duplicates
|
||
- **Returns**: Filtered array of posts
|
||
|
||
```php
|
||
searchResultFilter($posts, $query)
|
||
```
|
||
|
||
- Filters and processes search results
|
||
- **Parameters**:
|
||
- `$posts` - Array of posts
|
||
- `$query` - The search query
|
||
- **Returns**: Filtered array of posts
|
||
|
||
### extras.php
|
||
|
||
```php
|
||
getChildrenPages()
|
||
```
|
||
|
||
- Gets child pages of the current page
|
||
- **Returns**: Array of child pages or empty array
|
||
|
||
```php
|
||
hasSidebar()
|
||
```
|
||
|
||
- Checks if sidebar should be rendered
|
||
- **Returns**: Boolean indicating sidebar presence
|
||
|
||
```php
|
||
hasPageHeader()
|
||
```
|
||
|
||
- Checks if the page should render a page header
|
||
- **Returns**: Boolean indicating page header presence
|
||
|
||
```php
|
||
createOwnerRole()
|
||
```
|
||
|
||
- Creates a new WordPress role named "Owner" with admin capabilities minus plugin/theme management
|
||
- **Returns**: void
|
||
|
||
```php
|
||
getTheTitle()
|
||
```
|
||
|
||
- Gets the title based on the current context (archive, search, etc.)
|
||
- **Returns**: Appropriate title string
|
||
|
||
```php
|
||
divWrapper($content)
|
||
```
|
||
|
||
- Wraps iframes and embeds in a div with the class "embed"
|
||
- **Parameters**: `$content` - The content to process
|
||
- **Returns**: Modified content
|
||
|
||
### Class: Resources (class-resources.php)
|
||
|
||
Custom post type and taxonomy management for "Resources"
|
||
|
||
### Class: Enqueue (class-enqueue.php)
|
||
|
||
Manages script and style enqueueing
|
||
|
||
```php
|
||
enqFEAssets()
|
||
```
|
||
|
||
- Enqueues frontend CSS and JS files
|
||
- **Returns**: void
|
||
|
||
```php
|
||
enqBEAssets()
|
||
```
|
||
|
||
- Enqueues backend (admin/editor) CSS and JS files
|
||
- **Returns**: void
|
||
|
||
### Class: ACF (class-acf.php)
|
||
|
||
Handles ACF (Advanced Custom Fields) functionality
|
||
|
||
```php
|
||
saveJson($path)
|
||
```
|
||
|
||
- Sets the path for saving ACF field groups as JSON
|
||
- **Parameters**: `$path` - The default path
|
||
- **Returns**: Modified path
|
||
|
||
```php
|
||
loadJson($paths)
|
||
```
|
||
|
||
- Sets the path for loading ACF field groups from JSON
|
||
- **Parameters**: `$paths` - The default paths
|
||
- **Returns**: Modified paths array
|
||
|
||
### Class: Breadcrumbs (class-breadcrumbs.php)
|
||
|
||
Generates and displays breadcrumb navigation
|
||
|
||
```php
|
||
generate()
|
||
```
|
||
|
||
- Generates breadcrumb data based on the current page
|
||
- **Returns**: Array of breadcrumb items
|
||
|
||
```php
|
||
render()
|
||
```
|
||
|
||
- Renders breadcrumb HTML with schema.org markup
|
||
- **Returns**: void (echoes HTML)
|
||
|
||
The class also includes other helper methods for different page types:
|
||
|
||
- `getHomeBreadcrumb()`
|
||
- `getBlogPostsIndexBreadcrumb()`
|
||
- `getSinglePostBreadcrumbs()`
|
||
- `getCustomPostTypeBreadcrumbs()`
|
||
- `getStaticPageBreadcrumbs($post)`
|
||
- `getTaxonomyArchiveBreadcrumb()`
|
||
- `getPostTypeArchiveBreadcrumb()`
|
||
- `getDateArchiveBreadcrumbs()`
|
||
- `getMonthArchiveBreadcrumb()`
|
||
- `getYearArchiveBreadcrumb()`
|
||
- `getAuthorArchiveBreadcrumb()`
|
||
- `getSearchBreadcrumb()`
|
||
- `get404Breadcrumb()`
|
||
|
||
## ACF Blocks System
|
||
|
||
The theme implements a custom block system using Advanced Custom Fields. Blocks are registered automatically in functions.php via the `regACFBlocks()` function.
|
||
|
||
See `views/blocks/boilerplate/` for a starting point for custom blocks.
|
||
|
||
### Block Structure
|
||
|
||
Each block consists of:
|
||
|
||
- PHP template file (block rendering)
|
||
- CSS file (block-specific styles)
|
||
- block.json file (block configuration)
|
||
|
||
See the [ACF Blocks Documentation](https://www.advancedcustomfields.com/resources/#acf-blocks) for more details on creating custom blocks.
|
||
|
||
## JavaScript Components
|
||
|
||
The theme utilizes custom web components for enhanced functionality.
|
||
|
||
### ButtonComponent
|
||
|
||
A custom HTML element for creating buttons with various configurations:
|
||
|
||
```javascript
|
||
class ButtonComponent extends HTMLElement {
|
||
// Attributes:
|
||
// - btnClasses: Additional CSS classes
|
||
// - element: The element to use (`a` or `button`)
|
||
// - type: Button type (for non-anchor elements)
|
||
// - url: The URL for links
|
||
// - target: Target attribute for links
|
||
// - title: Button text
|
||
// - color: Button color
|
||
// - variant: Button style variant
|
||
// - size: Button size
|
||
// - width: Button width
|
||
}
|
||
```
|
||
|
||
Usage:
|
||
|
||
```html
|
||
<x-button
|
||
btnClasses="button text-center"
|
||
element="a"
|
||
url="https://example.com"
|
||
target="_blank"
|
||
title="Click Me"
|
||
color="primary"
|
||
variant="default"
|
||
size="medium"
|
||
width="auto"
|
||
></x-button>
|
||
```
|
||
|
||
## Asset Management
|
||
|
||
### CSS
|
||
|
||
The theme uses Tailwind CSS for styling with custom utilities:
|
||
|
||
- Base styles in `views/styles/base`
|
||
- Component styles in `views/styles/components`
|
||
- Block-specific styles in individual block folders and `views/styles/blocks`
|
||
- Admin/editor styles in `views/styles/backend`
|
||
|
||
### JavaScript
|
||
|
||
- **theme.js**: Main frontend JavaScript
|
||
- **admin.js**: Admin-specific JavaScript
|
||
- **components**: JavaScript components
|
||
- **modules**: JavaScript modules for specific functionality (e.g., navigation, focus styling)
|
||
|
||
### Build System
|
||
|
||
The theme includes a simple build system in the bin directory:
|
||
|
||
- **.build.js**: Production build script that compiles Tailwind CSS
|
||
- **.watch.js**: Development watch script with BrowserSync for live reloading
|
||
- **.utils.js**: Shared utility functions for the build process
|
||
|
||
## Development Workflow
|
||
|
||
### Setup
|
||
|
||
1. Create a new repo using this one as a template.
|
||
2. Clone the repo to your local dev folder.
|
||
3. Install dependencies (if asked to overwrite, choose "no"):
|
||
|
||
```bash
|
||
# Install theme dependencies
|
||
composer install
|
||
npm i
|
||
|
||
# Configure playwright for testing
|
||
npm init playwright@latest --yes "--" . '--quiet' '--browser=chromium' '--browser=firefox' '--browser=webkit' '--lang=js'
|
||
|
||
# Perform initial build
|
||
npm run build
|
||
```
|
||
|
||
4. Create .env file from .env.example and set:
|
||
|
||
- `LOCALHOST_URL`: Local development URL.
|
||
- `BROWSERSYNC_PORT`: Port for BrowserSync (default: 5000).
|
||
|
||
5. Start building your project.
|
||
|
||
- Run `npm run start` to start the development server with live reloading.
|
||
- Activate the theme in your WordPress admin.
|
||
- (Optional) Import the sample content from `content`.
|
||
|
||
### Sart Development Server
|
||
|
||
- Run `npm run watch` or `npm run start` to start development server with live reloading.
|
||
- Changes to PHP, CSS, and JS files will trigger automatic reload.
|
||
|
||
### Production
|
||
|
||
- Run `npm run build` to compile and optimize CSS for production (normally handled by GitHub Actions).
|
||
|
||
### Deployment
|
||
|
||
- Deployment is handled via GitHub Actions.
|
||
- Ensure you update `.github/workflows/wpengine,yml` with the correct WP Engine deployment configuration (environment and theme folder).
|
||
|
||
## Testing
|
||
|
||
The theme includes a suite of testing tools to ensure code quality and functionality.
|
||
|
||
Accessibility tests using Playwright and Axe:
|
||
|
||
- Test files located in `tests`.
|
||
- Run via the [VSCode Playwright extension](https://marketplace.visualstudio.com/items/?itemName=ms-playwright.playwright) or with `npx playwright test --ui` in your terminal for the dedicated Playwright window.
|
||
- Tests include:
|
||
- `site-a11y.spec.js`: Accessibility tests for the site.
|
||
- Generates reports in `playwright-report` and screenshots in `test-results`.
|
||
|
||
Code linting for modified WordPress coding standards using phpcs:
|
||
|
||
- Run `composer lint` in your terminal to check PHP files for coding standards violations
|
||
- Test results are saved in `phpcs-results.txt`. Review the file for error details.
|
||
- Automated fixes noted in the results can be done using `composer fix` in your terminal.
|
||
|
||
### Files
|
||
|
||
- `404.php` - Displays a custom "Page Not Found" message when a visitor tries to access a page that doesn't exist.
|
||
- `archive.php` - Displays a list of posts from a particular archive, such as a category, date, or tag archive.
|
||
- `author.php` - Displays a list of posts by a specific author, along with the author's information.
|
||
- `category.php` - Displays a list of posts from a specific category.
|
||
- `footer.php` - Contains the footer section of the theme, typically including closing HTML tags and widgets or navigation in the footer area.
|
||
- `front-page.php` - The template used for the front page of the site, either static or a blog, depending on the site settings.
|
||
- `functions.php` - Imports custom functionality for the theme. **Should not be edited**, all changes/additions should live in the `lib` directory.
|
||
- `header.php` - Contains the header section of the theme, typically including the site's title, meta tags, and navigation menu.
|
||
- `index.php` - The fallback template for all WordPress pages, used if no other more specific template (like `category.php` or `single.php`) is available.
|
||
- `page.php` - Displays individual static pages, such as "About" or "Contact" pages.
|
||
- `screenshot.png` - An image of the theme’s design, shown in the WordPress theme selector to give users a preview of the theme's appearance.
|
||
- `search.php` - Displays the results of a search query, showing posts or pages that match the search terms entered by the user.
|
||
- `single.php` - Displays individual posts, often used for blog posts or custom post types.
|
||
- `tag.php` - Displays a list of posts associated with a specific tag.
|
||
|
||
### Folders
|
||
|
||
- `acf` - Storage for ACF field group JSON files. You shouldn't edit anything here manually.
|
||
- `bin` - Helper files for the dev and build processes.
|
||
- `lib` - Main library for the theme, including the Twig engine and other helper functions.
|
||
- `static` - Static assets for the theme, including CSS, JS, and images. The rendered stylesheet is stored here.
|
||
- `styles` - The raw CSS files compiled by Tailwind into the final CSS file.
|
||
- `views` - Twig view templates for the theme. This is where you will do most of your work.
|
||
- `blocks` - ACF block templates.
|
||
- `boilerplate` - Example ACF block template. Used to build your own blocks (more on this below).
|
||
- `icons` - Icon templates for SVG icons.
|
||
- `partials` - Partial templates for the page hero, breadcrumb, and social media sections.
|