Developer Diaries: Anatomy of a Photo Block

Screenshot of a Photo Block With Crop Toolbar Options
Screenshot of a Photo Block With Crop Toolbar Options

I’ve been wanting to create a photo block for a while now. I’ve tried to fall in love with an image block from a block suite or even come to love the core block, but I’m too often frustrated that an image block takes too many clicks to use, or is just simply not flexible enough to accommodate non-standard layouts (such as a card layout).

A few months ago, I pulled the switch and asked my friend Ajay Dsouza if he’d like to help me develop a new (and free) photo block for the masses.

He asked how my photo block would be different. I told him my aim was to be able to have the block added and ready to publish in just 4 clicks. The block had to be easy to use but extremely customizable in all the right ways.

The result so far has been a wonderful learning experience, which I hope to share in this developer diary. I’d love to say the block is finished. It is not. But it’s mostly there.

It began with a wireframe

I’m a very visual person. I still like to do mockups and wireframes even though I don’t consider myself a designer. With other image blocks, you’re presented with several buttons, each doing a separate thing. This is shown below.

Core Image Block With Options
Core Image Block With Options

Rather than use this interface, I wanted a “large” drop zone for dragging and dropping photos in my photo block. I also wanted a way for a user to upload via file, via URL, use the regular media library, or choose an image from data parameters (if the block is used in a query loop).

The resulting wireframe and implementation are a marriage of all these ideas.

Initial Interface of the Photo Block Showing a Dropzone and Shortcut Buttons
Initial Interface of the Photo Block Showing a Dropzone and Shortcut Buttons

The goal of the wireframe was to present all of the various “modes” a user could be in without reliance on sidebar options. A user can upload a photo five different ways but still not be overwhelmed with options.

I began with the work on this initial screen first in order to get a proof-of-concept going.

Initial Screen in the Block Editor
Initial Screen in the Block Editor

For the icon set, I used Lucide.dev throughout the photo block and its settings.

I used FilePond for the uploader

The first UI element I tackled was the dropzone area, which I concluded needed to be a React uploader component.

The component had to be able to accept photos that are dropped, and also launch an upload dialogue if clicked on (dual purpose). I should also be able to modify the component and have a real-time preview.

I found all of this in FilePond. It is a neat React uploader and is extremely easy to use and style. It has an MIT license, so I deemed it okay to include in the photo block project.

As a side note, I did try to use the “amazing” Pintura editor in this project (for cropping and image editing), but the author doesn’t sell a license that can be used in a distributed product (I inquired how much, and it was prohibitively expensive).

The result is a neat upload experience if adding via drag and drop, via URL, or by launching the upload dialogue.

Animated Gif of file upload feature in the photo block

Uploading via URL

Uploading via URL had to be just as intuitive, so I decided to change the toolbar when the URL button is clicked, but still allow the dropzone for dragging or launching the upload dialogue instead if needed.

URL Input Field in the Toolbar
URL Input Field in the Toolbar

Here’s the URL input in action.

Uploading via URL
Uploading via URL

Uploading via the media library

Clicking on the Media Library button would bring up the media library modal and end up on the same edit screen as the other options.

Inserting a File from the Media Library
Inserting a File from the Media Library

The Edit screen

This brings us to the image edit screen. This is the screen a user should land on after selecting or uploading a photo.

Edit Photo Screen with Caption Option
Edit Photo Screen with Caption Option

The edit screen is designed to prominently display an edit/crop and replace option (two common tasks) and add some shortcuts for the alt-text and link settings in the toolbar.

I wanted as much as possible to be configured on the block itself and also in its toolbar. Not all users have the sidebar options open, so the toolbar and block interactions are paramount.

There’s a prominent “Replace” button, which takes you back to the initial image select screen. If you happen to click Replace and don’t mean to, there is a Back button, which will take you back to the last edited image (and back to the edit screen).

Replacing an Image Presents a Back Button
Replacing an Image Presents a Back Button

In addition to the Crop and Replace buttons, there are two popovers in the toolbar for accessibility and link settings.

Here’s the wireframe for the accessibility popover. It features inputs for editing the image title and alternate text.

Accessibility Popover Wireframe
Accessibility Popover Wireframe

Here’s how the accessibility popover ended up looking. I decided to group both the image title and alt text in one section, as the title can be used for accessibility reasons too.

Accessibility options popover with title and alt text options
Accessibility options popover with title and alt text options

The link options were a bit more complicated. The original wireframe I came up with has a custom URL picker. Not included in the wireframe are advanced settings such as an anchor attribute.

Link Settings Wireframe
Link Settings Wireframe

I settled on four buttons, with no link as the default. Clicking on the remaining buttons would bring up specific settings for the selected option.

Link Popover Settings on the Edit Screen
Link Popover Settings on the Edit Screen

Selecting “Full size photo” will reveal a shortcut to the media file and provide some lightbox settings.

