VDI-Starter/README.md

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 AC Bug/Issue Tracking: 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

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
├── 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
│       │   ├── FocusStyling.js    # Replace focus styling for keyboard navigation
│       │   ├── GetHeaderHeight.js # Calculate header height and set it as a CSS variable
│       │   └── Navigation.js      # Script controlling navigation behavior
│       ├── 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
• 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

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

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

blockCategories($categories)

• Adds custom block category for theme blocks
• Parameters: $categories - The existing block categories
• Returns: Modified array of categories

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

pageSearch($query)

• Modifies the WordPress query for page search functionality
• Parameters: $query - The WordPress query object
• Returns: void

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

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

searchResultFilter($posts, $query)

• Filters and processes search results
• Parameters:
  • $posts - Array of posts
  • $query - The search query
• Returns: Filtered array of posts

extras.php

getChildrenPages()

• Gets child pages of the current page
• Returns: Array of child pages or empty array

hasSidebar()

• Checks if sidebar should be rendered
• Returns: Boolean indicating sidebar presence

hasPageHeader()

• Checks if the page should render a page header
• Returns: Boolean indicating page header presence

createOwnerRole()

• Creates a new WordPress role named "Owner" with admin capabilities minus plugin/theme management
• Returns: void

getTheTitle()

• Gets the title based on the current context (archive, search, etc.)
• Returns: Appropriate title string

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

enqFEAssets()

• Enqueues frontend CSS and JS files
• Returns: void

enqBEAssets()

• Enqueues backend (admin/editor) CSS and JS files
• Returns: void

Class: ACF (class-acf.php)

Handles ACF (Advanced Custom Fields) functionality

saveJson($path)

• Sets the path for saving ACF field groups as JSON
• Parameters: $path - The default path
• Returns: Modified path

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

generate()

• Generates breadcrumb data based on the current page
• Returns: Array of breadcrumb items

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 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:

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:

<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"):

   composer install
   npm i
   npm init playwright@latest --yes "--" . '--quiet' '--browser=chromium' '--browser=firefox' '--browser=webkit' '--lang=js'
   

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 build to build the basic styles.
   • 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 or with npx playwright test in your terminal.
• 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.