CF Block Usage Viewer

A WordPress plugin for discovering and managing Block usage across your site. View block statistics, identify orphaned blocks, and export block usage data.

Description

Block Usage Viewer helps you understand and manage how blocks are used across your WordPress site. It adds a "Blocks Used" column to your Posts and Pages admin tables, provides a dashboard widget with site-wide statistics, and enables CSV export of block usage data. Perfect for content audits, site migrations, and managing block-based content at scale.

Installation

Download the Plugin

⚠️ Important: When downloading from the Releases page, use the plugin ZIP file (e.g., cf-block-usage-viewer-v1.5.2.zip), NOT the "Source code" links. The source code archives are incomplete and will not work.

Via WordPress Admin

Download the plugin ZIP file from the latest release
Go to Plugins > Add New in WordPress admin
Click Upload Plugin and choose the ZIP file
Click Install Now and then Activate

Manual Installation

Download the plugin ZIP file from the latest release
Extract the ZIP file
Upload the cf-block-usage-viewer folder to /wp-content/plugins/
Activate the plugin through the Plugins menu in WordPress

Features

Core Features (All Versions)

Visual Block Display: Shows all blocks used on each post/page with a count
Filterable Dropdown: Filter posts/pages by specific blocks
Sortable Column: Sort by block count (ascending/descending)
Nested Block Support: Detects blocks inside other blocks (columns, groups, etc.)
Performance Optimized: Caches block data for efficiency
Translation Ready: Full internationalization support
Fully Extensible: 40+ filters and action hooks for developers

Enhanced Discovery (v1.5+)

Dashboard Widget

Site-Wide Statistics: View total posts, blocks, and averages across your entire site
Published vs Non-Published Analytics: Separate counts for published and draft content
Dynamic Post Type Display: Automatically shows which post types are being analyzed (Posts, Pages, etc.)
Top 10 Blocks: Discover your most-used blocks with usage percentages and quick filter links
Orphaned Blocks Detection: Identify blocks from deactivated plugins that remain in your content
Quick Action Links: Jump directly to filtered views or all posts/pages
Smart Caching: One-hour cache with automatic invalidation on content changes
Screen Options Compatible: Hide/show widget via WordPress Screen Options
Accessible Design: WCAG 2.1 Level AA compliant with full screen reader support

CSV Export Capability

Two Export Modes:
- Export Filtered View: Export only posts matching your current block filter
- Export All: Export all posts regardless of filters
Comprehensive Data: Includes Post ID, Title, Author, Date, Status, URL, Block Count, and Blocks Used
Memory Efficient: Streams large datasets without memory issues
Excel Compatible: UTF-8 BOM ensures special characters display correctly in Excel
Accessible Controls: ARIA live regions and screen reader announcements
Loading States: Visual feedback with spinner animation during export
Error Handling: Clear error messages with user-friendly admin notices

Requirements

WordPress 5.0 or higher
PHP 7.4 or higher

Usage

Viewing Block Usage (Admin Columns)

Once activated, navigate to Posts > All Posts or Pages > All Pages. You'll see a new "Blocks Used" column showing:

The total number of unique block types on each post/page
A list of block names used

Filtering by Block

Use the "All Blocks" dropdown at the top of the Posts or Pages list
Select a specific block type (e.g., "Image", "Paragraph", "Video")
Click Filter to show only posts/pages containing that block

Sorting by Block Count

Click the "Blocks Used" column header to sort:

Ascending: Posts with fewest blocks first (0, 1, 2, 3...)
Descending: Posts with most blocks first (...13, 8, 3, 1, 0)

Dashboard Widget (v1.5+)

Navigate to Dashboard in WordPress admin. The "Block Usage Viewer" widget displays:

Site-Wide Statistics:

Total content items analyzed (with post type breakdown)
Total block instances (all blocks including duplicates)
Block instances in published vs non-published content
Average blocks per post

Top 10 Blocks:

Most frequently used blocks with usage counts
Percentage of total blocks for each type
Quick filter links to find posts using each block

Orphaned Blocks (when detected):

Blocks found in content but no longer registered
Likely from deactivated or removed plugins
Helps identify content that needs updating

Quick Links:

Jump to Posts or Pages with one click

Note: The widget shows "Analyzing: Posts, Pages" (or other post types if extended via filter) and explains that block instances include duplicates.

