Adding Custom Fields to Vue Gutenberg Blocks

Supercharging Your Vue Gutenberg Blocks: Adding Custom Fields with Ease

Gutenberg, WordPress’s revolutionary block editor, has opened up a whole new world of possibilities for creating dynamic and engaging content. But what if you want to go beyond the standard blocks and create truly custom experiences? This is where Vue.js, with its powerful component-based architecture, shines.

This blog will guide you through the process of adding custom fields to your Vue Gutenberg blocks, allowing you to build blocks that are tailored to your specific needs and offer users a rich and intuitive editing experience.

Understanding the Power of Custom Fields

Imagine building a block that displays a product, allowing you to customize the displayed attributes like price, image, and description. Or perhaps you want a block that fetches data from an external API, where the user can input their API key. Custom fields enable you to achieve these and much more.

Here’s how custom fields empower your Vue Gutenberg blocks:

• Enhanced Flexibility: Users can tailor the content within the block to match their specific requirements.
• Dynamic Content: You can leverage user input to dynamically fetch and display content, making your blocks truly interactive.
• Increased Functionality: You can add advanced features, like image uploads, color pickers, or dropdown menus, by incorporating custom fields.

Building Blocks with Custom Fields: A Step-by-Step Guide

Let’s dive into a practical example. We’ll create a "Featured Product" block that allows users to input a product title, description, image URL, and price.

1. Setting Up Your Project:

First, create a new Vue.js project:

vue create my-gutenberg-block

Select the default preset for this example.

2. Creating Your Gutenberg Block Component:

Inside your src/components folder, create a file named FeaturedProductBlock.vue:

<template>
  <div class="wp-block-featured-product">
    <h2>{{ title }}</h2>
    <img :src="image" alt="Product Image" />
    <p>{{ description }}</p>
    <p>Price: ${{ price }}</p>
  </div>
</template>

<script>
export default {
  name: 'FeaturedProductBlock',
  props: {
    attributes: {
      type: Object,
      required: true
    }
  },
  computed: {
    title() {
      return this.attributes.title;
    },
    description() {
      return this.attributes.description;
    },
    image() {
      return this.attributes.image;
    },
    price() {
      return this.attributes.price;
    }
  }
};
</script>

<style scoped>
.wp-block-featured-product {
  border: 1px solid #ccc;
  padding: 20px;
  margin-bottom: 20px;
}
</style>

In this component:

• We use props to receive the attributes object, which will hold the custom field values.
• We utilize computed properties to access the specific values from the attributes object.

3. Registering Your Block in src/main.js:

import Vue from 'vue';
import App from './App.vue';
import FeaturedProductBlock from './components/FeaturedProductBlock.vue';

Vue.config.productionTip = false;

// Register the block component globally
Vue.component('FeaturedProductBlock', FeaturedProductBlock);

new Vue({
  render: h => h(App)
}).$mount('#app');

4. Defining the Block’s Attributes:

In your src/blocks.js file (create it if it doesn’t exist), add the following code:

import FeaturedProductBlock from './components/FeaturedProductBlock.vue';

export default {
  name: 'featured-product-block', // Unique block name
  title: 'Featured Product', // Block title
  description: 'Displays a featured product with title, description, image, and price.', // Block description
  icon: 'cart', // Block icon (use WordPress icon names)
  category: 'common', // Block category
  keywords: ['product', 'featured', 'shop'], // Block keywords

  // Define attributes for the block
  attributes: {
    title: {
      type: 'string',
      default: 'Featured Product'
    },
    description: {
      type: 'string',
      default: 'Lorem ipsum dolor sit amet...'
    },
    image: {
      type: 'string',
      default: 'https://via.placeholder.com/300x200.png'
    },
    price: {
      type: 'number',
      default: 19.99
    }
  },

  // Register the block component
  edit: FeaturedProductBlock
};

This defines the featured-product-block with its name, title, description, icon, category, keywords, and most importantly, the attributes object. We’ve added fields for title, description, image, and price, specifying their data types and default values.

5. Rendering the Block in WordPress:

To render your block in WordPress, you’ll need to:

• Create a plugin: Create a new plugin directory (e.g., my-gutenberg-block) and a plugin.php file within it.
• Include the block: Within your plugin.php file, use the register_block_type function to register the block:

<?php
/**
 * Plugin Name: My Gutenberg Block
 * Description: A plugin that demonstrates adding a custom Gutenberg block.
 * Version: 1.0.0
 * Author: Your Name
 */

// Register the block type
function my_gutenberg_block_register_block() {
    // Include your Vue.js build file
    wp_enqueue_script(
        'my-gutenberg-block-script',
        plugins_url( 'dist/main.js', __FILE__ ),
        array( 'wp-element', 'wp-i18n' ),
        '1.0.0',
        true
    );
    // Register the block
    register_block_type( 'my-gutenberg-block/featured-product-block', array(
        'editor_script' => 'my-gutenberg-block-script',
        'render_callback' => 'my_gutenberg_block_render',
    ) );
}
add_action( 'init', 'my_gutenberg_block_register_block' );

// Callback function for rendering the block
function my_gutenberg_block_render( $attributes ) {
    return '<div class="wp-block-featured-product">' .
        '<h2>' . esc_html( $attributes['title'] ) . '</h2>' .
        '<img src="' . esc_url( $attributes['image'] ) . '" alt="Product Image" />' .
        '<p>' . esc_html( $attributes['description'] ) . '</p>' .
        '<p>Price: $' . esc_html( $attributes['price'] ) . '</p>' .
    '</div>';
}

