Skip to content

Latest commit

 

History

History
573 lines (447 loc) · 24 KB

README.md

File metadata and controls

573 lines (447 loc) · 24 KB
Raw

WDS BT

WebDevStudios. Your Success is Our Mission.

License: GPL v3 Code Quality Security

Table of Contents

Overview

Meet WDS BT, a stylish block theme, tailored for WordPress, featuring native blocks and site editor compatibility. Boasting a contemporary aesthetic, an intuitive interface, and seamless WordPress block editor integration, WDS BT ensures a polished and adaptable framework across all devices. It's crucial to understand that WDS BT is crafted as a foundational theme rather than a parent theme. This difference affords users a flexible starting point for customization. Elevate your website with WDS BT, where design effortlessly meets functionality, providing the ideal canvas for your creative expression.

Features

Feature Description
Native Block Support Stylish block theme tailored for WordPress with support for native blocks and site editor.
Contemporary Aesthetic Boasts a contemporary aesthetic design to enhance the visual appeal of your website.
Intuitive Interface Offers an intuitive interface for easy navigation and seamless user experience.
Seamless Integration with Block Editor Integrates seamlessly with the WordPress block editor for efficient content creation and editing.
Foundation Theme, not Parent Theme Crafted as a foundational theme rather than a parent theme, providing flexibility for customization.
Polished and Adaptable Framework Ensures a polished and adaptable framework across all devices, enhancing responsiveness and usability.
Responsive Design Responsive design ensures optimal viewing experience across various screen sizes and devices.
Flexible Starting Point for Customization Provides a flexible starting point for customization, allowing users to tailor the theme to their needs.
Automated Workflow Actions for Code Quality Automated workflow actions to verify code quality adherence using WordPress coding standards.
Contribution and Support Welcomes contributions and support tickets from users, with detailed guidelines for submitting pull requests.
Free Software with GPL License Released under the terms of the GNU General Public License version 2 or any later version, ensuring freedom and openness.

🔝 Back to Top

Requirements

Getting Started

  1. Set up a local WordPress development environment, we recommend using Local.
  2. Ensure you are using WordPress 6.4+.
  3. Clone / download this repository into the /wp-content/themes/ directory of your new WordPress instance.
  4. In the WordPress admin, use the Appearance > Themes screen to activate the theme.

🔝 Back to Top

Development

Theme Structure 
		
			└── wds-bt/
				├── CONTRIBUTING.md
				├── README.md
				├── a11y.cjs
				├── assets
				│   ├── fonts
				│   ├── images
				│   ├── index.js
				│   ├── js
				│   │   ├── block-filters
				│   │   │   ├── index.js
				│   │   │   └── unregister-core-embed.js
				│   │   ├── block-variations
				│   │   │   └── index.js
				│   │   ├── global
				│   │   │   ├── header.js
				│   │   │   ├── index.js
				│   │   │   └── table.js
				│   │   ├── index.js
				│   │   └── templates
				│   │       └── index.js
				│   └── scss
				│       ├── _index.scss
				│       ├── abstracts
				│       │   ├── _index.scss
				│       │   ├── mobile-only-mixins.scss
				│       │   ├── responsive-mixins.scss
				│       │   └── utility.scss
				│       ├── base
				│       │   ├── _index.scss
				|       |   ├── forms.scss
				│       │   ├── global.scss
				│       │   └── pagination.scss
				│       ├── blocks
				│       │   └── core
				│       │       ├── audio.scss
				│       │       ├── button.scss
				│       │       ├── calendar.scss
				│       │       ├── code.scss
				│       │       ├── comments.scss
				│       │       ├── cover.scss
				│       │       ├── file.scss
				│       │       ├── footnotes.scss
				│       │       ├── gallery.scss
				│       │       ├── group.scss
				│       │       ├── latest-comments.scss
				│       │       ├── latest-posts.scss
				│       │       ├── list.scss
				│       │       ├── navigation.scss
				│       │       ├── page-list.scss
				│       │       ├── post-author.scss
				│       │       ├── post-comments-form.scss
				│       │       ├── post-navigation-link.scss
				│       │       ├── post-terms.scss
				│       │       ├── preformatted.scss
				│       │       ├── pullquote.scss
				│       │       ├── query-pagination.scss
				│       │       ├── query.scss
				│       │       ├── quote.scss
				│       │       ├── search.scss
				│       │       ├── separator.scss
				│       │       ├── social-links.scss
				│       │       ├── table.scss
				│       │       ├── tag-cloud.scss
				│       │       ├── verse.scss
				│       │       └── video.scss
				│       ├── template-parts
				│       │   ├── _index.scss
				│       │   ├── footer.scss
				│       │   └── header.scss
				│       └── pages
				│           ├── _index.scss
				│           ├── 404.scss
				│           ├── archive.scss
				│           └── search.scss
				├── composer.json
				├── composer.lock
				├── functions.php
				├── inc
				│   ├── functions
				│   │   └── security.php
				│   ├── hooks
				│   │   ├── enable-svg.php
				│   │   ├── enqueue-block-stylesheet.php
				│   │   ├── register-block-categories.php
				│   │   ├── register-block-pattern-categories.php
				│   │   ├── register-block-styles.php
				│   │   ├── register-block-variations.php
				│   │   ├── remove-archive-title-prefix.php
				│   │   └── unregister-block-variations.php
				│   └── setup
				│       ├── preload-scripts.php
				│       ├── scripts.php
				│       └── setup.php
				├── lefthook.yml
				├── package-lock.json
				├── package.json
				├── parts
				│   ├── footer.html
				│   └── header.html
				├── patterns
				│   ├── footer-default.php
				│   └── header-default.php
				├── phpcs.xml.dist
				├── postcss.config.js
				├── readme.txt
				├── screenshot.png
				├── style.css
				├── styles
				│   └── dark.json
				├── templates
				│   ├── 404.html
				│   ├── archive.html
				│   ├── index.html
				│   ├── page-blank.html
				│   ├── page-no-title.html
				│   ├── page.html
				│   ├── search.html
				│   └── single.html
				├── theme.json
				├── webpack.config.js
				└── webpack.prod.js
