MediaAndFocalPicker (experimental)
Reason why
The MediaAndFocalPicker is a combined media picker for images/videos and
their focal points. In contrast to the existing T2 MediaReplacer and the
WordPress core MediaReplaceFlow components, it's intended for use in the
InspectorControls panel.
It looks similar to the native post FeaturedImage picker, but is for use with
blocks, not with posts. There is currently no media picker available
for blocks in the InspectorControls in WordPress or T2.
Implementation
The MediaAndFocalPicker is a wrapper built around the core MediaReplaceFlow and
FocalPointPicker components. The property names are based on MediaReplaceFlow
but with some changes in order to prevent naming conflicts and to apply to Dekode
naming conventions.
The core FocalPointPicker is used to display the selected media
and to modify the focal point. Since selecting media and their focal
point are frequently used together, it makes sense to provide both features
in one place, not separated in BlockControls and InspectorControls.
WordPress component documentation:
Usage
You can use the MediaAndFocalPicker as an easy-to-use alternative to a
combination of the T2 MediaReplacer (or the core MediaReplaceFlow)
and the FocalPointPicker components in your blocks. It will save you some
work and give authors a better user experience.
Basic example
import { __experimentalMediaAndFocalPicker as MediaAndFocalPicker, MediaPreviewer } from '@t2/editor';
import { InspectorControls, useBlockProps } from '@wordpress/block-editor';
import { PanelBody } from '@wordpress/components';
export default function Edit({ attributes, setAttributes }) {
const { mediaId, mediaUrl, focalPoint } = attributes;
const blockProps = useBlockProps({ className: 'block-class-name' });
return (
<>
<InspectorControls>
<PanelBody title="Media settings">
<MediaAndFocalPicker
mediaUrl={mediaUrl}
mediaId={mediaId}
focalPoint={focalPoint}
onFocalChange={(value) => setAttributes({ focalPoint: value })}
onSelectMedia={(media) => {
setAttributes({ mediaId: media.id, mediaUrl: media.url, mediaType: media.type });
}}
onRemoveMedia={() => {
setAttributes({ mediaId: undefined, mediaUrl: undefined, mediaType: undefined });
}}
/>
</PanelBody>
</InspectorControls>
<div {...blockProps}>
<MediaPreviewer mediaId={mediaId} />
</div>
</>
);
}Screenshots of the above example
Without selected media
With selected media
With selected media and open dropdown
Callbacks and editor UI
The visual appearance of the MediaAndFocalPicker in the editor UI depends
primarily on the callbacks you set in the component. As an example, the
Remove button is only displayed when the onRemoveMedia callback is set.
Optional callbacks changing the visual appearance in the editor UI:
onToggleFeatured: Displays a menu item for using the post featured media.onSelectURL: Displays a menu item for setting/changing a media url.onResetMedia: Displays aResetmenu item when a media is selected.onRemoveMedia: Displays aRemovebutton when a media is selected.
Required callbacks (no visual change):
onFocalChange: Called when the focal point changes.onSelectMedia: Called when the selected image changes.
Enhanced example
import { __experimentalMediaAndFocalPicker as MediaAndFocalPicker, MediaPreviewer, useFeaturedMedia } from '@t2/editor';
import { InspectorControls, useBlockProps } from '@wordpress/block-editor';
import { PanelBody } from '@wordpress/components';
export default function Edit({ attributes, setAttributes }) {
const { mediaId, mediaUrl, focalPoint, useFeatured } = attributes;
const blockProps = useBlockProps({ className: 'block-class-name' });
const updateMedia = (media) => {
setAttributes({ mediaId: media.id, mediaUrl: media.url, mediaType: media.type });
};
/* This hook is required for post featured media support */
useFeaturedMedia(useFeatured, mediaId, updateMedia);
return (
<>
<InspectorControls>
<PanelBody title="Media settings">
<MediaAndFocalPicker
mediaUrl={mediaUrl}
mediaId={mediaId}
focalPoint={focalPoint}
useFeatured={useFeatured}
onFocalChange={(value) => setAttributes({ focalPoint: value })}
onToggleFeatured={(value) => setAttributes({ useFeatured: value })}
onSelectMedia={updateMedia}
onSelectURL={updateMedia}
onRemoveMedia={updateMedia}
onResetMedia={updateMedia}
/>
</PanelBody>
</InspectorControls>
<div {...blockProps}>
{/* The MediaPreviewer doesn't support media urls, only ids */}
<MediaPreviewer mediaId={mediaId} />
</div>
</>
);
}Screenshot of the above example with open dropdown
The basic media object
Depending on the selected action, WordPress provides two different media objects
with different properties for media url and type. In order to prevent this
ambiguity, the below callbacks return a normalized basic media object in addition
to the media object natively provided by WordPress (if available).
export type BasicMediaProps = {
id: number | undefined; /* The media attachment id */
url: string | undefined; /* The media url */
type: string | undefined; /* The media type: image, video, etc. */
};
onSelectMedia = (basic: BasicMediaProps, media: any) => void;
onSelectURL = (basic: BasicMediaProps) => void;
onRemoveMedia = (basic: BasicMediaProps) => void;
onResetMedia = (basic: BasicMediaProps) => void;It may seem strange to provide a basic media object when a media is removed,
but it allows you to use one single callback for updating your media properties
in your block. When a media is removed, all three properties are undefined.
With onSelectURL, only the url property has a value, the other two are
undefined,
const updateMedia = (media) => {
setAttributes({ mediaId: media.id, mediaUrl: media.url, mediaType: media.type });
};The useFeaturedMedia hook
Components in the InspectorControl are not updated when they are hidden,
which is always the case when an author changes the post featured media.
In order to update the media properties without delay when the post featured
media changes, you must to add the useFeaturedMedia hook in your block.
This is only required when the onToggleFeatured callback is set in the
MediaAndFocalPicker. You can see how to use this hook in the
"Enhanced example" above.
Component properties
The property names are based on the MediaReplaceFlow component, but with
some changes in order to prevent naming conflicts and to align with Dekode
naming conventions.
export type MediaAndFocalPickerProps = {
/** The media url. Required but can be undefined. */
mediaUrl: string | undefined;
/** The media (attachment) id. Required but can be undefined. */
mediaId: number | undefined;
/** An array of media ids for use with media galleries */
mediaIds?: number[];
/** Comma delimited list of MIME types accepted for upload. */
accept?: string;
/** A list of media types allowed to replace the current media: image, video, etc. */
allowedTypes?: string[];
/** The text of the add/replace button when no media is selected. */
addMediaText?: string;
/** The text of the add/replace button when media is selected. */
replaceMediaText?: string;
/** The text of the remove button (only displayed when media is selected). */
removeMediaText?: string;
/** The media focal point, defaults to { x: 0.5, y: 0.5 }. */
focalPoint: FocalPoint;
/** Whether to use the post featured media (true) or not (false). */
useFeatured?: boolean;
/** Callback when the focal point changes (required). */
onFocalChange: (focalPoint: FocalPoint) => void;
/** Callback when useFeatured changes. Displays the use featured media menu item when set. */
onToggleFeatured?: (useFeatured: boolean) => void;
/** Callback when media is replaced (required). */
onSelectMedia: (basic: BasicMediaProps, media: any) => void;
/** Callback when media is replaced with an URL. Displays the select urlmenu item when set. */
onSelectURL?: (basic: BasicMediaProps) => void;
/** Callback when media is removed. Displays the remove button when set. */
onRemoveMedia?: (basic: BasicMediaProps) => void;
/** Callback when media is removed. Displays the reset menu item when set. */
onResetMedia?: (basic: BasicMediaProps) => void;
/** Callback when an upload error happens (currently not supported). */
onError?: (error: string) => void;
/** Creates a media replace notice. */
createNotice?: () => void;
/** Removes a media replace notice. */
removeNotice?: () => void;
/** Whether to allow multiple media selections (true) or not (false). */
multiple?: boolean;
/** Whether to add media to a gallery (true) or not (false). */
addToGallery?: boolean;
/** Whether to add media to a gallery (true) or not (false). */
popoverProps?: DropdownProps['popoverProps'];
/** Allows customizing of the add/replace dropdown (not yet supported by WP). */
renderToggle?: (toggleButtonProps: any) => ReactNode;
/** Allows customizing of the remove button, i.e. to add an icon. */
removeButtonProps?: ButtonProps;
/** Allows customizing of the FocalPointPicker. */
focalPointProps?: FocalPointPickerProps;
/** Adds additional menu items to the add/replace dropdown . */
children?: ReactNode;
};