m_media (zotonic_core v1.0.0-rc.17)

Access to data about uploaded files and other media.

The medium (singular form of media) table stores all information of uploaded files or other media. Every resource can contain a single medium. A resource with a medium is most often of the category image, audio, video or document.

In template the m_media model is used to fetch the medium record by the resource id: m.media[id]. This is the same function as with m.rsc[id].medium except, that the m_rsc model does access control checks and the m_media does not.

The m_media model implements all functions to handle media files and is used by other Erlang modules.

Properties of a medium record

A medium record has minimally the following properties, other properties can be added by modules.

PropertyDescriptionExample value
idId of the medium record, equal to the page id.512
filenameFilename and path of the uploaded file, relative to the archive directory.<<"2009/10/20/zotonic-datamodel.jpg">>
rootnameRoot name of the filename.<<"zotonic-datamodel">>
original_filenameFilename as suggested by the user agent when uploading the file. Can contain illegal characters.<<"Zotonic-datamodel.jpg">>
mimeMime type of the medium.<<"image/jpeg">>
widthWidth in pixels.536
heightHeight in pixels.737
orientationExif oritentation of the image.1
sha1Optional sha1 checksum of uploaded file. Undefined when not present.
sizeSize in bytes of the uploaded file.71585
preview_filenameOptional filename for a generated file preview.
preview_widthOptional. Width of the generated preview.
preview_heightOptional. Height of the generated preview.
is_deletable_fileIf the file should be deleted when the medium record is deleted. A boolean.true
is_deletable_previewIf the optionally generated preview file should be deleted when the medium record is deleted. A boolean.false
createdTimestamp when the medium record is created.{{2009,10,20},{13,47,27}}

Available Model API Paths

MethodPath patternDescription
get/+id/...Return medium record for resource +id when the resource is visible; returns enoent for unknown resource and eacces when not visible.
post/+idReplace medium of existing resource +id from payload url or uploaded file (#upload); optional payload rsc map updates resource props. No further lookups.
post/Create a new resource+medium from payload url or uploaded file (#upload), with optional payload rsc properties for the new resource. No further lookups.
delete/+idDelete medium linked to resource +id (queues file cleanup, emits media events); requires editable resource access. No further lookups.

/+name marks a variable path segment. A trailing /... means extra path segments are accepted for further lookups.

Summary

Types

media_url()
option()
options()

Functions

delete(Id, Context)
depiction(Id, Context)
depicts(Id, Context)
download_file(Url, Context)
download_file(Url, Options, Context)
duplicate(FromId, ToId, Context)
exists/2
get/2
get_by_filename(Filename, Context)
identify/2
insert_file(File, Context)
insert_file(File, RscProps, Context)
insert_file(File, RscProps, Options, Context)
insert_medium(Medium, RscProps, Options, Context)
insert_url(Url, Context)
insert_url(Url, RscProps, Context)
insert_url(Url, RscProps, Options, Context)
is_unique_file(Filename, Context)
m_delete/3
m_get/3
m_post/3
make_preview_unique(RscId, Extension, Context)
merge(WinnerId, LoserId, Context)
mime_to_category(Mime)
recover_medium(Medium, Context)
replace(Id, MediaProps, Context)
replace_file(File, RscId, Context)
replace_file(File, RscId, RscProps, Context)
replace_file(File, RscId, RscProps, Options, Context)
replace_file(File, RscId, RscProps, MediaInfo, Options, Context)
replace_medium(Medium, RscId, RscProps, Options, Context)
replace_url(Url, RscId, RscProps, Context)
replace_url(Url, RscId, RscProps, Options, Context)
reupload(Id, Context)
save_preview(RscId, Data, Mime, Context)
save_preview_url(RscId, Url, Context)

Types

media_url()

-type media_url() :: binary() | string().

option()

-type option() ::
          {preferred_category, m_rsc:resource()} |
          {preview_url, media_url()} |
          {max_length, non_neg_integer()} |
          {timeout, non_neg_integer()} |
          m_rsc:update_option().

options()

-type options() :: [option()].

Functions

delete(Id, Context)

-spec delete(m_rsc:resource_id(), z:context()) -> ok | {error, term()}.

depiction(Id, Context)

-spec depiction(m_rsc:resource_id(), z:context()) -> map() | undefined.

depicts(Id, Context)

-spec depicts(m_rsc:resource_id(), z:context()) -> [m_rsc:resource_id()].

download_file(Url, Context)

download_file(Url, Options, Context)

duplicate(FromId, ToId, Context)

-spec duplicate(m_rsc:resource(), m_rsc:resource(), z:context()) -> ok | {error, term()}.

exists/2

-spec exists(undefined | string() | binary() | integer(), z:context()) -> boolean().

get/2

-spec get(m_rsc:resource() | undefined, z:context()) -> z_media_identify:media_info() | undefined.

get_by_filename(Filename, Context)

-spec get_by_filename(binary(), z:context()) -> z_media_identify:media_info() | undefined.

identify/2

-spec identify(m_rsc:resource_id(), z:context()) ->
                  {ok, z_media_identify:media_info()} | {error, term()}.

insert_file(File, Context)

-spec insert_file(File, Context) -> {ok, RscId} | {error, term()}
                     when
                         File ::
                             file:filename_all() |
                             #upload{filename :: binary() | undefined,
                                     tmpfile :: file:filename_all() | undefined,
                                     tmpmonitor :: undefined | pid(),
                                     data :: binary() | undefined,
                                     mime :: binary() | undefined},
                         Context :: z:context(),
                         RscId :: m_rsc:resource_id().

insert_file(File, RscProps, Context)

-spec insert_file(File, RscProps, Context) -> {ok, RscId} | {error, term()}
                     when
                         File ::
                             file:filename_all() |
                             #upload{filename :: binary() | undefined,
                                     tmpfile :: file:filename_all() | undefined,
                                     tmpmonitor :: undefined | pid(),
                                     data :: binary() | undefined,
                                     mime :: binary() | undefined},
                         RscProps :: m_rsc:props_all(),
                         Context :: z:context(),
                         RscId :: m_rsc:resource_id().

