Media utilities

Hooks and utility helper functions for use with media.

link getAspectRatio

/**
 * Gets the normalized aspect ratio string for the given width and height.
 *
 * This function will return the smallest possible integer values that
 * accurately represent the given width to height ratio,
 *
 * @param width  The width of the media.
 * @param height The height of the media.
 *
 * @returns A string representing the CSS aspect-ratio value, i.e. "16/9".
 */
function getAspectRatio(width: number, height: number): string;

link getBasicMedia

/**
 * Converts a WordPress media object into a normalized object with just basic properties.
 *
 * It also extracts the mime and media type from the url (file extension) if they are missing
 * or incorrect.
 *
 * @param media A WordPress media object.
 */
function getBasicMedia(media: any = {}): BasicMediaProps;

link getFocalPosition

/**
 * Transforms a focal point into an object-position style.
 *
 * @param focalPoint The focal point with x and y coordinates ranging from 0 to 1.
 *
 * @returns A string representing the CSS object-position value, or undefined if the focal point is invalid.
 */
function getFocalPosition(focalPoint: FocalPoint | undefined): string | undefined;

link getMediaType

/**
 * Extracts the media type (e.g., 'image', 'video', 'audio') from a MIME type string.
 *
 * @param mimeType The MIME type string.
 *
 * @returns The media type as a string, or undefined if not recognized.
 */
function getMediaType(mimeType: string | undefined): string | undefined;

link getMimeType

/**
 * Determines the MIME type for a given URL or file name.
 *
 * @param url The URL or file name to analyze.
 *
 * @returns The MIME type as a string, or undefined if not recognized.
 */
function getMimeType(url: string | undefined): string | undefined;

link pickMediaSize

/**
 * Selects a specific media size from a WordPress media object and converts it into a normalized BasicMedia object.
 *
 * If the requested size does not exist, it falls back to the full size.
 *
 * @param media A WordPress media object.
 * @param mediaSize The desired media size (e.g., 'thumbnail', 'medium', 'large', 'full').
 */
function pickMediaSize(media: any, mediaSize: string | undefined): BasicMediaProps;

link useBasicMedia

/**
 * A React hook that retrieves media information from the WordPress media library.
 *
 * The function immediately returns a BasicMedia object based on the given arguments.
 * If a valid mediaId is provided, it then fetches the full media details from the
 * WordPress media library and updates both the BasicMedia and the native WordPress
 * media object accordingly.
 *
 * @param mediaId The ID of the media item in the WordPress media library.
 * @param mediaUrl The URL of the media item (used if mediaId is not provided).
 * @param mediaType The type of the media item (used if mediaId is not provided).
 * @param mediaSize The desired media size (e.g., 'thumbnail', 'medium', 'large', 'full').
 * 
 * @returns { basic: BasicMediaProps; native: unknown }
 */
function useBasicMedia( mediaId: number | undefined, mediaUrl?: string, mediaType?: string, mediaSize?: string);

link Example usage

import { __experimentalMediaSuiteViewer as MediaSuiteViewer, useBasicMedia } from '@t2/editor';
import { useBlockProps } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';

export default function Edit({ attributes, setAttributes }) {
    // Block attributes for storing media data (use you own names as you please).
    const { mediaId, mediaUrl, mediaType } = attributes;
    const blockProps = useBlockProps({ className: 't2-test-block' });

    // Immediately returns a BasicMedia object based on the given arguments.
    // Then resolves the mediaId and returns the normalised BasicMedia and the native WordPress media object.
    const { basic, native } = useBasicMedia(mediaId, mediaUrl, mediaType);

    return (
        <div {...blockProps}>
            <p>{__('This is a simple test block with an image.', 't2')}</p>
            <MediaSuiteViewer mediaId={basic.id} mediaUrl={basic.url} mediaType={basic.type} />
        </div>
    );
}

link useFeaturedMedia

/**
 * A React hook that retrieves the post featured media and updates media settings.
 *
 * This hook retrieves the current post featured media object and invokes a callback
 * to update media settings whenever the featured media changes, provided that
 * the `useFeatured` flag is set to true.
 *
 * @param useFeatured - A boolean indicating whether to use the post's featured media.
 * @param mediaId - The current media ID to compare against the featured media ID.
 * @param updateMedia - A callback function to update media settings when the featured media changes.
 *
 * @returns The current post featured media object or undefined if no featured media is set.
 */
function useFeaturedMedia(useFeatured?: boolean, mediaId?: number, updateMedia?: UpdateMediaHandler): unknown;

link Example usage

import { useFeaturedMedia } from '@t2/editor';
import { useBlockProps } from '@wordpress/block-editor';

export default function Edit({ attributes, setAttributes }) {
    const {mediaId, mediaUrl, mediaType, focalPoint, useFeatured} = attributes;
    const blockProps = useBlockProps({className: 't2-test-block'});

    /* Reusable function to update media attributes */
    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);
}

link Reference

link BasicMedia properties

WordPress provides two different media objects with different property names for url, media type, mime type and alt text (and other properties as well). And sometimes the media type is just file instead of the actual media type.

In order to prevent this ambiguity, all media components use the normalized BasicMedia object internally and externally (i.e. in callbacks). Note that the five properties always exist, but they can all be undefined.

export type BasicMediaProps = {
    /* The media attachment id */
    id: number | undefined;

    /* The media url */
    url: string | undefined;

    /* The media type: image, video, etc. */
    type: string | undefined;

    /* The media mime type: image/jpeg, video/mp4, etc. */
    mime: string | undefined;

    /* The media alt text */
    alt: string | undefined;
};

link Media handler signatures

All callbacks for changing media (select, upload, remove) provide the normalized BasicMedia object as the first argument. onSelectMedia also adds the native media object in the second argument.

/** Update basic media function signatures */
export type BasicMediaHandler = (basic: BasicMediaProps) => void;
export type UpdateMediaHandler = (basic: BasicMediaProps, native: unknown) => void;