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

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"
    }
  ]
}