Setup

From the command line, change directories to your new theme directory:

cd /wp-content/themes/your-theme

The command below will remove node_modules, vendor, build, package-lock.json, and composer.lock files. Install theme dependencies and trigger an initial build.

Note: You will need to have Composer 2 and NPM 10 installed first.

npm run setup

NPM Scripts

From the command line, type any of the following to perform an action:

Command Description
🌐 npm run a11y Run accessibility tests using Pa11y-CI.
🛠️ npm run build Build the theme using wp-scripts.
🔨 npm run create-block Create a custom block with Webpack and @wordpress/create-block.
📝 npm run format Format files using wp-scripts and composer.
🔍 npm run lint Run all linting scripts.
🎨 npm run lint:css Lint CSS files using wp-scripts.
🚀 npm run lint:js Lint JavaScript files using wp-scripts.
📚 npm run lint:md:docs Lint Markdown files in the docs directory using wp-scripts.
🐘 npm run lint:php Lint PHP files using composer.
📦 npm run lint:pkg-json Lint package.json and composer.json using wp-scripts.
🔄 npm run packages-update Update dependencies defined in package.json using wp-scripts.
🔄 npm run reset Remove node_modules, vendor, build, package-lock.json, and composer.lock files.
🛠️ npm run setup Reset, install dependencies, and build the theme.
▶️ npm run start Start the development server using wp-scripts.

🔝 Back to Top

Creating Blocks

  1. Run the Block Creation Script Navigate to your project root in the terminal and run the following command to create a new block:
npm run create-block

Follow the prompts to configure your new block. The script will scaffold a new block structure inside assets/blocks/.

  1. Build your block After editing and configuring your block, build your project to compile assets using webpack:
npm run build

This will process JavaScript, SCSS, optimize images, and generate necessary files in the build/ directory and custom blocks will have files generated in the blocks/ directory.

🔝 Back to Top

Customizations

Registering Block Styles

  1. Open the inc/hooks/register-block-styles.php file in your theme directory.

  2. Add a new block style entry with the following mandatory properties:

    • Name: The identifier used to compute a CSS class for the style.

    • Label: A human-readable label for the style.

    Example:

    'block_name' => array(
    'name' => __( 'label', 'wdsbt' ),
),
Overriding/Customizing Block Styles

  1. Navigate to the assets/scss/blocks/ directory within your theme. If overriding a core block style, use the core folder, if overriding a block from a plugin use the third-party folder.

  2. Create an SCSS file with the exact filename as the block name you want to customize. This file will house your custom styles for that specific block.

  3. Files within the assets/scss/blocks/core/ directory are automatically enqueued, simplifying the integration of your custom styles into the WordPress block editor. Do not import these files into the main index.scss

  4. After adding your custom SCSS file, run the following command to compile and apply your changes:

    npm run build
