UCSC Gutenberg Blocks

About The Plugin

A WordPress plugin providing UCSC custom Gutenberg blocks: class schedule, course catalog, and campus directory as seen at:

• Courses
• Class Schedule
• Directory

Development Setup Instructions

• Follow the setup instructions in the wp-dev.ucsc README

How To Contribute Code / Develop

• From the wordpress root (by default wp-dev.ucsc): cd public/wp-content/plugins/ucsc-gutenberg-blocks
• This is a separate repo that gets cloned to this directory during the initial setup setup.sh
• Create Feature branch git checkout -b "feature/WPM-xxx_my_feature"
• Write code, see Anatomy of a Custom Block
• Commit and push your changes, then create a PR into the main branch on GitHub
• Instructions for pushing to the development and production campus press servers

Basic Block Development

As a reference a commit to adding a demo block to this repo

This commit shows how to create a Dynamic Block vs a Static Block. There are many benefits to using Dynamic Blocks, here are some resources discussing the benefits:

• https://design.oit.ncsu.edu/2019/03/11/choosing-dynamic-blocks-one/
• https://www.youtube.com/watch?v=0EtQO1kx8Vg

Instructions

• Create a file in src/classes to hold the PHP/Wordpress code.
  • Actions can be added
  • Blocks can be registered
  • Site and Network settings
• Include the new file in the index.php file and instantiate the class
• Create a js file in src/blocks/ directory
  • This file can import libs and components but is not a component itself
  • Create and export a function where you can register the block.
  • Make sure the name you are registering here matches the name you registered in PHP
• In src/index.js import your function and call it so that the block gets registered.
• If needed, add JS and CSS component code under src/components

Testing

Unit tests use Jest via @wordpress/scripts and @testing-library/react for rendering Gutenberg block edit components.

Running Tests

From the wp-dev.ucsc project root, run tests inside Docker:

docker compose -f docker-compose.yml -f docker-compose-start.yml run --rm \
  -w /var/www/html/wp-content/plugins/ucsc-gutenberg-blocks \
  plugin_npm_start npm test

Or to run a single test file:

docker compose -f docker-compose.yml -f docker-compose-start.yml run --rm \
  -w /var/www/html/wp-content/plugins/ucsc-gutenberg-blocks \
  plugin_npm_start npx wp-scripts test-unit-js --testPathPattern=ClassSchedule

Coverage

Run JavaScript coverage from the plugin directory:

npm run test:coverage

The report is written to:

coverage/coverage-summary.json
coverage/lcov.info
coverage/lcov-report/index.html

The equivalent Docker command, from the wp-dev.ucsc project root, is:

docker compose -f docker-compose.yml -f docker-compose-start.yml run --rm \
  -w /var/www/html/wp-content/plugins/ucsc-gutenberg-blocks \
  plugin_npm_start npm run test:coverage

Run PHP coverage from the plugin directory:

bash tests/php/run-php-coverage.sh

The PHP report is written to:

coverage/php/clover.xml
coverage/php/coverage-raw.json

The latest three-block assessment is:

Overall JavaScript coverage is 38.86% statements, 41.15% branches, 35.53% functions, and 38.83% lines because untouched components and legacy files are included. The JavaScript suite passed 72 tests across 5 suites.

PHP coverage reports 100% statement coverage (545/545), but the harness is not a clean passing baseline: 3 of 4 suites passed. The CampusDirectoryShortcodeTest.php suite contains four intentionally failing XSS assertions documenting existing escaping vulnerabilities.

The plugin's structural gap report is read-only and groups classes, templates, blocks, and components that are named by no test:

python3 /path/to/ucsc-wp-block-dev/skills/validate/scripts/coverage-report.py . --gaps

This structural report is a gap floor, not line or branch coverage. On systems where the script requires Python 3.10 or newer, use that interpreter; Python 3.9 cannot parse its union type syntax.

Writing Tests

Test files live in src/blocks/__tests__/ and follow the naming convention BlockName.test.js. Since WordPress packages like @wordpress/components are provided at runtime (not installed as dependencies), they must be mocked with { virtual: true }:

jest.mock('@wordpress/components', () => ({
  Panel: ({ children }) => <div>{children}</div>,
}), { virtual: true });

Child components (dropdowns, layouts, etc.) are also mocked so tests focus on the block's own logic rather than its children.

VScode/Xdebug setup

The PHP Debug plugin is required. On the debug tab click Create a launch.json file and select type php.

You can replace the contents of launch.json with the following:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html/wp-content/plugins/ucsc-gutenberg-blocks": "${workspaceRoot}"
      },
      "hostname": "wp-dev.ucsc"
    }
  ]
}