Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feat: create custom blocks #53

Merged
merged 12 commits into from
Sep 28, 2023
Merged
3 changes: 3 additions & 0 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ jobs:
- name: Install npm dependencies
run: npm ci

- name: Install custom plugin npm dependencies
run: npm run plugins:install

- name: Lint
run: npm run lint
env:
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -47,5 +47,7 @@ coverage/

plugins/rollbar/

src/plugins/**/build/

# DB imports/exports
sql
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,11 @@ This is a starter to fast-track WordPress websites. It provides a way to skip ma
| [CSS Class Reference](docs/css.md) |
| [Page Templates](docs/page-templates.md) |
| [Deployment](docs/deployment.md) |
| [Custom Blocks](docs/custom-blocks.md) |
| [How to Contribute](docs/contributing.md) |

## SparkPress Team
- **[Kasey Bonifacio](https://github.com/kaseybon)**
- **[Ricardo Fearing](https://github.com/rfearing)**
- **[Rob Tarr](https://github.com/robtarr)**
- **[Philip Zastrow](https://github.com/zastrow/)**
- **[Philip Zastrow](https://github.com/zastrow/)**
1 change: 1 addition & 0 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ services:
volumes:
- ./uploads:/var/www/html/wp-content/uploads
- ./theme:/var/www/html/wp-content/themes/sparkpress-theme
- ./src/plugins/example-blocks:/var/www/html/wp-content/plugins/example-blocks
- ./wp-configs/wp-config.php:/var/www/html/wp-config.php
- ./wp-configs/php.ini:/var/www/html/php.ini
- ./.env:/var/www/html/.env
Expand Down
30 changes: 30 additions & 0 deletions docs/custom-blocks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Custom Blocks

We have a plugin for custom blocks called `example-blocks`, which lives in `src/plugins`. For the blocks to be available in WordPress, these steps must be taken:

1. Run `npm run plugins:install` to install the plugin's npm dependencies
1. Run `npm start` for local development (this run's the plugin's `npm start` command)
1. Activate the "Example Blocks" plugin from the WordPress menu

For production builds, running `npm run build:prod` will also work, outputting production bundles for the blocks.

## Creating a New Custom Block

Follow these steps to create a new custom block and wire it up with the normal development/build processes:

1. Create a new folder at `src/plugins/example-blocks/<block-name>`
1. Either copy files from another block or manually create these files:
- `block.json`: configuration/metadata for the block
- `src/index.js`: entry point for the JS bundle
- `src/edit.js`: the component used while editing
- `src/save.js`: the component rendered on the site
- `src/editor.scss`: custom styles for the editor view
- `src/style.scss`: custom styles for the block when rendered on the site
1. Configure the custom block by updating `block.json`, namely the `name`, `title`, `icon`, and `description` fields
1. Implement the edit function, which will usually be form controls corresponding to attributes that you define in `index.js`
1. Implement the save function, which will consume the attributes defined in `index.js` and render the block's desired markup

## Useful Resources

- [Create a Block Tutorial](https://developer.wordpress.org/block-editor/getting-started/create-block/)
- [Component Reference](https://developer.wordpress.org/block-editor/reference-guides/components/)
1 change: 1 addition & 0 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
1. Install [Node][node]
1. In your terminal, navigate to the repo directory
1. Run `npm install`, wait for installation of modules
1. Run `npm run plugins:install` to install dependencies for custom plugins (you will need to activate the plugin from WordPress)
1. Run `npm start` to build the theme and have a watch task to automatically rerun the build when changes are made.

## Setting Local Environment Variables
Expand Down
20 changes: 14 additions & 6 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,28 +7,36 @@
"prestart": "run-p clean node-version",
"start": "run-p build:dev serve:dev",
"postserve:dev": "docker-compose down",
"clean": "rm -rf theme/",
"copy": "mkdir -p ./theme && cp -r ./src/php/* ./theme",
"clean": "rm -rf theme/ plugins/example-blocks/",
"copy": "run-p copy:*",
"copy:php": "mkdir -p ./theme && cp -r ./src/php/* ./theme",
"copy:plugins": "mkdir -p ./plugins && cp -r ./src/plugins/* ./plugins",
"prebuild:dev": "npm run clean",
"prebuild:prod": "npm run clean",
"build:dev": "run-p copy sass watch js:watch",
"build:prod": "run-s copy js:prod 'sass -- --style compressed'",
"build:dev": "run-p plugins:dev copy:php sass watch js:watch",
"build:prod": "run-s plugins:build copy js:prod 'sass -- --style compressed'",
"serve:dev": "docker-compose up",
"sass": "sass src/scss/base.scss theme/css/base.css",
"postsass": "postcss theme/css/base.css --use autoprefixer -r",
"js:watch": "NODE_ENV=development node esbuild.mjs",
"js:prod": "node esbuild.mjs",
"plugins:install": "cd src/plugins/example-blocks && npm ci",
"plugins:dev": "cd src/plugins/example-blocks && npm start",
"plugins:build": "cd src/plugins/example-blocks && npm run build",
"plugins:format": "cd src/plugins/example-blocks && npm run format",
"watch": "run-p watch:*",
"watch:php": "chokidar \"src/php/**/*\" -c \"npm run copy\"",
"watch:php": "chokidar \"src/php/**/*\" -c \"npm run copy:php\"",
"watch:scss": "chokidar \"src/scss/**/*\" -c \"npm run sass\"",
"test": "vitest --run",
"test:watch": "vitest",
"test:ci": "vitest --run --coverage",
"lint:plugins:js": "cd src/plugins/example-blocks && npm run lint:js",
"lint:plugins:css": "cd src/plugins/example-blocks && npm run lint:css",
dustin-jw marked this conversation as resolved.
Show resolved Hide resolved
"lint:js": "eslint src/js",
"lint:php": "./scripts/run.sh vendor/bin/phpcs --standard=wp-configs/sparkpress-standard.xml --extensions=php src/php -s -n",
"lint:scss": "stylelint src/scss/**/*.scss src/scss/*.scss --color --formatter verbose",
"lint:twig": "./scripts/run.sh vendor/bin/twigcs src/php/views",
"lint": "run-s lint:*",
"lint": "run-s lint:* lint:plugins:*",
"php:run": "./scripts/run.sh",
"export-db": "./scripts/export-db.sh",
"backup-db": "BACKUP=true ./scripts/export-db.sh",
Expand Down
18 changes: 18 additions & 0 deletions src/plugins/example-blocks/.editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# This file is for unifying the coding style for different editors and IDEs
# editorconfig.org

# WordPress Coding Standards
# https://make.wordpress.org/core/handbook/coding-standards/

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = tab

[*.{yml,yaml}]
indent_style = space
indent_size = 2
30 changes: 30 additions & 0 deletions src/plugins/example-blocks/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Coverage directory used by tools like istanbul
coverage

# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release

# Dependency directories
node_modules/

# Optional npm cache directory
.npm

# Optional eslint cache
.eslintcache

# Output of `npm pack`
*.tgz

# Output of `wp-scripts plugin-zip`
*.zip

# dotenv environment variables file
.env
14 changes: 14 additions & 0 deletions src/plugins/example-blocks/.prettierrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"printWidth": 110,
"endOfLine": "lf",
"trailingComma": "es5",
"tabWidth": 2,
"useTabs": true,
"semi": true,
"singleQuote": true,
"quoteProps": "as-needed",
"jsxSingleQuote": false,
"bracketSpacing": true,
"bracketSameLine": false,
"arrowParens": "always"
}
17 changes: 17 additions & 0 deletions src/plugins/example-blocks/blocks/hello-world/block.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "example-blocks/hello-world",
"version": "0.1.0",
"title": "Hello World",
"category": "example-custom-blocks",
"icon": "nametag",
"description": "Prints Hello World!",
"supports": {
"html": false
},
"textdomain": "example-blocks",
"editorScript": "file:./build/index.js",
"editorStyle": "file:./build/index.css",
"style": "file:./build/style-index.css"
}
34 changes: 34 additions & 0 deletions src/plugins/example-blocks/blocks/hello-world/src/edit.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
/**
* Retrieves the translation of text.
*
* @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/
*/
import { __ } from '@wordpress/i18n';

/**
* React hook that is used to mark the block wrapper element.
* It provides all the necessary props like the class name.
*
* @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops
*/
import { useBlockProps } from '@wordpress/block-editor';

/**
* Lets webpack process CSS, SASS or SCSS files referenced in JavaScript files.
* Those files can contain any CSS code that gets applied to the editor.
*
* @see https://www.npmjs.com/package/@wordpress/scripts#using-css
*/
import './editor.scss';

/**
* The edit function describes the structure of your block in the context of the
* editor. This represents what the editor will render when the block is used.
*
* @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#edit
*
* @return {WPElement} Element to render.
*/
export default function Edit() {
return <p {...useBlockProps()}>{__('Hello World!', 'example-blocks')}</p>;
}
10 changes: 10 additions & 0 deletions src/plugins/example-blocks/blocks/hello-world/src/editor.scss
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
/**
* The following styles get applied inside the editor only.
*
* Replace them with your own styles or remove the file completely.
*/

.wp-block-example-blocks-hello-world {

/* insert custom styles here */
}
39 changes: 39 additions & 0 deletions src/plugins/example-blocks/blocks/hello-world/src/index.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
/**
* Registers a new block provided a unique name and an object defining its behavior.
*
* @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
*/
import { registerBlockType } from '@wordpress/blocks';

/**
* Lets webpack process CSS, SASS or SCSS files referenced in JavaScript files.
* All files containing `style` keyword are bundled together. The code used
* gets applied both to the front of your site and to the editor.
*
* @see https://www.npmjs.com/package/@wordpress/scripts#using-css
*/
import './style.scss';

/**
* Internal dependencies
*/
import Edit from './edit';
import save from './save';
import metadata from '../block.json';

/**
* Every block starts by registering a new block type definition.
*
* @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
*/
registerBlockType(metadata.name, {
/**
* @see ./edit.js
*/
edit: Edit,

/**
* @see ./save.js
*/
save,
});
20 changes: 20 additions & 0 deletions src/plugins/example-blocks/blocks/hello-world/src/save.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
/**
* React hook that is used to mark the block wrapper element.
* It provides all the necessary props like the class name.
*
* @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops
*/
import { useBlockProps } from '@wordpress/block-editor';

/**
* The save function defines the way in which the different attributes should
* be combined into the final markup, which is then serialized by the block
* editor into `post_content`.
*
* @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#save
*
* @return {WPElement} Element to render.
*/
export default function save() {
return <p {...useBlockProps.save()}>{'Hello World!'}</p>;
}
12 changes: 12 additions & 0 deletions src/plugins/example-blocks/blocks/hello-world/src/style.scss
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
/**
* The following styles get applied both on the front of your site
* and in the editor.
*
* Replace them with your own styles or remove the file completely.
*/

.wp-block-example-blocks-hello-world {
background-color: #21759b;
color: #fff;
padding: 2px;
}
17 changes: 17 additions & 0 deletions src/plugins/example-blocks/blocks/reverse-string/block.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "example-blocks/reverse-string",
"version": "0.1.0",
"title": "Reverse String",
"category": "example-custom-blocks",
"icon": "smiley",
"description": "Prints a user-entered string in reverse order.",
"supports": {
"html": false
},
"textdomain": "example-blocks",
"editorScript": "file:./build/index.js",
"editorStyle": "file:./build/index.css",
"style": "file:./build/style-index.css"
}
39 changes: 39 additions & 0 deletions src/plugins/example-blocks/blocks/reverse-string/src/edit.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
import { TextControl } from '@wordpress/components';

/**
* React hook that is used to mark the block wrapper element.
* It provides all the necessary props like the class name.
*
* @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops
*/
import { useBlockProps } from '@wordpress/block-editor';

/**
* Lets webpack process CSS, SASS or SCSS files referenced in JavaScript files.
* Those files can contain any CSS code that gets applied to the editor.
*
* @see https://www.npmjs.com/package/@wordpress/scripts#using-css
*/
import './editor.scss';

/**
* The edit function describes the structure of your block in the context of the
* editor. This represents what the editor will render when the block is used.
*
* @param {Object} props
* @param {Object} props.attributes
* @param {Function} props.setAttributes
* @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#edit
*
* @return {WPElement} Element to render.
*/
export default function Edit({ attributes, setAttributes }) {
const { textToReverse } = attributes;
const updateTextToReverse = (newText) => setAttributes({ textToReverse: newText });

return (
<div {...useBlockProps()}>
<TextControl label="Text to Reverse" value={textToReverse} onChange={updateTextToReverse} />
</div>
);
}
13 changes: 13 additions & 0 deletions src/plugins/example-blocks/blocks/reverse-string/src/editor.scss
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
/**
* The following styles get applied inside the editor only.
*
* Replace them with your own styles or remove the file completely.
*/

.wp-block-example-blocks-reverse-string {
padding: 1em;
box-sizing: border-box;
border: none;
border-radius: 2px;
box-shadow: inset 0 0 0 1px #1e1e1e;
}
Loading
Loading