Creating Block Variations

  1. In the assets/js/block-variations directory within your theme, create a new JavaScript file. This file will contain the definition of your block variation.

  2. Import the newly created file into the assets/js/block-variations/index.js file. This step ensures that your variation is included in the build process.

  3. Use the wp.blocks.registerBlockVariation() function to officially register your block variation. This function takes the name of the original block and an object defining the variation.

    Example:

    // In your variations JavaScript file
wp.blocks.registerBlockVariation('core/paragraph', {
    name: 'custom-variation',
    title: __('Custom Variation', 'wdsbt'),
    attributes: { /* Define your custom attributes here */ },
    // Add more variation settings as needed
});

    Original Block Name: Provide the name of the original block for which you are creating the variation. Variation Object: Define the properties of your block variation, including the name, title, attributes, and any additional settings.

NOTE: To find the correct block name, open the block editor, launch the browser console and type wp.blocks.getBlockTypes(). You will see the complete list of block names (from core or third-party).

Unregister Blocks and Variations

This functionality allows you to unregister and disable specific core Gutenberg blocks, styles, and variations that are not needed on your WordPress website. By removing these unused blocks and variations, you can streamline the Gutenberg editor and improve the overall performance of your site.

Implementation

The script in assets/js/block-filters/unregister-core-embed.js loops through a list of unused blocks and variations, unregistering them from the Gutenberg editor. Additionally, it keeps only the specified embed variations for the core/embed block.

Example

// List of Gutenberg blocks to unregister
const unusedBlocks = [
    'core/file',
    'core/latest-comments',
    'core/rss',
    // Add more unused blocks as needed
];

// List of Gutenberg block variations to unregister
const unregisterBlockVariations = [
    // Example:
    // {
    //     blockName: 'core/group',
    //     blockVariationName: 'group-stack',
    // },
];

// Keep only the necessary embed variations
const keepEmbeds = [
    'twitter',
    'wordpress',
    'spotify',
    // Add more necessary embed variations as needed.
];

Mixins

Responsive Mixins

This SCSS file assets/scss/abstracts/_responsive-mixins.scss provides mixins for creating responsive media queries with both minimum and maximum width conditions. The file promotes modular and maintainable styling by allowing the easy application of responsive styles based on screen width.

To use the responsive mixin, include it in your SCSS code and customize it according to your project's breakpoints. Here's an example:

// Usage examples
.my-element {
  width: 100%;

  // Apply styles when the screen width is 600px or more
  @include responsive-min(600px) {
    /* Your responsive styles for min-width: 600px */
  }

  // Apply styles when the screen width is up to 600px
  @include responsive-max(600px) {
    /* Your responsive styles for max-width: 600px */
  }

  // Apply styles when the screen width is between 600px and 1200px
  @include responsive-range(600px, 1200px) {
    /* Your responsive styles for a range of widths */
  }
}
Mobile Only Mixins

This SCSS file assets/scss/abstracts/_mobile-only-mixins.scss contains a mixin called mobile-only designed to visually hide elements for accessibility (a11y) while making them visible on mobile devices.

Include the mobile-only mixin in your SCSS file where you want to hide elements on desktop but make them visible on mobile:

// Example usage:
.my-element {
  @include mobile-only;
}

Stylelint Configuration

Extends

The configuration extends two base configurations:

  • @wordpress/stylelint-config/scss: This extends the WordPress SCSS stylelint configuration.
  • stylelint-config-prettier: This extends the Prettier stylelint configuration.

These base configurations provide a foundation for enforcing consistent styles and conventions in SCSS files.

Rules
  • declaration-no-important: Disallows the use of !important in declarations.
  • scss/at-rule-no-unknown: Allows specific SCSS at-rules to be ignored, such as @apply, @layer, @variants, @responsive, and @screen.
  • string-quotes: Enforces the use of single quotes for strings.
  • declaration-property-unit-allowed-list: Specifies allowed units for the following properties:
    • font-size: allows only em and rem
    • line-height: unitless
    • border: allow only px
    • margin: allows only em and rem
    • padding: allows only em and rem

🔝 Back to Top

