https://github.com/wpgaurav/gt-acf-blocks
GT ACF Blocks simplifies the process of creating custom Gutenberg blocks for WordPress by leveraging the power of Advanced Custom Fields. This plugin allows developers to quickly build rich, customizable blocks with clean, organized code and without having to write complex JavaScript.
https://github.com/wpgaurav/gt-acf-blocks
acf acf-field acf-pro advanced-custom-fields block-editor gutenberg gutenberg-blocks wordpress wordpress-development wordpress-plugin
Last synced: about 2 months ago
JSON representation
GT ACF Blocks simplifies the process of creating custom Gutenberg blocks for WordPress by leveraging the power of Advanced Custom Fields. This plugin allows developers to quickly build rich, customizable blocks with clean, organized code and without having to write complex JavaScript.
- Host: GitHub
- URL: https://github.com/wpgaurav/gt-acf-blocks
- Owner: wpgaurav
- Created: 2025-05-05T02:25:19.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-15T04:32:06.000Z (about 1 year ago)
- Last Synced: 2025-06-25T23:05:13.952Z (12 months ago)
- Topics: acf, acf-field, acf-pro, advanced-custom-fields, block-editor, gutenberg, gutenberg-blocks, wordpress, wordpress-development, wordpress-plugin
- Language: PHP
- Homepage: https://gauravtiwari.org/code/
- Size: 55.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# GT ACF Blocks
A WordPress plugin that provides a framework for easily creating custom Gutenberg blocks using Advanced Custom Fields (ACF).
## Description
GT ACF Blocks simplifies the process of creating custom Gutenberg blocks for WordPress by leveraging the power of Advanced Custom Fields. This plugin allows developers to quickly build rich, customizable blocks with clean, organized code and without having to write complex JavaScript.
## Features
- Simple framework for registering custom Gutenberg blocks
- Seamless integration with Advanced Custom Fields
- Block templates with automatic field rendering
- Block categories for organization
- Block preview support
- CSS and JS enqueuing for individual blocks
- Developer-friendly API
## Requirements
- WordPress 5.8+
- PHP 7.4+
- Advanced Custom Fields PRO 5.8+
## Installation
1. Upload the `gt-acf-blocks` folder to the `/wp-content/plugins/` directory
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Ensure Advanced Custom Fields PRO is installed and activated
## Usage
### Creating a New Block
1. Create a new folder for your block in the `blocks` directory
2. Add your block's PHP, CSS, and JS files
3. Register your block using the plugin's API
### Basic Block Structure
```
blocks/
└── example-block/
├── block.json # Block configuration
├── block.php # Block template
├── block.css # Block styles (optional)
├── block.js # Block scripts (optional)
└── fields.php # ACF field definitions
```
### Registering a Block
Add your block registration to your theme's `functions.php` or a custom plugin:
```php
add_action('acf/init', 'register_my_blocks');
function register_my_blocks() {
if (function_exists('gt_acf_blocks_register_block')) {
gt_acf_blocks_register_block([
'name' => 'example-block',
'title' => 'Example Block',
'description' => 'An example custom block',
'category' => 'formatting',
'keywords' => ['example', 'demo'],
]);
}
}
```
## Adding a New Block
Follow these steps to create and register a new custom block:
1. **Create the block directory structure**:
```
cd /path/to/your/wordpress/wp-content/plugins/gt-acf-blocks/blocks
mkdir my-custom-block
```
2. **Create the necessary files**:
- `block.json` - Block configuration
- `block.php` - Block template
- `fields.php` - ACF field definitions
- `block.css` (optional) - Block styles
- `block.js` (optional) - Block scripts
3. **Configure your block.json**:
```json
{
"name": "my-custom-block",
"title": "My Custom Block",
"description": "A description of what my block does",
"category": "formatting",
"icon": "star-filled",
"keywords": ["custom", "example"],
"acf": {
"mode": "preview",
"renderTemplate": "block.php"
},
"supports": {
"align": true,
"mode": false,
"jsx": false
}
}
```
4. **Define your ACF fields in fields.php**:
```php
'group_my_custom_block',
'title' => 'My Custom Block',
'fields' => [
[
'key' => 'field_my_custom_field',
'label' => 'Custom Field',
'name' => 'custom_field',
'type' => 'text',
],
],
'location' => [
[
[
'param' => 'block',
'operator' => '==',
'value' => 'acf/my-custom-block',
],
],
],
]);
}
```
5. **Create your block template in block.php**:
```php
```
6. **Register your block** in your theme's functions.php or a custom plugin:
```php
add_action('acf/init', 'register_my_blocks');
function register_my_blocks() {
if (function_exists('gt_acf_blocks_register_block')) {
gt_acf_blocks_register_block([
'name' => 'my-custom-block',
]);
}
}
```
7. **Add CSS (optional)** in block.css:
```css
.my-custom-block {
padding: 20px;
background-color: #f8f8f8;
}
.my-custom-block .custom-content {
font-size: 18px;
color: #333;
}
```
8. **Add JavaScript (optional)** in block.js:
```javascript
(function($) {
$(document).ready(function() {
$('.my-custom-block').on('click', function() {
// Your custom JavaScript here
});
});
})(jQuery);
```
9. **Test your block** by adding it to a page or post in the WordPress editor.
## Configuration
Each block can be configured through its `block.json` file with the following options:
- `name`: Internal block name (required)
- `title`: Display title in the editor (required)
- `description`: Block description
- `category`: Block category
- `icon`: Dashicon or SVG to represent the block
- `keywords`: Search terms to help users discover the block
- `supports`: Block support options
- `example`: Preview example configuration
## Development
### Field Definitions
Define your ACF fields in the block's `fields.php` file:
```php
'group_example_block',
'title' => 'Example Block',
'fields' => [
[
'key' => 'field_example_title',
'label' => 'Title',
'name' => 'title',
'type' => 'text',
],
// Add more fields as needed
],
'location' => [
[
[
'param' => 'block',
'operator' => '==',
'value' => 'acf/example-block',
],
],
],
]);
}
```
### Block Template
Create your block's front-end display in the `block.php` file:
```php
```
## Support
For support, feature requests, or bug reports, please submit an issue via the GitHub repository or [send me a message](https://gauravtiwari.org).
## License
This plugin is licensed under the GPL v2 or later.
---
Built with ♥ by [Gaurav Tiwari](https://gauravtiwari.org)