Flickr Justified Block WP Registry grade B. Medium-severity findings · 1 findingWP RegistryMedium-severity findings · 1 findingOpen the reportB

A powerful WordPress Gutenberg block that creates beautiful justified photo galleries from Flickr albums, individual photos, or direct image URLs. Features intelligent caching, automatic pagination, and built-in lightbox.

Last updated: 2026-04-05

---

✨ Features

🎨 Justified Layout Engine

• True justified galleries with optimal row heights calculated from image aspect ratios
• Responsive breakpoints - control columns per screen size (mobile, tablet, desktop)
• Auto or fixed row heights with viewport-aware sizing

🚀 Smart Caching System

• Multi-level caching - request-level + WordPress transients
• Configurable TTL with cache versioning
• Negative caching for private photos
• Rate-limit detection with automatic backoff

⚡ Background Cache Warming

• WP-Cron integration pre-fetches Flickr data before visitors arrive
• Configurable batch sizes and fast/slow modes
• Prevents API rate limits during high traffic

📄 Automatic Album Pagination

• Large albums load page-by-page as visitors scroll
• IntersectionObserver triggers seamless loading
• Scroll position preservation for smooth UX

🔄 Image Fallback Recovery

• Detects expired Flickr URLs (404s)
• Automatically fetches fresh URLs via AJAX
• No broken images - ever

📊 Sort by Views

• Display most popular photos first using cached Flickr view counts
• Cache-aware sorting prevents API timeouts on large galleries

📐 EXIF Rotation Support

• Handles rotated photos correctly throughout entire pipeline
• Layout calculations, CSS transforms, and lightbox display

🖼️ Built-in PhotoSwipe Lightbox

• Full-featured lightbox with Flickr attribution links
• No extra plugins needed
• Responsive and touch-friendly

🌐 Mixed Content Support

• Combine Flickr photos, albums, and direct image URLs in the same gallery
• Supports: JPG, PNG, WebP, AVIF, GIF, SVG

---

📋 Requirements

• WordPress: 6.7 or higher
• PHP: 8.1 or higher
• Flickr API Key: Required for Flickr URLs (free from Flickr App Garden)

---

🔧 Installation

From WordPress Admin

1. Go to Plugins → Add New
2. Search for "Flickr Justified Block"
3. Click Install Now
4. Click Activate
5. (Optional) Go to Settings → Flickr Justified and add your API key

Manual Installation

1. Download the latest release from GitHub Releases
2. Upload the flickr-justified-block folder to /wp-content/plugins/
3. Activate the plugin through the Plugins menu
4. (Optional) Configure your API key at Settings → Flickr Justified

From Source

git clone https://github.com/radialmonster/flickr-justified-block.git
cd flickr-justified-block
# Copy to your WordPress plugins directory
cp -r . /path/to/wordpress/wp-content/plugins/flickr-justified-block/

---

🚀 Quick Start

1. Add the Block

In the WordPress block editor:

1. Click the + button to add a new block
2. Search for "Flickr Justified"
3. Add the block to your post or page

2. Add URLs

In the block sidebar, paste URLs (one per line):

https://www.flickr.com/photos/username/albums/72157605291217770
https://www.flickr.com/photos/username/123456789
https://example.com/direct-image.jpg

Supported URL formats:

• Flickr photo: https://flickr.com/photos/username/123456789
• Flickr album: https://flickr.com/photos/username/albums/72157605291217770
• Flickr set: https://flickr.com/photos/username/sets/72157605291217770
• Direct image: https://example.com/image.jpg

3. Customize Settings

Adjust settings in the block sidebar:

• Row Height: Auto or fixed pixel height
• Gap: Space between images (px)
• Image Size: Quality/size from Flickr
• Responsive Columns: Columns per breakpoint
• Sort Order: Input order or by views
• Max Photos: Limit number of photos (0 = unlimited)

4. Publish

Click Publish or Update - your gallery is live!

---

⚙️ Configuration

Global Settings

Go to Settings → Flickr Justified to configure:

API Key

• Flickr API Key: Get one from Flickr App Garden
• Keys are encrypted when stored in the database

Cache Settings

• Cache Duration: How long to cache Flickr data (default: 7 days)
• Background Cache Warmer: Enable/disable automatic cache warming
• Batch Size: Number of URLs to warm per WP-Cron run

Responsive Breakpoints

• Customize screen width breakpoints for responsive behavior
• Default columns per breakpoint

Error Handling

• Show Placeholder: Display placeholder for unavailable photos
• Show Error: Display error message
• Show Nothing: Skip unavailable photos silently

---

🖥️ WP-CLI Commands