Media File Option in the Link Settings
Media File Option in the Link Settings With Lightbox Options

Clicking “The photo’s page” will reveal a shortcut to the attachment page.

Attachment Page Selected in Link Options
Attachment Page Selected in Link Options

Selecting “Custom link” will show a URL input field, which also searches the database for any matching posts if keywords are entered.

Custom Link Option Selected in Link Settings
Custom Link Option Selected in Link Settings
Searching for Posts in the Custom URL Link
Searching for Posts in the Custom URL Link
A Selected Post in the Url Picker
A Selected Post in the URL Picker

All link options (aside from no link) have an advanced section where you can set the link anchor, have it pop up in a new tab, and other advanced link options.

Link Settings Advanced Options
Link Settings Advanced Options

I also have it so that if you do select “Open in new tab”, the REL attribute input will be filled in automatically.

Setting New Tab Fills in the Rel Parameters Automatically
Setting New Tab Fills in the Rel Parameters Automatically

Edit screen sidebar options

Let’s move onto the sidebar options for the Edit screen. The goal is to allow the block to be customizable but not overwhelm the user with unintuitive controls or UX.

Edit Screen Sidebar Options
Edit Screen Sidebar Options

For the sidebar options, I decided on tabs to mimic the direction that WordPress Core is taking with regard to splitting up items into logical sections.

In the main tab, there is an area for Presets, and I added duplicate options for the image title and alt text. I duplicated this functionality from the toolbar in order to make it clear that the title and alt text should ideally be filled out.

This next section looks very close to the way the standard core image block operates with regard to image sizes and dimensions.

Choosing an Image Size in the Sidebar Options
Choosing an Image Size in the Sidebar Options

I deviated from Core here a bit here and included all image sizes that the theme or plugins have registered.

Choose an Image Size
Choose an Image Size

Another notable difference is that the width/height controls are dynamic and maintain their aspect ratios when edited.

Modifying the Image Display Size on the Edit Screen
Modifying the Image Display Size on the Edit Screen

For the image styles, you can adjust the background color, image opacity, adjust the blur, and also add a drop shadow.

Image Styles in the Block Editor
Image Styles in the Block Editor

For CSS styles, I’m using CSSGram to add a CSS filter to the photo in order to change its appearance. I coded it so that hovering over an item will show a preview of what the image would look like with the filter applied.

CSSGram Options in the Sidebar
CSSGram Options in the Sidebar

As far as sidebar dimension options, I had to create several custom controls in order to capture all of the dimension data I needed to style the image. I tried to mimic core styles and behavior as much as possible. I ended up coding two custom dimension controls for the padding, margin, border, and border-radius.

Dimension Control Wireframes for Padding and Border Radius
Dimension Control Wireframes for Padding and Border Radius

Here’s how it ended up coming out. It’s a lot of functionality in a very confined space. Each control can also be adjusted per media breakpoint (mobile, tablet, desktop). You can see the icons for each in the animated gif below.

Dimension Controls in the Sidebar Options
Dimension Controls in the Sidebar Options

For this next section, I borrowed heavily from the way GenerateBlocks’ image block handles container sizing.

The image out of the box is designed to be fluid and not necessarily have any constraints. However, having sizing controls allows you to be much more creative in the way you can display images. For example, if you’re using the block to display author avatars, you can set these values to have a set width and height with positioning via the object fit settings.

Here’s an animated gif of making a circular image.

Making a Circular Image Using Size Settings
Making a Circular Image Using Size Settings

You’re also able to specify min and max height parameters per breakpoint.

Sizing Controls Per Breakpoint
Sizing Controls Per Breakpoint

As far as advanced options go, I’ve included the ability to add CSS classes to the figure and img tag separately for more advanced styling.

Advanced Anchor and CSS Class Options
Advanced Anchor and CSS Class Options

Another feature I borrowed from GenerateBlocks is adding custom data attributes.

Add Custom Data Attributes to the Image
Add Custom Data Attributes to the Image

There is also an option to prevent lazy loading the image, preventing right+click saving, and the ability to show and hide based on a breakpoint.

Additional Advanced Options Including Skipping Lazy Loading
Additional Advanced Options Including Skipping Lazy Loading

The crop screen

Crop Options Screen
Crop Options Screen

For the crop screen, I wanted to use an intuitive cropper and have the cropper behave the same as Photoshop or Affinity Photo.

The toolbar allows you to unlock the crop aspect ratio (for a freeform crop), select an aspect ratio, and also allows you to rotate the image.

Crop Toolbar for the Photo Block
Crop Toolbar for the Photo Block
Photo Block Aspect Ratio Options
Photo Block Aspect Ratio Options

For the “Custom” option for aspect ratio, you can manually add in your aspect ratio.

Enter a Custom Aspect Ratio
Enter a Custom Aspect Ratio

When first visiting the Crop screen, the full-size image loads so that you can crop the original image.

Clicking “Save Changes” will crop the image and save any rotation.