Accessibility and Code Quality and Security Checks

WDS BT is equipped with automated workflow actions that ensure code security and uphold code quality standards with every commit. Accessibility check has been integrated into the development process, guaranteeing that websites built with WDS BT prioritize accessibility compliance based on WCAG 2.2 standards. This proactive approach underscores WDS BT's commitment to providing an inclusive user experience for all.

A11y Test (npm run a11y)
  • Purpose: To guarantee that the theme meets the Web Content Accessibility Guidelines (WCAG) standards.
  • Running the A11y Test Script:
    • Accessibility checks are integrated into the development process using pa11y-ci by running: 
          npm run a11y
    • You will be prompted to enter the URL of the site you want to test for accessibility. If you leave it blank, it will default to https://wdsbt.local.
  • Script Details: The script performs the following actions
    • Prompts for URL: You will be prompted to enter the URL of the site you want to test for accessibility. If you leave it blank, it will default to https://wdsbt.local.
    • Checks for Sitemap: Attempts to access the sitemap at [URL]/wp-sitemap.xml.
    • Runs Accessibility Tests:
      • If the sitemap is found, the script runs pa11y-ci on the sitemap URL. 
          $ npm run a11y
  Please enter the URL to test for accessibility (leave blank to use your local: https://wdsbt.local):
  > https://example.com
  Sitemap found at https://example.com/wp-sitemap.xml. Running pa11y-ci on the sitemap...
  [output from pa11y-ci]
      • If the sitemap is not found, the script runs pa11y-ci on the main page URL. 
          $ npm run a11y
  Please enter the URL to test for accessibility (leave blank to use your local: https://wdsbt.local):
  > https://example.com
  No sitemap found at https://example.com/wp-sitemap.xml. Running pa11y-ci on the main page...
  [output from pa11y-ci]
  • Violation Reports: Any detected accessibility violations are displayed in the console for immediate review and action.
Security Check (security.yml)
  • Purpose: Perform security checks on dependencies to identify vulnerabilities.
  • Configuration: Uses symfonycorp/security-checker-action@v5 for security scanning.
  • Concurrency Handling: Ensures only one instance runs per branch concurrently, cancelling previous runs.
  • Job:
    • Name: Security check
    • OS: Ubuntu latest
  • Conditional Execution:
    • Runs only if:
      • Not a scheduled event (schedule), or
      • Scheduled event, but repository owner is not "webdevstudios."
Code Quality Check (assertions.yml)
  • Purpose: To verify code quality adherence using WordPress coding standards.
  • Configuration: The code quality check is performed using predefined assertions in assertions.yml.
  • Action Requirement: All detected code issues and violations must be addressed and fixed before any commit can successfully pass through.
  • Report Display: The assertions report will appear in the command-line interface (CLI) during the checks.
Integration Process with LeftHook
  1. Commit Changes: Make your changes to the codebase as usual.
  2. Automated Checks on Commit: LeftHook triggers automated checks upon each commit.
  3. Review Reports: Check the generated reports for any accessibility violations or code quality issues.
  4. Address Issues: Address and fix any identified violations or issues.
  5. Recommit: Once all issues are resolved, recommit your changes.
  6. Passing Commit: Your commit will successfully pass through once all checks are clear.
  7. Create Pull Request (PR): When you create a PR, the actions are triggered again to run on the PR branch.
  8. Review PR Checks: Review the checks on the PR to ensure compliance before merging.

Automated Versioning Process

To handle cache busting for CSS and JS files, this theme automatically appends the file modification time as a version parameter to the URLs of enqueued styles and scripts, ensuring that browsers fetch the most recent version whenever the files are updated.

How It Works
  1. Hooking into the style_loader_src and script_loader_src filters, which handle the URLs of enqueued styles and scripts.
  2. Using the filemtime() function to retrieve the last modified time of the style.css file, appending it as the version (ver) parameter in the asset URLs.
  3. This ensures that browsers always fetch the latest version of your CSS and JS files, preventing them from serving cached versions after updates.

Contributing and Support

Your contributions and support tickets are welcome. Please see our contributing guidelines before submitting a pull request.

WDS BT is free software, and is released under the terms of the GNU General Public License version 2 or any later version. See LICENSE.md for complete license.

Acknowledgements

The WDS-BT theme was initially inspired by the Powder theme. We acknowledge and thank the creators of Powder for their work.

🔝 Back to Top