Attributes System

How block attributes are defined, shared, and merged — from the common Advanced-tab attributes to per-block settings.

Every Styble block ends up with a single flat array of attributes registered with WordPress. That array is built from two sources: common attributes shared by all blocks, and per-block attributes unique to one block. This page explains both and how they are merged.

The two sources

Source	File	Scope
Common attributes	blocks/Attributes/CommonAttributes.php	Shared by every block (the Advanced tab, visibility, section preferences, etc.)
Per-block attributes	blocks/Types/<Block_Name>/attributes.php	Specific to one block

Common attributes

CommonAttributes (blocks/Attributes/CommonAttributes.php, namespace ShapedPlugin\StyblePro\Attributes) defines the attributes that power the shared Advanced tab — responsive visibility, section width/background/border/shadow/spacing, custom CSS classes and IDs, and more. It exposes a static get() method that AbstractBlock calls, and groups the definitions into helper methods such as get_required() and get_section_preferences().

Attribute definitions are produced by helpers in Att_Utils (ShapedPlugin\StyblePro\Includes\Utils\Att_Utils) so the shapes stay consistent:

public static function get_required(): array {
	return array(
		'uniqueId'           => Att_Utils::string( '' ),
		'align'              => Att_Utils::string( 'wide' ),
		'hideOnDesktop'      => Att_Utils::boolean(),
		'hideOnTablet'       => Att_Utils::boolean(),
		'hideOnMobile'       => Att_Utils::boolean(),
		'additionalCssClass' => Att_Utils::string(),
		'additionalId'       => Att_Utils::string(),
	);
}

Att_Utils provides shaped builders such as string(), boolean(), single_responsive(), responsive_spacing(), border(), box_shadow(), and background() — each returning a WordPress-style attribute definition (type + default).

Skipping common attributes

Child blocks (rendered only inside a parent) often do not need the full Advanced tab. Setting protected $skip_common_attributes = true; in the block class makes load_attributes() start from an empty array instead of CommonAttributes::get().

Per-block attributes

Each block declares its own attributes in blocks/Types/<Block_Name>/attributes.php, which simply returns an array:

<?php
defined( 'ABSPATH' ) || exit;

return array(
	'headingText' => array(
		'type'    => 'string',
		'default' => 'Hello',
	),
	'columns'     => array(
		'type'    => 'number',
		'default' => 3,
	),
);

These keys must match the attribute names used in the block's JavaScript (attributes in index.js / accessed in edit.jsx).

The merge flow

Merging happens in AbstractBlock::load_attributes() (blocks/Includes/AbstractBlock.php), called from the constructor before registration:

protected function load_attributes() {
	if ( ! $this->skip_common_attributes ) {
		$this->attributes = CommonAttributes::get();
	} else {
		$this->attributes = array();
	}

	$attribute_file = SP_STYBLE_PATH . 'Types/' .
		self::to_studly_case( $this->block_name ) . '/attributes.php';

	if ( file_exists( $attribute_file ) ) {
		$attributes = require $attribute_file;
		if ( is_array( $attributes ) ) {
			$this->attributes = array_merge( $this->attributes, $attributes );
		}
	}

	$this->attributes = apply_filters(
		'styble_block_attributes',
		$this->attributes,
		$this->block_name
	);
}

Step by step:

1. Start with common attributes — CommonAttributes::get(), unless skip_common_attributes is true.
2. Resolve the per-block file — SP_STYBLE_PATH . 'Types/<Studly_Block_Name>/attributes.php'. The slug is converted to StudlyCase via to_studly_case().
3. Merge — array_merge() layers per-block attributes on top, so a block can override a common default by reusing the same key.
4. Filter — the final array passes through the styble_block_attributes filter, letting third parties add or change attributes per block.

The merged array is then handed to register_block_type() through get_args().

Extending attributes via filter

To add an attribute to a specific block without editing core files, hook styble_block_attributes:

add_filter( 'styble_block_attributes', function ( $attributes, $block_name ) {
	if ( 'my-custom-block' === $block_name ) {
		$attributes['myExtraField'] = array(
			'type'    => 'string',
			'default' => '',
		);
	}
	return $attributes;
}, 10, 2 );

There is also a runtime filter, styble_pro_attributes, applied to attributes at render time inside render_block_callback(). See Hooks & Internationalization.

Related

• Creating a Custom Block — where attributes.php fits in.
• Dynamic CSS Generation — how attributes turn into CSS.
• The user-facing Advanced tab is documented per block, e.g. on the Container page.