Guide to Using the Media Modal in the Admin UI

Updated at 1781012829000

The media modal is a shared window for selecting and managing media in the admin interface. Instead of rebuilding upload, search, preview, detail, and selection logic on every page, a page can simply open the modal with JavaScript and register callbacks to receive the selected media.

The modal supports:

Searching media by keyword, group, type, status, creation date, and time range.
Displaying media as icons or as a list.
Loading more items with pagination.
Uploading new files or adding media from a URL.
Viewing details, previewing images, playing audio/video, and opening files.
Updating metadata such as group name, alt text, title, caption, description, URL, and public status.
Selecting one media item or multiple media items.
Replacing files, deleting, restoring, and reducing file size when permitted.

Opening The Media Modal

In pages using the default admin layout, the media modal is usually already included. To select media, call:

ezyadmin
    .showMediaModal("avatarImage")
    .onMediaSelected(function(media) {
        console.log(media.id);
        console.log(ezyadmin.extractMediaUrl(media));
        ezyadmin.closeMediaModal();
    });

The argument passed to showMediaModal(command) identifies the selection context. For example:

ezyadmin.showMediaModal("avatarImage");
ezyadmin.showMediaModal("coverImage");
ezyadmin.showMediaModal("settingImage");

This command string lets the system keep separate callbacks for different use cases.

Selecting One Media Item

The single-selection flow has three steps:

The page calls showMediaModal.
The user clicks a media item to open its details.
The user clicks the Select button in the detail view.

Example:

ezyadmin.selectAvatarImage = function() {
    ezyadmin
        .showMediaModal("avatarImage")
        .onMediaSelected(function(media) {
            $('#avatarImage')
                .attr('src', ezyadmin.extractMediaUrl(media))
                .removeClass('d-none');

            ezyadmin.closeMediaModal();
        });
};

The selected media object usually contains fields such as id, name, url, type, originalName, mimeType, size, width, height, publicMedia, createdAt, and updatedAt.

Use:

ezyadmin.extractMediaUrl(media)

instead of manually building the URL.

Restricting Media Type

Use onMediaShow to validate the media after its detail view is loaded. For example, to allow images only:

ezyadmin
    .showMediaModal("imageOnly")
    .onMediaShow(function(media) {
        if (media.type !== 'IMAGE') {
            $('#selectMediaButton').attr('disabled', true);
        }
    })
    .onMediaSelected(function(media) {
        $('#thumbnail').attr('src', ezyadmin.extractMediaUrl(media));
        ezyadmin.closeMediaModal();
    });

onMediaShow runs when a media detail is displayed, not when the media list first opens.

Selecting Multiple Media Items

The modal provides checkboxes for each media item. Once at least one item is checked, the multi-select button becomes visible.

Example:

ezyadmin
    .showMediaModal("gallery")
    .onMultipleMediaSelected(function(medias) {
        medias.forEach(function(media) {
            console.log(media.id, ezyadmin.extractMediaUrl(media));
        });

        ezyadmin.closeMediaModal();
    });

If onMultipleMediaSelected is not registered, the modal falls back to calling the single-selection callback for each selected media item.

Handling Modal Close

You can register a callback for when the media modal is closed:

ezyadmin
    .showMediaModal("settingMedia")
    .onMediaModelHide(function() {
        $('#setting-modal').modal('show');
    });

This is useful when one modal temporarily opens the media modal, then needs to reopen after selection or cancellation.

Workflow

sequenceDiagram
    participant Page as Current page
    participant Modal as Media modal
    participant API as Media API
    participant User as User

    Page->>Modal: ezyadmin.showMediaModal(command)
    Modal->>API: GET /api/v1/media/list or /api/v1/me/media/list
    API-->>Modal: Media list
    User->>Modal: Filter, load more, upload, or select media
    Modal->>API: GET media details
    API-->>Modal: Media details
    User->>Modal: Click Select
    Modal->>Page: onMediaSelected(media)
    Page->>Page: Update UI or call business API
    Page->>Modal: ezyadmin.closeMediaModal()

Search And Display

The modal supports these filters:

Keyword.
Group name prefix.
Type.
Status.
Specific date.
Time range.
Sort order.
Limit per request.
Display type: ICONS or LIST.

When showMediaModal is called, filters are reset, the list is reloaded, and the modal opens in icon view.

Uploading New Media

Users can click Add new to upload a file or add media from a URL.

Upload a file:

ezyadmin.addNewMedia(file, notPublicMedia);

Add from URL:

ezyadmin.addNewMediaFromUrl({
    type: 'IMAGE',
    originalName: 'banner.jpg',
    url: 'https://example.com/banner.jpg'
}, false);

Newly added media is inserted at the top of the current list. The modal also supports drag-and-drop upload into the media list area.

Permissions And API Fallback

The modal automatically chooses the correct API based on the current account’s permissions:

If the account can access the shared media library, it uses /api/v1/media/list.
Otherwise, it uses /api/v1/me/media/list and only returns media owned by the current account.

The same fallback applies to details, update, delete, replace, restore, and reduce-file-size operations.

Notes

Call ezyadmin.closeMediaModal() after handling the selected media, because the selection callback does not always close the modal automatically.

If only images, videos, or audio files are allowed, check media.type in onMediaShow or onMediaSelected.

Always prefer ezyadmin.extractMediaUrl(media) when displaying or storing the media URL.

If the main media page does not need the selection modal embedded inside itself, set includeMediaModal = false.

Complete Example

ezyadmin.selectSettingImage = function() {
    $('#setting-modal').modal('hide');

    ezyadmin
        .showMediaModal("settingImage")
        .onMediaShow(function(media) {
            $('#selectMediaButton')
                .attr('disabled', media.type !== 'IMAGE');
        })
        .onMediaSelected(function(media) {
            $('#settingImageInput').val(ezyadmin.extractMediaUrl(media));
            ezyadmin.closeMediaModal();
            $('#setting-modal').modal('show');
        })
        .onMediaModelHide(function() {
            $('#setting-modal').modal('show');
        });
};

Conclusion

The media modal is a reusable component for selecting, searching, and managing media in the admin UI. The simplest integration only needs showMediaModal(...).onMediaSelected(...), while advanced cases can use onMediaShow, onMultipleMediaSelected, and onMediaModelHide. This keeps features such as avatar selection, cover image selection, setting images, and galleries consistent without rewriting upload and media-selection logic.

Previous Page Hotkeys in EzyPlatform Next Page Guide to Using Cron Expressions Supported by EzyPlatform