ucsc / ucsc-content-blocks

A collection of WordPress blocks for UC Santa Cruz.

UC Santa Cruz Content Blocks

A collection of WordPress blocks for UC Santa Cruz. Built with @wordpress/scripts. Additional blocks will be added as use cases arise.

Current Blocks

• Details -- a block that utilizes the <details> element that can be used as an accordion
• Details Wrapper -- a block that wraps multiple Details blocks, enabling them to be opened and closed simultaneously

Requirements

Cloning and installing this plugin requires:

• Git
• GitHub Cli (optional but helpful)
• Node.js/npm
• Composer

Block development will require a local WordPress development environment such as @wordpress/env.

Clone and install

• Clone repo: gh repo clone ucsc/ucsc-content-blocks
• cd ucsc-content-blocks/
• npm install
• composer install

Directory structure and scripts

This plugin was developed using @wordpress/scripts (see the "devDependencies" object in package.json).

Both src/ and build/ directories are located within the blocks/ directory at the project root.

blocks/
 -build/
  --block-one/
  --block-two/
 -src/
  --block-one/
  --block-two/

Build and Start

The following npm scripts will build (or start) the entire plugin.

npm run build

npm run start (start will initiate a perpetual build after every file save)

Additional scripts

There are build and start scripts for individual blocks and for various additional tasks such as linting and packaging. Please review the "scripts" object in package.json. All additional scripts are provided by the @wordpress/scripts package.

Creating a new block

If you'd like to contribute to this project and create a new block, please review our contributing guidelines.

Scaffold files

The @wordpress/scripts package includes a script called create-block that allows you to initiate a new block for development.

From within the blocks/src/ directory, issue the command

npx @wordpress/create-block --no-plugin

and follow the prompts to name and namespace your new block.

You will see a new directory in blocks/src/ that contains your new block's files.

The script will create a functioning "Hello World" block that you can enqueue via this plugin and review in your development environment prior to digging into the code.

The --no-plugin flag will restrict creation to block scaffolding only, which is helpful when developing a plugin that has multiple blocks.

For more information, see the @wordpress/create-block documentation in the WordPress Block Editor Handbook.

Enqueue block

Once the new block is created, it must be enqueued via the ucsc_register_content_blocks() function in the ucsc-content-blocks.php file.

/**
 * Register blocks
 */
function ucsc_register_content_blocks() {

 // Register blocks in the format $dir => $render_callback.
 $blocks = array(
  'details'  => '',
  'details-wrapper'  => '',
 );
...
}

Enqueue the newly created block by adding a line to the $blocks array with the name of the directory that was created with the block-creation script:

 $blocks = array(
  'details'  => '',
  'details-wrapper'  => '',
  'new-block'  => '',
 );

Activate this plugin in your development environment. If the new block was enqueued propperly, you'll be able to chose the newly created "Hello World" block in the block editor of a WordPress Page or Post.

Once you've verified it was built and enqueued properly, configure the build and start scripts for your new block.

Add build and start scripts for new block

As described above, the npm build and npm start commands will build and start the entire plugin. When developing a new block, it's convenient to build and start just the block you're working on.

You can add build and start scripts for your new block by editing the "scripts" object in the package.json file.

"scripts": {
  "start": "wp-scripts start --webpack-src-dir=blocks/src/ --output-path=blocks/build/",
  "build": "wp-scripts build --webpack-src-dir=blocks/src/ --output-path=blocks/build/",
 ...
  "start:details": "wp-scripts start --webpack-src-dir=blocks/src/details --output-path=blocks/build/details",
  "build:details": "wp-scripts build --webpack-src-dir=blocks/src/details --output-path=blocks/build/details",
  "start:details-wrapper": "wp-scripts start --webpack-src-dir=blocks/src/details-wrapper --output-path=blocks/build/details-wrapper",
  "build:details-wrapper": "wp-scripts build --webpack-src-dir=blocks/src/details-wrapper --output-path=blocks/build/details-wrapper",
 ...
 }

Use the entries for the existing blocks as a template and add entries to build and start your new block.

"scripts": {
  "start": "wp-scripts start --webpack-src-dir=blocks/src/ --output-path=blocks/build/",
  "build": "wp-scripts build --webpack-src-dir=blocks/src/ --output-path=blocks/build/",
 ...
  "start:details": "wp-scripts start --webpack-src-dir=blocks/src/details --output-path=blocks/build/details",
  "build:details": "wp-scripts build --webpack-src-dir=blocks/src/details --output-path=blocks/build/details",
  "start:details-wrapper": "wp-scripts start --webpack-src-dir=blocks/src/details-wrapper --output-path=blocks/build/details-wrapper",
  "build:details-wrapper": "wp-scripts build --webpack-src-dir=blocks/src/details-wrapper --output-path=blocks/build/details-wrapper",
  "start:new-block": "wp-scripts start --webpack-src-dir=blocks/src/new-block --output-path=blocks/build/new-block",
  "build:new-block": "wp-scripts build --webpack-src-dir=blocks/src/new-block --output-path=blocks/build/new-block",
 ...
 }

Save your changes to package.json and test that they work:

• npm run start:new-block
• npm run build:new-block

Bingo!

Go develop your new block.

Resources

• WordPress Block Editor Handbook
• Create a Block Tutorial
• @wordpress/scripts
• @wordpress/create-block
• @wordpress/env

Contributors

• Jason Chafin

ucsc-content-blocks's Issues

Replace ::before pseudo-class styles with ::marker

Follows the browser convention of using ::marker for the details element summary.

Expand/Collapse button not contained withing bounding <div>

Needs some styling.

Dashicons don't show on front-end when logged out

Dashicons need to be enqueued via the plugin for them to show up on the front-end when a user is logged out.

Details Wrapper: `const ALLOWED_BLOCKS` not restricting wrapper blocks

The Details wrapper should limit the blocks placed within it to only the Details block. A constant has been set up to take care of that but it's no doing its job.This should be fixed.

Details wrapper: styles for the expand all button

Revert pseudo-classes on `<summary>` element back to `:before`

We converted the pseudo-classes on the style variations from :before to :marker; however, :marker does not allow absolute positioning (that we have found).

We need to revert back to the :before pseudo-class to re-enable absolute positioning.

Details: inherited margin on the `<p>` block

The paragraph block is inheriting a 1em margin from the user agent styleshet via themargin-block-start declaration.

This messes up the spacing on the <summary><p> elements.

Remove ability to make a link in the summary of the details element

Details: add clickListener to Summary field

After adding the details block, the initial click into the field opens/closes the block prior to being able to edit the field. The edit.js file currently employs a "listener" on the space bar. I believe we need one for Click, too.

Current listener as example:

const keyUpListener = ( e ) => { if ( e.keyCode === SPACE ) { e.preventDefault(); } };

Details wrapper: build Expand/Collapse All button with button.json

While the Expand/Collapse All button on the details wrapper is built by the block, it is returned via raw html, not using block attributes. It needs to be built properly suing block components and attributes defined in block.json

Details-wrapper: enqueue front end JavaScript with block

The javascript file that provides the Expand/Collapse All button functionality is registered and enqueued globally via the ucsc-content-blocks.php file when the plugin is activated.

According to the WordPress Block Editor Handbook, Frontend Enqueueing is possible via the block.json file, which would only enqueue the JavaScript when the block is used.