WPLite

This guide will help you set up and run a local installation of Wordpress using the WPLite theme.

Table of Contents

• Table of Contents
• Prerequisites
• Installation
• Folder Structure
  • Key Files and Directories
• VSCode Components
• Style Guide - HTML - PHP
• Templating Guide
  • Additional Scripts
• Features
  • Dynamic theme customizer
  • Organized components
  • Organized page templates
  • Organized views
  • Built-in custom fields registration
  • Form Builder
• Reference Links
• Conclusion

Prerequisites

Before you begin, ensure you have the following installed on your system:

• Docker (version 4+ or later)

⬆ back to top

Installation

Download and install Docker Desktop from Docker's official website based on your operating system (Windows, macOS, or Linux). Then run it after the installation.

Copy the .env-template file to .env and modify it as needed:

cp .env-template .env

Run the development server:

docker-compose up

To watch templates or page-templates scss files:

make dev:templates

make dev:page-templates

Compile the theme:

make compile # You can pass arg `name=my-theme`. Defaults to `name=wplite`

The compile command will generate a wplite folder which we can zip and upload to development, staging or live server.

⬆ back to top

Folder Structure

project
├── theme
|   ├── assets
|   ├── lib
|   ├── components
|   ├── template-parts
|   ├── templates
|   ├── vendor
|   ├── 404.php
|   ├── archive.php
|   ├── category.php
|   ├── comments.php
|   ├── footer.php
|   ├── functions.php
|   ├── header.php
|   ├── home.php
|   ├── index.php
|   ├── page.php
|   ├── screenshot.png
|   ├── search.php
|   ├── single.php
|   ├── style.css
|   └── tag.php
├── .editorconfig
├── .env.template
├── docker-compose.yml
├── package-lock.json
└── package.json

Key Files and Directories

• docs/: Contains the docs for the application.
• theme/: Contains the main source code for the application.
  • assets/: Contains static assets like css, js, images and fonts.
  • lib/: Contains php classes, functions, structure related templates, custom components, widgets and re-usable custom fields.
    • custom-field-groups: Includes re-usable custom field groups .json files.
  • components/: Custom components.
  • template-parts/: Custom template parts.
  • templates/: Custom page templates.
  • vendor/: Vendor php modules.
  • 404.php: The template for displaying 404 page.
  • archive.php: The template for displaying archive pages.
  • category.php: The template for displaying category pages.
  • comments.php: The template for displaying comments.
  • footer.php: The template for displaying the footer.
  • front-page.php: The template for displaying front-page.
  • functions.php: The main functions php file.
  • header.php: The template for displaying the header.
  • home.php: The template for display blog posts page.
  • index.php: The main template page.
  • page.php: The template for displaying all pages.
  • screenshot.png: The template for displaying the header.
  • search.php: The template for displaying the header.
  • single.php: The template for displaying all single posts.
  • style.css: The main stylesheet css file.
  • tag.php: The template for displaying tag pages.
• .editorconfig: Defines coding styles and indentation settings for consistent formatting across different editors and IDEs.
• .env-template: The .env template file.
• docker-compose.yml: The docker-compose.yml file configures and manages all application services, allowing you to build and run your multi-container Docker application with a single command.
• package.json: The project's manifest file, listing metadata, dependencies, and scripts.

⬆ back to top

VSCode Components

The project includes custom VSCode code snippets, based on Bootstrap 5.3.3, to enhance your development workflow by providing quick access to commonly used code patterns and templates, improving productivity and efficiency. Here are the following reusable vscode snippets:

• wplite:accordion
• wplite:button
• wplite:card
• wplite:container
• wplite:features
• wplite:hero-banner
• wplite:image
• wplite:link
• wplite:media-block
• wplite:page-content
• wplite:testimonial-carousel
• wplite:unordered-list

⬆ back to top

Style Guide

A well-defined style guide is essential for maintaining consistency, readability, and quality across your project's codebase. Here are some of our recommended style guide for the scaffold:

HTML

If an HTML element has multiple attributes, put every attributes into new line.

Why? It enables you to read and organize attributes better.

<a
  class="btn btn-light"
  role="button"
  title="Get Started">
  Get Started
</a>

PHP

We adhere to the PHP-FIG's PER Coding Style 2.0 for PHP development, in line with widely recognized best practices and industry standards.