insert_file(File, RscProps, Options, Context)

-spec insert_file(File, RscProps, Options, Context) -> {ok, RscId} | {error, term()}
                     when
                         File ::
                             file:filename_all() |
                             #upload{filename :: binary() | undefined,
                                     tmpfile :: file:filename_all() | undefined,
                                     tmpmonitor :: undefined | pid(),
                                     data :: binary() | undefined,
                                     mime :: binary() | undefined},
                         RscProps :: m_rsc:props_all(),
                         Options :: options(),
                         Context :: z:context(),
                         RscId :: m_rsc:resource_id().

insert_medium(Medium, RscProps, Options, Context)

insert_url(Url, Context)

-spec insert_url(Url, Context) -> {ok, RscId} | {error, term()}
                    when Url :: media_url(), Context :: z:context(), RscId :: m_rsc:resource_id().

insert_url(Url, RscProps, Context)

-spec insert_url(Url, RscProps, Context) -> {ok, RscId} | {error, term()}
                    when
                        Url :: media_url(),
                        RscProps :: m_rsc:props_all(),
                        Context :: z:context(),
                        RscId :: m_rsc:resource_id().

insert_url(Url, RscProps, Options, Context)

-spec insert_url(Url, RscProps, Options, Context) -> {ok, RscId} | {error, term()}
                    when
                        Url :: media_url(),
                        RscProps :: m_rsc:props_all(),
                        Options :: options(),
                        Context :: z:context(),
                        RscId :: m_rsc:resource_id().

is_unique_file(Filename, Context)

-spec is_unique_file(Filename, Context) -> boolean()
                        when Filename :: file:filename_all(), Context :: z:context().

m_delete/3

-spec m_delete([binary()], zotonic_model:opt_msg(), z:context()) -> {ok, term()} | ok | {error, term()}.

m_get/3

-spec m_get(list(), zotonic_model:opt_msg(), z:context()) -> zotonic_model:return().

m_post/3

-spec m_post([binary()], zotonic_model:opt_msg(), z:context()) -> {ok, term()} | ok | {error, term()}.

make_preview_unique(RscId, Extension, Context)

-spec make_preview_unique(RscId, Extension, Context) -> PreviewFilename
                             when
                                 RscId :: m_rsc:resource_id() | insert_rsc,
                                 Extension :: binary(),
                                 Context :: z:context(),
                                 PreviewFilename :: file:filename_all().

