#Media

Your Addon can add Media Items to the Media Library. You can package these in your Addon, download them to your Addon's Storage Path and add them by providing their filepath, or you can simply pass a URL to MercuryCMS for it to download. All files you provide MercuryCMS will automatically be converted and resized.

#Storing Media

To store Media, you can use cms.createMedia() and pass it a source which must be one of url, filepath, or use a multipart/form-data request and provide a file object called file.

// use static-cms-addon
import cms from 'static-cms-addon'

let media = await cms.createMedia({
  name: 'My Image', // optional
  altText: 'An Image I Made', // optional
  caption: 'I really, really, really like this image', // optional
  url: 'http://example.com/images/my_image.png',
})
console.log(media._id)

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/media`, {
  name: 'My Image',
  altText: 'An Image I Made',
  caption: 'I really, really, really like this image', // optional
  url: 'http://example.com/images/my_image.png',
})
console.log(response.data.media._id)

If you provide a url, that URL will be saved on the Media Item in the Media Library. If you attempt to add media from the same URL in the future, it will skip downloading and instead just return the media object that already exists. You can force the Media to be downloaded by passing refreshFromSource: true as one of the options in the request. This will force the Media to be redownloaded and saved without changing the Media's _id.

When providing a filepath, is must be absolute. Unlike url, filepath is not saved on the Media, so you can safely use the same filepath multiple times to create multiple Media Items.

If you do not provide a name, MercuryCMS will use the base filename. For example, if you use filepath: '/path/to/image.png', the Media's name will be "image".

#Media Directories

You can put Media Items into Media Directories by specifying a path. Any path you specify will put the new Media into the existing path by that name, automatically creating any directories that don't exist. For example, if you specify path: 'My Addon/Interior Photos', it will automatically create a directory called "My Addon" if it doesn't exist, then create a folder called "Interior Photos" inside the My Addon folder before adding Media into that folder.

Once you have created a Media Item, users are free to organize it into directories as they wish. If you'd like to move an existing Media Item to a different path, you can use cms.moveMedia(). This will automatically create any directories that don't exist and move the selected items to the new path. Note that moving items may confuse users into thinking the Media has been deleted. When doing this, make it clear to your users where the Media went and why.

// use static-cms-addon
import cms from 'static-cms-addon'

let media = await cms.getMedia()
let mediaItem = media[0]

await cms.moveMedia(mediaItem._id, 'My Addon/New Place') // you can pass a single _id or array of _ids

// use axios
let response = await axios.get(`http://localhost:${cmsPort}/api/addon/media`)
let mediaItem = response.data.media[0]

await axios.post(`http://localhost:${cmsPort}/api/addon/media/move` {mediaIds: [mediaItem._id], path: 'My Addon/New Place'})

#Getting Media

You can get a list of all of the Media your Addon has creating by using cms.getMedia().

// use static-cms-addon
import cms from 'static-cms-addon'

let media = await cms.getMedia()
console.log(media[0])

// use axios
let response = await axios.get(`http://localhost:${cmsPort}/api/addon/media`)
console.log(response.data.media[0])