Prefix php functions, hooks or filters.

Why? Prefixing PHP functions helps avoid naming conflicts, improves code organization, and makes it easier to identify which functions belong to your custom code or specific libraries.

add_action('some_hook', 'wplite_some_hook');
function wplite_some_hook()
{
  //...
}

Identify the types for function parameters and return values. Also add header comment to the functions to indicate its purpose.

Why? Identifying PHP function parameter and return types enhances code readability, reduces bugs, and enables better code completion and static analysis by clearly specifying the expected data types for function inputs and outputs.

/**
 * Displays the name and age of a person.
 *
 * @since 1.0.0
 *
 * @param string $name The person's name.
 * @param int $age The person's age.
 * @return string
 */
function wplite_some_function(string $name, int $age): string
{
  return $name .' is '. $age .'yrs old.';
}

⬆ back to top

Templating Guide

Templates lives in a custom folder called templates and are organized by folder names. Below is the folder/file structure for creating page templates.

templates
├── page/404/404.php                              						// 404 template
├── page/front-page/front-page.php                            // Front-page template
├── page/search/search.php                             				// Search template
├── page/<post_name>/<post_name>.php              						// Inner page template
├── archive/<post_type>/archive-<post_type.php>   						// Custom post type's archive template (e.g. templates/archive/movies/archive-movies.php)
├── single/<post_type>/single-<post_type>.php     						// Custom post type's singular template (e.g. templates/single/movies/single-movies.php)
├── taxonomy/<taxonomy_name>/taxonomy-<taxonomy_name>.php     // Custom taxonomy template (e.g. templates/taxonomy/category/taxonomy-category.php)

Additional Scripts

When adding 1st or 3rd party scripts, make sure to enqueue them only for specific templates by using the wordpress conditional tags.

Why? This ensures we only load them into templates where they are needed.

⬆ back to top

Features

Dynamic theme customizer

Includes a dynamic, JSON-based Customizer setup using Spyc, a lightweight JSON parser for PHP. It allows you to define WordPress Customizer panels, sections, and settings from a single lib/config/customizer.json configuration file.

Organized components

Custom components can be organized into folders. We need to register our component in order to use it. Use the after_setup_theme hook to register custom components.

<?php
use WPLite\Utils\Component;

add_action('after_setup_theme', 'wplite_child_register_components');
function wplite_child_register_components() {
	Component::register([
		'my-component',
	], 'Misc');
}

To use the component, use the Component::render() static method in your template:

<?php
use WPLite\Utils\Component;

Component::render('my-component', 'Misc', [
	'arg_1' => '',
]);

It is suggested that we put scss module in the same folder to organize the modules and then import it into your template's scss, see example:

@use "components/Misc/{{component_name}}/{{component_scss}}";

Organized page templates

Custom page templates can be organized into folders, and any CSS or JS files named identically to the corresponding page template PHP file will be automatically enqueued. Custom fields can also be defined via a JSON file, using the same filename as the associated page template (e.g., sample.json).

Organized views

Custom views can be organized into folders, and any CSS or JS files named identically to the corresponding component PHP file will automatically be enqueued, read docs

Built-in custom fields registration

The theme includes built-in custom fields registration system for templates and page templates. To register custom fields, create a .json file using the same name as youre template php file (e.g. front-page/front-page.json). Following are the available field types:

• text | url | email | password
• select
• wpeditor
• image ( stores the wp media attachment id )
• checkbox
• radio
• textarea
• group ( useful for nesting fields )
• repeater

You can also create and re-use custom fields by creating a .json file inside lib/custom-field-groups. To be able to re-use it, use extends in your field. See example usage:

{
  "name": "header-banner",
  "title": "Header Banner",
  "extends": "generic-content",
  "fields": []
}

# This will include lib/custom-field-groups/header-banner.json if it exists

Form Builder

This theme includes lightweight and extensible utility for building and handling front-end forms, read docs

⬆ back to top

Reference Links

• Bootstrap
• Wordpress Codex
• MDN Web Docs > HTML
• MDN Web Docs > Accessibility

Conclusion

You have now set up the WP scaffold and are ready to start building your wordpress website. For more information, detailed guides or wordpress coding reference, refer to the official Wordpress codex.

⬆ back to top