merge(WinnerId, LoserId, Context)

mime_to_category(Mime)

-spec mime_to_category(Mime) -> media | image | video | audio | document
                          when Mime :: string() | binary().

recover_medium(Medium, Context)

-spec recover_medium(Medium, Context) -> ok | {error, Reason}
                        when Medium :: map(), Context :: z:context(), Reason :: term().

replace(Id, MediaProps, Context)

-spec replace(Id, MediaProps, Context) -> ok | {error, term()}
                 when Id :: m_rsc:resource_id(), MediaProps :: map() | list(), Context :: z:context().

replace_file(File, RscId, Context)

-spec replace_file(File, RscId, Context) -> {ok, RscId} | {error, term()}
                      when
                          File ::
                              file:filename_all() |
                              #upload{filename :: binary() | undefined,
                                      tmpfile :: file:filename_all() | undefined,
                                      tmpmonitor :: undefined | pid(),
                                      data :: binary() | undefined,
                                      mime :: binary() | undefined},
                          RscId :: m_rsc:resource_id(),
                          Context :: z:context().

replace_file(File, RscId, RscProps, Context)

-spec replace_file(File, RscId, RscProps, Context) -> {ok, RscId} | {error, term()}
                      when
                          File ::
                              file:filename_all() |
                              #upload{filename :: binary() | undefined,
                                      tmpfile :: file:filename_all() | undefined,
                                      tmpmonitor :: undefined | pid(),
                                      data :: binary() | undefined,
                                      mime :: binary() | undefined},
                          RscId :: m_rsc:resource_id(),
                          RscProps :: m_rsc:props_all(),
                          Context :: z:context().

replace_file(File, RscId, RscProps, Options, Context)

-spec replace_file(File, RscId, RscProps, Options, Context) -> {ok, RscId} | {error, term()}
                      when
                          File ::
                              file:filename_all() |
                              #upload{filename :: binary() | undefined,
                                      tmpfile :: file:filename_all() | undefined,
                                      tmpmonitor :: undefined | pid(),
                                      data :: binary() | undefined,
                                      mime :: binary() | undefined},
                          RscId :: m_rsc:resource_id(),
                          RscProps :: m_rsc:props_all(),
                          Options :: options(),
                          Context :: z:context().

replace_file(File, RscId, RscProps, MediaInfo, Options, Context)

-spec replace_file(File, RscId, RscProps, MediaInfo, Options, Context) -> {ok, RscId} | {error, term()}
                      when
                          File ::
                              file:filename_all() |
                              #upload{filename :: binary() | undefined,
                                      tmpfile :: file:filename_all() | undefined,
                                      tmpmonitor :: undefined | pid(),
                                      data :: binary() | undefined,
                                      mime :: binary() | undefined},
                          RscId :: m_rsc:resource_id(),
                          RscProps :: m_rsc:props_all(),
                          MediaInfo :: z_media_identify:media_info() | list(),
                          Options :: options(),
                          Context :: z:context().

replace_medium(Medium, RscId, RscProps, Options, Context)

replace_url(Url, RscId, RscProps, Context)

-spec replace_url(Url, RscId, RscProps, Context) -> {ok, RscId} | {error, term()}
                     when
                         Url :: media_url(),
                         RscId :: m_rsc:resource_id(),
                         RscProps :: m_rsc:props_all(),
                         Context :: z:context().

replace_url(Url, RscId, RscProps, Options, Context)

-spec replace_url(Url, RscId, RscProps, Options, Context) -> {ok, RscId} | {error, term()}
                     when
                         Url :: media_url(),
                         RscId :: m_rsc:resource_id(),
                         RscProps :: m_rsc:props_all(),
                         Options :: options(),
                         Context :: z:context().

reupload(Id, Context)

-spec reupload(m_rsc:resource_id(), z:context()) -> {ok, m_rsc:resource_id()} | {error, term()}.

save_preview(RscId, Data, Mime, Context)

-spec save_preview(m_rsc:resource_id(), iodata(), binary() | string(), z:context()) ->
                      {ok, file:filename_all()} | {error, eacces | term()}.

save_preview_url(RscId, Url, Context)