CSV Export (v1.5+)

Navigate to Posts > All Posts or Pages > All Pages. You'll see two export buttons:

Export Filtered View:

Apply a block filter using the dropdown (optional)
Click Export Filtered View
Downloads CSV of all matching posts (not just current page)

Export All:

Click Export All
Downloads CSV of all posts regardless of filters

CSV includes:

Post ID
Title
Author name
Publish date
Post status (publish, draft, pending, etc.)
Permalink URL
Block count (number of block instances)
Blocks used (comma-separated list of unique block types)

File format: block-usage-{mode}-{post_type}-{date}.csv (e.g., block-usage-all-post-2026-01-05.csv)

Opening in Excel:

Files include UTF-8 BOM for proper character encoding
Special characters (quotes, commas, unicode) are properly escaped
Open directly in Excel, Google Sheets, or any CSV editor

Translation

The plugin is fully translation-ready using the cf-block-usage-viewer text domain.

Creating a Translation

Copy the .pot template file to cf-block-usage-viewer-{locale}.po
- For French: cf-block-usage-viewer-fr_FR.po
- For Spanish: cf-block-usage-viewer-es_ES.po
- For German: cf-block-usage-viewer-de_DE.po
Translate using tools like:
- Poedit (desktop app)
- Loco Translate (WordPress plugin)
- Any standard PO editor
Save both the .po and compiled .mo files in the plugin's /languages/ directory

Extensibility for Developers

Block Usage Viewer is built with extensibility in mind, providing 40+ filters and action hooks for customization.

Quick Examples

Add Custom Post Types:

add_filter('cf_buv_supported_post_types', function($post_types) {
    $post_types[] = 'product';
    $post_types[] = 'portfolio';
    return $post_types;
});

Customize Dashboard Widget Post Types:

add_filter('cf_buv_dashboard_stats_post_types', function($post_types) {
    $post_types[] = 'product';
    return $post_types;
});

Exclude Blocks from Filter:

add_filter('cf_buv_excluded_blocks', function($excluded, $post_type) {
    $excluded[] = 'core/spacer';
    $excluded[] = 'core/separator';
    return $excluded;
}, 10, 2);

Customize Block Name Display:

add_filter('cf_buv_format_block_name', function($formatted, $original) {
    if (strpos($original, 'acf/') === 0) {
        return 'ACF: ' . $formatted;
    }
    return $formatted;
}, 10, 2);

Change Cache Duration:

add_filter('cf_buv_cache_duration', function($duration, $post_type) {
    if ($post_type === 'product') {
        return 5 * MINUTE_IN_SECONDS; // 5 minutes for products
    }
    return $duration;
}, 10, 2);

Customize CSV Export Filename:

add_filter('cf_buv_export_filename', function($filename, $mode, $post_type) {
    $site_name = sanitize_title(get_bloginfo('name'));
    return "{$site_name}-blocks-{$mode}-{$post_type}.csv";
}, 10, 3);

Add Custom Data to CSV Export:

add_filter('cf_buv_export_csv_row', function($row_data, $post, $mode) {
    // Add custom field to export
    $row_data['custom_field'] = get_post_meta($post->ID, 'my_custom_field', true);
    return $row_data;
}, 10, 3);

add_filter('cf_buv_export_csv_headers', function($headers) {
    $headers[] = 'Custom Field';
    return $headers;
});

Control Dashboard Widget Visibility:

add_filter('cf_buv_dashboard_widget_capability', function($capability) {
    return 'manage_options'; // Only administrators
});

Track Export Events:

add_action('cf_buv_after_export', function($count, $mode, $post_type) {
    error_log("User exported {$count} {$post_type} posts in {$mode} mode");
}, 10, 3);

Complete Documentation

For complete documentation of all available filters and actions, please refer to the plugin documentation included in the download.

Available hook categories:

Post Type Support (3 hooks)
Column Customization (6 hooks)
Block Name Formatting (4 hooks)
Cache Control (2 hooks)
Dashboard Widget (11 hooks)
CSV Export (16 hooks)
REST API (2 hooks)
Styling (2 hooks)
And more!

Frequently Asked Questions

Does this work with custom post types?

Yes! The plugin is fully extensible. You can add custom post types using the cf_buv_supported_post_types filter (see examples above).

Does it detect blocks inside reusable blocks?