If the crop is not desirable, an “Undo” option shows in the toolbar so that you can revert the crop.

Undo Option in the Toolbar After Cropping
Undo Option in the Toolbar After Cropping

The caption

Add Caption Button on the Photo Block Interface
Add Caption Button on the Photo Block Interface

Being a photography block, the caption is very important for describing the image and giving appropriate credit. For the majority of the image blocks I’ve tried, the caption is an option in the toolbar that could be toggled on or off and seems a bit of an afterthought.

For the photo block, I imagined a fully-featured caption where the caption would be (towards the bottom). This way, adding a caption is more immediate and there’s no need to jump between the interface unless you want to change caption positions.

Adding a Caption on the Edit Screen
Adding a Caption on the Edit Screen

From an architectural perspective, I made the caption its own block. This made for a more configurable caption and opens the door as far as customizations. It also helps cleanly separate the caption functionality from the photo controls.

By default, a user is given a single-line caption. This is what the majority of users will be used to as far as captions go.

Option for Selecting Between Multi-line or Single-line Captions
Option for Selecting Between Multi-line or Single-line Captions

However, if you have a more complex caption, you can switch modes and use blocks to create your caption.

Multi-line Caption Used in the Caption Block
Multi-line Caption Used in the Caption Block

The multi-line caption is actually a collection of blocks. Not wanting to open up the caption wide-open, there is currently a set list of enabled blocks for the caption. I did this so that I could provide some base styles for the included components.

Supported Blocks for the Photo Block Caption
Supported Blocks for the Photo Block Caption

When in multi-line mode, I have provided an option called Smart Styles, which will lay down a base style for all of the supported inner blocks.

Smart Styles for Multi-line Caption
Smart Styles for Multi-line Caption

You’re able to adjust font families for paragraphs and headings. Currently, only common web fonts are available.

Adjust Common Sizes and Colors for a Multi-line Caption
Adjust Common Sizes and Colors for a Multi-line Caption

Four color choices are presented, which will apply to all available inner blocks. You can also increase or decrease the base font size to give the caption more room.

For single-line captions, the options are a bit more straightforward but the caption is less flexible.

Font and Color Settings for Single-line Captions
Font and Color Settings for Single-line Captions

You’re able to adjust the typography, background color, link color, and link hover color.

I coded a custom popover component for the typography section, which can also be adjusted per breakpoint.

Typography Popover for Single-line Captions
Typography Popover for Single-line Captions

Moving onto the Styles tab in the Inspector Controls, you’ll find the same dimension and layout settings as you’ll find in the parent photo block.

Dimension Settings for the Caption Block
Dimension Settings for the Caption Block
Caption Container Sizing
Caption Container Sizing

For the Advanced sidebar options, you can set the CSS class, add data attributes, and display the caption based on breakpoints.

Advanced Caption Options in the Captions Block
Advanced Caption Options in the Captions Block

Caption positioning

Whether in single or multi-line captions, you’ll notice you can adjust the position of the caption.

There are three choices: Top, Overlay, and Bottom.

Caption Positioning in the Captions Block Toolbar
Caption Positioning in the Captions Block Toolbar

By default, the caption is positioned at the bottom of the photo. You can choose “Top” to position the caption above the photo.

Position a Caption Above the Photo
Positioning a Caption Above the Photo

You’re also able to position the caption over the photo, also known as the Overlay position. Selecting this will center the caption over the photo. You’re able to select an overlay type and adjust the caption’s text, positioning, and color settings.

Configuring the Overlay in the Captions Block

The data screen

The photo block has data built-in and allows you to select where the image is coming from. This is so that you can use the photo block within the Query Loop block.

Data Options in the Photo Block
Data Options in the Photo Block

When on the data preview, you can specify a source for the alt text, title text, and link source.

Alt Text Data Source Options
Alt Text Data Source Options
Image Title Data Options
Image Title Data Options
Link Data Options
Link Data Options

You can also set a fallback image and set the image size using the sidebar options.

Set the Photo Size and Fallback Image in Data Mode
Set the Photo Size and Fallback Image in Data Mode

And lastly, you can choose a dynamic caption.

Use Data for a Dynamic Caption
Use Data for a Dynamic Caption

Conclusion

With the block being more or less complete, I still need to code the front end of the block. After that, lots of testing, and then finally, a release on WordPress.org.

If you’re interested in the Photo block, you are welcome to sign-up for my newsletter, where I’ll share updates on the progress.

Ronald Huereca
Ronald Huereca

Ronald Huereca

Ronald has been part of the WordPress community since 2006, starting off writing and eventually diving into WordPress plugin development and writing tutorials and opinionated pieces.

No stranger to controversy and opinionated takes on tough topics, Ronald writes honestly when he covers a topic.

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Ronald Huereca
MediaRon - Ronald Huereca

Ronald created MediaRon in 2011 and has more than fifteen years of releasing free and paid WordPress plugins.

Quick Links

Say Hi