Media Library

If you run an asset-intensive app, having one place to view and manage all those assets is invaluable. Avo's Media Library feature makes that easier.

The Media Library has two goals in mind.

1. Browse and manage all your assets
2. Use it to inject assets in Avo's rich text editors (trix, rhino, markdown, and lexxy).

WARNING

The Media Library feature is still in alpha and future releases might contain breaking changes so keep an eye out for the upgrade guide.

This is just the initial version and we'll be adding more features as we progress and get more feedback on usage.

How to enable it

The Media Library feature is disabled by default (until we release the stable version). To enable it, you need to do the following:

# config/initializers/avo.rb
if defined?(Avo::MediaLibrary)
  Avo::MediaLibrary.configure do |config|
    config.enabled = true
  end
end

This is the killswitch of the whole feature. When disabled, the Media Library will not be available to anyone. It will hide the menu item, block all the routes, and hide the Media Library icons from the editors.

Control who can use it

visible decides who may use the Media Library. It gates the sidebar item, the Media Library button in the rich text editors, and the Media Library routes themselves — a user it returns false for gets a 404 on every one of them.

Turn it off for everyone with a Boolean:

# config/initializers/avo.rb
if defined?(Avo::MediaLibrary)
  Avo::MediaLibrary.configure do |config|
    config.visible = false
  end
end

Or restrict it per user with a block, which has access to the Avo::Current object:

# config/initializers/avo.rb
if defined?(Avo::MediaLibrary)
  Avo::MediaLibrary.configure do |config|
    config.visible = -> { Avo::Current.user.is_developer? }
  end
end

Anyone who isn't a developer then has no Media Library at all — no menu item, no button in the editors, and a 404 on every Media Library URL.

visible defaults to true, so an enabled Media Library is available to everyone who can sign in to Avo. Leave it there only if every Avo user may browse, rename and delete every uploaded asset.

WARNING

Before Avo 4.1.7, visible hid the menu item but left the routes reachable by URL, so any authenticated Avo user could browse, rename and delete every asset. See GHSA-cff8-4h3c-9r4q.

Add it to the menu editor

If you customize the menu, the Media Library won't appear automatically. Add it back with a link_to (or link) item pointing at avo.media_library_index_path.

# config/initializers/avo.rb
Avo.configure do |config|
  config.main_menu = lambda {
    link_to 'Media Library', avo.media_library_index_path
  }
end

File previews

Opening a file shows a preview next to its details.

File type	Preview
Images	The image
Audio and video	A player
CSV (text/csv)	A table, with the first row as the header
Other text files (text/*: .txt, .md, and so on)	The file's content as plain text
Everything else	A placeholder icon

Markdown files are shown as source, not rendered.

A CSV table loads up to 1,000 rows at a time, and never more than 1 MB of the file per read — whichever limit it reaches first, so very wide rows arrive in smaller pages. Use Load more rows at the bottom of the table to load the next page, View raw to see the file as plain text instead, and View as table to come back.

Plain text previews show the first 1 MB of the file. Download always gives you the whole file.

The details next to the preview list every record the file is Attached to. Each one links to the record's Show page when the record still exists and its model has an Avo resource. Anything else is listed as plain text, the model name and the id, such as Post #12. That covers a record deleted with delete or delete_all, which skip Active Storage's purge callbacks and leave the attachment behind, and a model with no resource, such as the ActionText::RichText an image embedded in a rich text field is attached to. Since avo >= v4.2.8

Delete removes the file from your storage service along with its record in the database. When the file is attached to records, the confirmation names them, and deleting the file removes it from those records too. Each record is checked the same way as the delete button on its own file field: its delete_<field>? policy method has to allow it, and the record has to stay valid without the file. If any record refuses, nothing is deleted and Avo tells you which record and why. Since avo >= v4.3.14

INFO

Text previews are read from your storage service by the server, so they work the same on local disk, S3, and the other Active Storage services. No extra configuration is needed.

Use it with the rich text editors

The Media Library will seamlessly integrate with all the rich text editors.

field :body, as: :trix
field :body, as: :rhino
field :body, as: :markdown
field :body, as: :lexxy

The editors will each have a button to open the Media Library modal. Once open, after the user selects the asset, it will be injected into the editor.

The button follows visible too, so a user the Media Library is not visible to won't see it.

Disable it on a single markdown field

The markdown field accepts a media_library option (defaults to true). Set it to false to hide the gallery button on that field while keeping the Media Library enabled everywhere else.

field :body, as: :markdown, media_library: false

This is a markdown-only option; the trix and rhino fields don't support per-field toggling. The lexxy field hides the button when its attachments are disabled (attachments_disabled: true).