Yes! The plugin recursively checks for nested blocks, including blocks inside columns, groups, and other container blocks.

What about Classic Editor pages?

Pages using the Classic Editor (no blocks) will show a dash (—) in the Blocks Used column and count as 0 blocks when sorting.

Does it work with third-party blocks (ACF, Kadence, etc.)?

Yes! The plugin detects all registered blocks regardless of source, including core blocks, theme blocks, and third-party plugin blocks.

Can I customize how blocks are displayed?

Absolutely! The plugin provides 40+ filters and action hooks for customization. You can:

Customize block name formatting
Exclude specific blocks from the filter dropdown
Modify the column HTML output
Change cache duration
Customize CSS styling
Control dashboard widget visibility
Customize export data and filenames
And much more!

See the code examples above and the documentation included with the plugin for all available customization options.

Can I export block usage data?

Yes! Version 1.5+ includes CSV export with two modes:

Export Filtered View: Export only posts matching your current block filter
Export All: Export all posts regardless of filters

Exports include comprehensive metadata: Post ID, Title, Author, Date, Status, URL, Block Count, and Blocks Used.

What are "orphaned blocks"?

Orphaned blocks are blocks that appear in your content but are no longer registered in WordPress. This typically happens when:

A plugin providing custom blocks is deactivated or deleted
A theme with custom blocks is switched
Block names change during plugin updates

The dashboard widget detects these blocks and alerts you so you can update affected content.

Why do the dashboard and export show different counts than the admin column?

The admin column shows unique block types per post (better for quick scanning), while the dashboard and export count all block instances including duplicates (more accurate totals).

Example: A post with "paragraph, paragraph, heading" shows:

Admin column: 2 (unique types)
Dashboard/Export: 3 (total instances)

This is intentional to serve different use cases.

Can I hide the dashboard widget?

Yes! Use WordPress Screen Options (top right of dashboard) to hide/show the widget. Developers can also control visibility by capability using the cf_buv_dashboard_widget_capability filter.

How do I clear the cache?

The plugin automatically clears caches when content is saved or deleted. To manually clear all caches, run this SQL query:

DELETE FROM wp_options WHERE option_name LIKE '%cf_buv%';

Or use a caching plugin's "Clear All Caches" feature.

Changelog

1.5.2 (2026-01-27)

Documentation & Release Process Update

Improved public release documentation
Enhanced installation instructions with clear warnings about source code downloads
Automated public release mirroring from development repository

1.5.1 (2026-01-07)

Hotfix Release

The vendor directory is now properly included in the release build, ensuring all dependencies are present
Improved plugin folder naming: Plugin folder now includes cf- prefix for consistency and easier identification

1.5.0 (2026-01-05)

Enhanced Discovery Release

New Features:

Dashboard widget with site-wide block usage statistics
Top 10 blocks display with usage percentages and quick filter links
Orphaned blocks detection for identifying blocks from deactivated plugins
CSV export capability with two modes (filtered view and all posts)
REST API endpoint for secure export data retrieval
Dynamic post type display in dashboard widget
Published vs non-published content analytics

Improvements:

Refactored to PSR-4 autoloading structure
Separated concerns into modular classes (Plugin, DashboardWidget, ExportHandler)
Improved block counting methodology with instance tracking
Enhanced accessibility (WCAG 2.1 Level AA compliant)
Added 27 new filters and action hooks (40+ total)
Comprehensive PHPDoc documentation
Memory-efficient CSV streaming for large datasets

Developer Features:

New REST API: POST /wp-json/cf-buv/v1/export
Extensible export formats via filters
Dashboard widget customization hooks
Export event tracking actions
Cache duration controls per feature

Bug Fixes:

Fixed block counting discrepancy between dashboard and export
Corrected method visibility for cross-class access
Improved cache invalidation timing

1.0.5

Performance optimizations
Cache improvements
Translation updates

1.0.0

Initial release
Block usage display in admin columns
Filter by block type
Sort by block count
Full translation support

Support

For bug reports and feature requests, please use the GitHub Issues page.

License

This plugin is licensed under the GPL v2 or later.

Copyright (C) 2025 Crowd Favorite

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

Credits

Developed by Crowd Favorite

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
README.md		README.md

crowdfavorite/cf-block-usage

Folders and files

Latest commit

History

Repository files navigation