Media¶
Content, Media is the store's image library. The same screen appears as a picker when you insert an image into a page, a block or an email.
It replaces the stock Media Gallery, whose menu entry Nebula removes. Core's gallery is a Knockout UI component and renders an empty page under this theme. The permission is unchanged: this screen uses the same Magento_Cms::media_gallery resource the old one used, so any role that could open the stock gallery can open this one.
The layout¶
The screen has three parts: the folder tree down the left, the images in the middle, and a details panel on the right that opens when you click an image.
Folders¶
| Control | What it does |
|---|---|
| The arrow beside a folder | Shows or hides the folders inside it |
| A folder name | Lists that folder's images |
| The plus button above the tree | Creates a folder inside the one you have open. Type a name and confirm |
| The pencil on a folder | Renames it. Every image inside moves with it |
| The bin on a folder | Deletes the folder and everything in it. Asks first and warns that it cannot be undone |
The pencil and the bin appear on folders inside the library, never on the library root.
Deleting a folder is refused if any image anywhere inside it is still used on a page, a block or a product. The message names up to three of the places. It is the same check, and the same wording, as deleting a single image.
Which folders the library may write into is Magento's own list, read from configuration rather than from a field in the admin. The config path is system/media_storage_configuration/allowed_resources/media_gallery_image_folders. Magento_Cms and Magento_Catalog both contribute to it, which is where wysiwyg and catalog/category come from. The same list decides which images bin/magento nebula:media:index lists, not which folders it walks. That command walks the media tree whatever the list says, and records everything outside an allowed folder as not browsable. It never enters the eleven folders named below, Nebula's own working folders, or Magento's cache of resized product images. It is described on the CLI page.
Eleven folders are refused whatever that list says: downloadable, customer, customer_address, import, export, tmp, captcha, analytics, sitemap, theme_customization and .thumbs. They hold invoices, purchased files and working data rather than pictures.
The tree still shows folders you cannot write into, because an allowed folder can sit inside one. The library root is the obvious case. They are there so you can reach what is inside them, and they are not offered when you choose a destination for a move.
Finding an image¶
Type in the Search images box above the grid to narrow the current folder.
The pager under the grid moves between pages with Prev and Next and shows which page you are on.
A line at the foot of the grid says how long ago the library was indexed, and tells you when the folder you are looking at has just been rescanned.
If the grid says The media index is empty, nobody has built the index yet. Ask whoever runs your store to run bin/magento nebula:media:index once.
Uploading¶
Two ways, and both upload into the folder you have open:
- press Upload and choose files;
- drag files from your computer onto the grid. An overlay reading Drop images to upload appears while you are dragging.
The button reads Uploading… while it runs.
Not every folder you can see accepts an upload
The library root never does, and neither does a folder that only exists as the parent of an allowed one. Nothing greys out beforehand. The upload is sent, Magento refuses it, and the screen shows the refusal. Creating a folder there is refused for the same reason. Open an allowed folder first.
Working with several images at once¶
Tick the box on each image you want. A bar appears showing how many are selected.
| Control | What it does |
|---|---|
| Clear | Drops the selection |
| Move to | Moves the selected images into a folder you choose |
| Delete selected | Deletes them one at a time. Asks first |
Move to is all or nothing. If any image in the selection cannot safely be moved, none of them move and the screen says why. That is deliberate: moving an image breaks every page that points at it, and nothing else would tell you it had happened.
You can also drag images straight onto a folder in the tree, or onto any folder in the breadcrumb trail above the grid. Dragging an image you have ticked moves everything ticked. Dragging one you have not ticked moves only that image, even if a selection is still active. Two folders never light up and never take a drop: the one you are already in, and one you may not write into. A drop is the same operation as Move to, so it is refused on the same grounds and it is all or nothing in the same way. The Drop images to upload overlay stays away while you are dragging images that are already in the library.
A bulk delete is not all or nothing
The images are deleted one at a time, and the first one that is still used somewhere stops the run. The ones before it are already gone. The message says where the offending image is used, a CMS page and the field inside it for example, but not which image it was. The grid is not refreshed after a failure, so images that have already gone may still be on screen. Reload the folder and look at what is left before you try again.
The details panel¶
Click an image to open Details beside the grid.
| Field | What it is |
|---|---|
| Name | The file name. Edit it in the box and confirm to rename the file. The extension is kept |
| Dimensions | Width and height in pixels |
| Size | The file size |
| Type | The file type |
| URL | The address of the image, with a button that copies it |
| Alternative text | A description saved with the image, used everywhere it appears |
| Delete | Deletes this image |
Renaming is not checked against what uses the image
Where Move to refuses when a picture is used on a page, renaming does not. The file is renamed, anything pointing at the old name is left pointing at nothing, and nothing on screen says so. No reference is rewritten afterwards. Rename a picture before you use it, not after. If you have to rename one that is already in use, fix the pages, blocks and products yourself. Renaming a folder does the same to every image inside it.
When the panel is open as a picker, on a rich text field or an email, it also asks for the things that belong to this insertion rather than to the file:
| Field | What it is |
|---|---|
| Alternative text for this insert | A description used only here, overriding the one saved with the image |
| Alignment | Left, Center or Right |
| Width, Height | The size to show it at |
Close the panel with the cross at its top.
Deleting¶
Delete asks first, and says the file is removed from the library and that it cannot be undone.
Deletion is refused only when a reference is actually found. The message names up to three of the places, for example a CMS page and the field inside it, so you can go and change them. Remove the references first, then delete.
An incomplete answer does not stop a delete. If a usage source fails, or Magento's media gallery synchronisation has never indexed the file, the delete goes ahead and the incomplete answer is written to the log instead. Move is the stricter of the two: it refuses whenever the answer is not complete. That is why a move can be blocked on a file whose delete would not be.
There is no trash to restore from. A deleted file is gone.