Manage caches via WP-CLI:

Warm Cache

# Warm cache for all galleries
wp flickr-justified warm-cache

# Force rebuild all caches
wp flickr-justified warm-cache --rebuild

Clear Cache

# Clear all plugin caches
wp flickr-justified clear-cache

---

🎨 Customization

CSS Custom Properties

The plugin uses CSS custom properties for easy styling:

.flickr-justified-grid {
    --gap: 12px; /* Gap between images */
}

Custom Styling

Target the plugin classes:

/* Gallery container */
.flickr-justified-grid {
    margin: 2rem 0;
}

/* Individual photo cards */
.flickr-justified-card {
    border-radius: 8px;
    overflow: hidden;
}

/* Images */
.flickr-justified-card img {
    transition: transform 0.3s ease;
}

.flickr-justified-card img:hover {
    transform: scale(1.05);
}

---

🏗️ Architecture

File Structure

flickr-justified-block/
├── flickr-justified-block.php    # Main plugin file & REST routes
├── block.json                     # Block configuration (source of truth for attributes)
├── includes/
│   ├── admin-settings.php         # Admin settings page
│   ├── cache.php                  # Cache management & size definitions
│   ├── cache-warmers.php          # Background cache warming (WP-Cron)
│   ├── cli-warmers.php            # WP-CLI commands
│   ├── render.php                 # Main render orchestration
│   ├── render-ajax.php            # AJAX / async loading handlers
│   ├── render-helpers.php         # Helper functions (URL parsing, size selection)
│   ├── render-html.php            # HTML generation for galleries
│   └── render-photo-fetcher.php   # Flickr API integration
├── src/                           # ES module source (built via wp-scripts)
│   ├── view.module.js             # Frontend entry point
│   ├── frontend/
│   │   ├── config.js              # Server config reader (Script Module data)
│   │   ├── layout.js              # Justified layout engine
│   │   ├── lazy-loading.js        # Infinite scroll for albums
│   │   ├── photoswipe-init.js     # Built-in lightbox
│   │   ├── image-fallback.js      # Auto-recovery for expired URLs
│   │   └── async-loader.js        # Async gallery loading
│   └── editor/                    # Block editor UI
│       ├── index.js               # Editor entry point
│       └── components/            # Inspector controls, image cards, drag-drop
├── build/                         # Compiled JS bundles (auto-generated)
└── assets/
    ├── css/style.css              # Frontend styles
    └── lib/photoswipe/            # PhotoSwipe lightbox library

Caching Strategy

1. Request-level cache: In-memory cache for single request
2. WordPress transients: Persistent cache across requests
3. Local database: wp_fjb_photo_meta table for photo metadata
4. Background warmer: Pre-fetches data via WP-Cron

Performance Optimizations

• Lazy loading: Images load only when visible
• Container query fallback: Basic grid layout via CSS before JS initializes
• Srcset/Sizes: Responsive image loading
• Rate limiting: Protects against Flickr API limits
• Pagination: Large albums load incrementally

---

🐛 Troubleshooting

Gallery Not Loading

Check API Key:

wp option get flickr_justified_api_key

Check cache:

wp flickr-justified clear-cache
wp flickr-justified warm-cache

Rate Limited by Flickr

The plugin automatically handles rate limits, but if you're consistently rate limited:

1. Reduce Batch Size in settings
2. Enable Slow Mode for cache warmer
3. Increase Cache Duration to reduce API calls

Images Not Displaying

Clear and rebuild cache:

wp flickr-justified warm-cache --rebuild

Check photo permissions: Ensure photos are public on Flickr

504 Gateway Timeout

For very large albums (1000+ photos):

1. Ensure cache is warmed: wp flickr-justified warm-cache
2. Increase PHP max_execution_time
3. Enable object caching (Redis/Memcached)

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/radialmonster/flickr-justified-block.git
cd flickr-justified-block

# Install dependencies and build
npm install
npm run build

# For development with auto-rebuild on changes
npm start

# Copy to your WordPress plugins directory or symlink

Enable debugging in wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

---

📄 License

This plugin is licensed under the GPLv2 or later.

Copyright (C) 2024-2026 RadialMonster

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

• PhotoSwipe: photoswipe.com
• Flickr API: flickr.com/services/api

---

📞 Support

• Issues: GitHub Issues
• Documentation: Wiki
• WordPress.org: Plugin Page

---

🌟 Show Your Support

If you find this plugin helpful, please:

• ⭐ Star the repository
• 🐛 Report bugs or suggest features
• 💬 Share with others
• ☕ Buy me a coffee

---

Made with ❤️ by RadialMonster