• Build your Vue.js code: Ensure you have a package.json file in your block directory and run:

npm install && npm run build

This will create the dist/main.js file, which you’ll reference in your plugin.php file.

6. Building Custom Field Components:

Now, let’s add custom field components to allow users to input the values. Create a new folder called components/fields and create the following files:

• TextField.vue:

<template>
  <div class="gutenberg-field">
    <label :for="fieldId">{{ label }}</label>
    <input
      :type="type"
      :id="fieldId"
      :value="value"
      @input="updateValue"
    />
  </div>
</template>

<script>
export default {
  name: 'TextField',
  props: {
    fieldId: {
      type: String,
      required: true
    },
    label: {
      type: String,
      required: true
    },
    type: {
      type: String,
      default: 'text'
    },
    value: {
      type: [String, Number],
      required: true
    }
  },
  methods: {
    updateValue(event) {
      this.$emit('update:value', event.target.value);
    }
  }
};
</script>

<style scoped>
.gutenberg-field {
  margin-bottom: 10px;
}
</style>

• ImageUploadField.vue:

<template>
  <div class="gutenberg-field">
    <label :for="fieldId">{{ label }}</label>
    <input
      type="text"
      :id="fieldId"
      :value="value"
      @input="updateValue"
    />
    <button @click="openMediaLibrary">Choose Image</button>
  </div>
</template>

<script>
export default {
  name: 'ImageUploadField',
  props: {
    fieldId: {
      type: String,
      required: true
    },
    label: {
      type: String,
      required: true
    },
    value: {
      type: String,
      required: true
    }
  },
  methods: {
    updateValue(event) {
      this.$emit('update:value', event.target.value);
    },
    openMediaLibrary() {
      // Implement logic to open WordPress Media Library
      // and update the field value with the selected image URL
    }
  }
};
</script>

7. Integrating Custom Fields in the Block Component:

Finally, update your FeaturedProductBlock.vue component to use these custom field components:

<template>
  <div class="wp-block-featured-product">
    <TextField 
      fieldId="title"
      label="Title"
      v-model="attributes.title"
    />
    <TextField 
      fieldId="description"
      label="Description"
      v-model="attributes.description"
    />
    <ImageUploadField 
      fieldId="image"
      label="Image"
      v-model="attributes.image"
    />
    <TextField 
      fieldId="price"
      label="Price"
      type="number"
      v-model="attributes.price"
    />
    <h2>{{ title }}</h2>
    <img :src="image" alt="Product Image" />
    <p>{{ description }}</p>
    <p>Price: ${{ price }}</p>
  </div>
</template>

<script>
import TextField from './fields/TextField.vue';
import ImageUploadField from './fields/ImageUploadField.vue';

export default {
  name: 'FeaturedProductBlock',
  components: {
    TextField,
    ImageUploadField
  },
  props: {
    attributes: {
      type: Object,
      required: true
    }
  },
  computed: {
    title() {
      return this.attributes.title;
    },
    description() {
      return this.attributes.description;
    },
    image() {
      return this.attributes.image;
    },
    price() {
      return this.attributes.price;
    }
  }
};
</script>

We’ve now created a block that allows users to edit its content through custom input fields!

8. Implementing Media Library Interaction:

To enable the ImageUploadField component to open the WordPress Media Library, you’ll need to leverage the wp.media API within your Vue.js code. Here’s a basic example:

// In ImageUploadField.vue
methods: {
  // ...
  openMediaLibrary() {
    const frame = wp.media({
      title: 'Select Image',
      button: {
        text: 'Use Image'
      },
      multiple: false // Allow only one image to be selected
    });

    frame.on('select', () => {
      const attachment = frame.state().get('selection').first().toJSON();
      this.$emit('update:value', attachment.url);
    });

    frame.open();
  }
  // ...
}

This code uses the wp.media API to create a media frame, allowing the user to select an image. When an image is selected, the select event handler extracts the image URL and emits it to the parent component, updating the value prop of the ImageUploadField.

Expanding Your Block’s Functionality

The example above demonstrates the core principles of adding custom fields to Vue Gutenberg blocks. You can easily adapt this approach to create more complex blocks with various types of fields:

• Dropdown Menus: Use a select element with options to create dropdown menus for choosing from predefined values.
• Color Pickers: Utilize libraries like wp-color-picker to enable color selection within your blocks.
• Date Pickers: Use the wp-datepicker library for providing intuitive date selection functionality.
• Repeater Fields: Allow users to add and remove multiple instances of a field group for creating lists or collections of data.

Best Practices for Custom Field Management

Here are some essential best practices to keep in mind:

• Data Validation: Implement validation for custom fields to ensure data integrity and prevent errors.
• User Experience: Design user-friendly interfaces for your custom fields, making it easy for users to understand and interact with the block.
• Performance Optimization: Optimize your code to ensure your block loads quickly and performs efficiently.
• Accessibility: Ensure your blocks and custom fields are accessible to all users, regardless of their abilities.

Conclusion

By adding custom fields to your Vue Gutenberg blocks, you can unlock a whole new level of customization and functionality. Users can easily tailor the content within your blocks to match their specific needs, making your blocks even more engaging and valuable. This combination of Vue.js’s reactivity and WordPress’s Gutenberg editor empowers you to create dynamic and user-friendly content experiences within your WordPress websites. So go ahead, embrace the power of custom fields and build truly amazing Gutenberg blocks!