Gutenberg Block

Overview

Visual Portfolio provides native Gutenberg blocks that integrate seamlessly with the WordPress block editor. There are two main blocks available:

Visual Portfolio Block - The main block for creating galleries and portfolio layouts
Saved Layout Block - A block for displaying pre-configured saved layouts

Visual Portfolio Block

The main Visual Portfolio block (visual-portfolio/block) allows you to create custom galleries and portfolio layouts directly in the block editor.

Block Registration

The block is registered in /home/daytona/workspace/source/gutenberg/block/index.php:27-34:

public function register_block() {
    register_block_type_from_metadata(
        visual_portfolio()->plugin_path . 'gutenberg/block',
        array(
            'render_callback' => array( $this, 'block_render' ),
            'attributes'      => Visual_Portfolio_Gutenberg::get_block_attributes(),
        )
    );
}

Block Configuration

The block supports the following features as defined in block.json:

{
  "name": "visual-portfolio/block",
  "category": "media",
  "title": "Visual Portfolio",
  "keywords": ["gallery", "images", "posts", "portfolio", "vpf"],
  "supports": {
    "anchor": true,
    "className": false,
    "html": false,
    "align": ["wide", "full"]
  }
}

Dynamic Attributes

Block attributes are dynamically generated from registered controls in /home/daytona/workspace/source/classes/class-gutenberg.php:35-141. The system automatically converts control types to appropriate block attribute types:

checkbox/toggle → boolean
number/range → number
select (multiple) → array
gallery → array of objects
elements_selector → object

Block Context

The block can receive context from parent blocks using the usesContext property:

"usesContext": [
  "vp/queryType",
  "vp/baseQuery",
  "vp/postsQuery",
  "vp/imagesQuery"
]

Context is automatically transformed to attributes in /home/daytona/workspace/source/classes/class-gutenberg.php:145-178.

Loop Block

The Loop block (visual-portfolio/loop) is a container block that provides a complete portfolio structure with filters, gallery, and pagination.

Block Structure

The Loop block uses a predefined template with nested blocks:

[
  ['visual-portfolio/filter-by-category', {}, [
    ['visual-portfolio/filter-by-category-item', {
      text: 'All',
      isAll: true,
      url: '#',
      isActive: true
    }]
  ]],
  ['visual-portfolio/block', { setup_wizard: 'false' }],
  ['visual-portfolio/pagination', {}, [
    ['visual-portfolio/pagination-previous'],
    ['visual-portfolio/pagination-numbers'],
    ['visual-portfolio/pagination-next']
  ]]
]

Content Source Controls

The Loop block displays specific control categories in the sidebar:

content-source
content-source-general
content-source-images
content-source-post-based
content-source-social-stream
custom_css

Max Pages Calculation

The Loop block automatically calculates the maximum number of pages via REST API when attributes change:

const response = await apiFetch({
  path: '/visual-portfolio/v1/get-max-pages/',
  method: 'POST',
  data: requestData
});

Saved Layout Block

The Saved Layout block (visual-portfolio/saved-layout) displays pre-configured portfolio layouts saved as custom post types.

Block Attributes

'id' => array(
    'type' => 'string',
),
'align' => array(
    'type' => 'string',
),
'className' => array(
    'type' => 'string',
),
'anchor' => array(
    'type' => 'string',
)

WPML Support

The block includes WPML integration for translated layouts:

$attributes['id'] = apply_filters(
    'wpml_object_id',
    $attributes['id'],
    'vp_lists',
    true
);

Block Editor Integration

JavaScript Assets

Block editor assets are enqueued in /home/daytona/workspace/source/classes/class-gutenberg.php:183-234:

Visual_Portfolio_Assets::enqueue_script(
    'visual-portfolio-gutenberg',
    'build/gutenberg/index',
    array( 'masonry' )
);

Global Variables

The following variables are available to JavaScript via VPGutenbergVariables:

nonce - AJAX nonce for security
plugin_version - Current plugin version
plugin_url - Plugin URL path
attributes - All registered block attributes
controls - All registered controls
controls_categories - Control categories for organization

Block Render Callback

The block render callback in /home/daytona/workspace/source/gutenberg/block/index.php:45-71 processes attributes and outputs the portfolio:

public function block_render( $attributes, $content, $block ) {
    // Merge default attributes
    $attributes = array_merge(
        array(
            'anchor'    => '',
            'align'     => '',
            'className' => '',
        ),
        $attributes
    );

    // Transform context to attributes
    $context_attributes = Visual_Portfolio_Gutenberg::transform_context_to_attributes(
        $block->context
    );

    // Merge and render
    $merged_attributes = array_merge( $attributes, $context_attributes );
    return Visual_Portfolio_Get::get( $merged_attributes );
}

Using Blocks Programmatically

Creating a Block in Code

$block_content = do_blocks('<!-- wp:visual-portfolio/block {
  "layout": "grid",
  "items-gap": 15
} /-->');

Registering Custom Block Attributes

You can filter block attributes before registration:

add_filter( 'vpf_register_block_attributes', function( $attributes, $controls ) {
    $attributes['custom_field'] = array(
        'type' => 'string',
        'default' => 'value'
    );
    return $attributes;
}, 10, 2 );

Best Practices

Use Context - When building nested block structures, use block context to pass data from parent to child blocks
Validate Attributes - Always validate and sanitize attributes in render callbacks
Cache Control Data - The plugin caches control data for performance - clear cache when modifying controls
Preview Mode - Use the preview_image_example attribute to show layout previews in the block inserter
Anchor Support - Enable anchor support for deep linking to specific portfolios on a page

Visual Editor - Learn about the visual layout editor
Shortcodes - Alternative method for displaying portfolios
Settings Overview - Complete guide to all settings

Get Started

Core Concepts

Building Galleries

Layouts & Styles

Content Sources

Features

Integrations

Overview

Visual Portfolio Block

Block Registration

Block Configuration

Dynamic Attributes

Block Context

Loop Block

Block Structure

Content Source Controls

Max Pages Calculation

Saved Layout Block

Block Attributes

WPML Support

Block Editor Integration

JavaScript Assets

Global Variables

Block Render Callback

Using Blocks Programmatically

Creating a Block in Code

Registering Custom Block Attributes

Best Practices

​Overview

​Visual Portfolio Block

​Block Registration

​Block Configuration

​Dynamic Attributes

​Block Context

​Loop Block

​Block Structure

​Content Source Controls

​Max Pages Calculation

​Saved Layout Block

​Block Attributes

​WPML Support

​Block Editor Integration

​JavaScript Assets

​Global Variables

​Block Render Callback

​Using Blocks Programmatically

​Creating a Block in Code

​Registering Custom Block Attributes

​Best Practices

​Related

Overview

Visual Portfolio Block

Block Registration

Block Configuration

Dynamic Attributes

Block Context

Loop Block

Block Structure

Content Source Controls

Max Pages Calculation

Saved Layout Block

Block Attributes

WPML Support

Block Editor Integration

JavaScript Assets

Global Variables

Block Render Callback

Using Blocks Programmatically

Creating a Block in Code

Registering Custom Block Attributes

Best Practices

Related