fm:MediaList

The medialist allows you to display a list of media from the system. This could be used to display a list of recent blogpost, a gallery, or many other things.

This is the most powerful component in the system, since media serves such an important role in the Media Factory.

Example

<fm:MediaList fields="id,title">

  <fm:Loop>

     <a href="/article/{$$media_id}">{$$media_title}</a><br />

  </fm:Loop>
</fm:MediaList>

Supported attributes

Name	Required	Default	Description
channel	Optional	0	The channel to filter on. This can be specified with either a shortname, or an id.
collection	Optional	0	The collection to use to display media. This has to be specified by its id.
context	Optional	"generic", if parentID is set then defaults to "comment"	This is related to the parent and type of media. generic only normal media (no comments or notes) all all media comment only comments note only moderators' notes commentnote only comments and moderators' notes genericcomment everything but notes (comments and regular media) parent only parent media (deprecated) child only child media (deprecated)
dateFormat	Optional	%Y-%m-%d %H:%i:%s	This attribute allows you to change the way dates are displayed within the list. By default it will be YYYY-MM-DD HH:MM:SS. The format which should be used is the same as PHP's date() function.
endTime	Optional	N/A	This attribute filters by the upload date. No media past the endTime will be returned. Usually you should use YYYY-MM-DD format, but things like 'yesterday' will also work.
evenClass	Optional		The contents of this attribute will be placed in the 'loop.evenClass' template variable, only for even row-numbers. This allows you to give every even row a specific css class
eventId	Optional	0	Show media associated to an event. This has to be specified by id.
favorite_uid	Optional	N/A	This attribute allows you to fetch a user's favorites. Specify the user's id.
fields	Optional	N/A	Comma separated list of fields to retrieve for this query. Explained below.
fileTypes	Optional	1,2,3,4	Allows you to filter by a specific filetype. 1 = image, 2 = video, 3 = audio, 4 = text. You can supply multiple values by separating them with comma's
geoBoundaries	Optional	N/A	Filter by latitude and longitude. Specify this as "{west longitude},{north latitude},{east longitude},{south latitude}".
groupId	Optional	N/A	Only show media from a specific group
hidden	Optional	N/A	One of "PUBLIC" (default), "PRIVATE", or "ALL". Usually this should only be set when a user filter is set as well to only show a specific user's private media.
includeChildren	Optional	0	Only used in conjunction with a channel filter. This allows you to specify if you'd like to get all media from the specified channel + media from underlying channels (when nested channels are used). This is specified as 0 for false, 1 for true.
moderationStatus	Optional	Project setting	This filter can be used to override a vhosts moderation setting. Possible values are unmoderated, accepted, denied, notdenied, moderated, all
oddClass	Optional		The contents of this attribute will be placed in the 'loop.oddClass' template variable, only for odd row-numbers. This allows you to give every odd row a specific css class
offset	Optional	0	Only show media starting with this number. If for example 5 is supplied, the list with start with the 5th item in the query.
pageSize	Optional	30	The number of media-items per page. A maximum page size of 200 is enforced, attempting to set this to anything greater will cause the page size to revert to 200.
parentID	Optional	0	Only return media with the specified parentID. Note that setting this causes "context" to default to "comment"
parentUserID	Optional	N/A	Include only media whose parent's owner matches this ID. This must be used with a context filter restricting results to media with a parent (ie: context filter of "child", "comment", or "note"). Useful for showing all comments on any of a user's media in combination with the context filter
searchQuery	Optional	N/A	Allows you to search for media matching the query. The filename, title, description and tags will be used for the search.
sort	Optional	upload DESC	Allows you to sort by a specific field, for example upload ASC, rating DESC, commentcount DESC, votecount DESC. Multiple sort fields may be specified separated by commas, eg: sort="commentcount DESC, upload DESC"
startPage	Optional	N/A	Specifies the start-page. This can be used in conjuction with pageSize.
startTime	Optional	N/A	This attribute filters by the upload date. No media before the startTime will be returned. Usually you should use YYYY-MM-DD format, but things like 'yesterday' will also work.
tag	Optional	N/A	This filter allows you to filter media by a specific tag.
uid	Optional	N/A	Filter by a specific users id.

Deprecated Attributes

Name	Required	Default	Description
cacheTimeOut	Optional	N/A	This attribute allows you to cache results for x seconds. Use the fm:Cache component instead.
requestVars	Optional	30	This attribute allowed you to automatically add filters through _GET variables, such as channel, sort. Use channel="{$$get.channel}" now instead.

The format for the dateFormat attribute is the same as PHP's date function.
The accepted values for startTime and endTime are the same as PHP's strtotime function.
The fields should contain a comma-seperated list of template variables you would like to see for every media item. In the initial example 'id' and 'title' were specified, but almost all variables from the table below are accepted.
In the past numeric values for moderationStatus were also accepted, but it is strongly discouraged to do so today.

Template variables

Name	Description
loop.hasResults	The contents of this variable will be either 0 or 1, depending on if there are items in the list.
loop.oddClass	The contents of this variable will reflect the "oddClass" attribute. This will only be set for odd rownumbers.
loop.evenClass	The contents of this variable will reflect the "evenClass" attribute. This will only be set for even rownumbers.
loop.index	The 0-based index of the item in the loop. (Will contain 0,1,2,3,4, etc.)
loop.currentPage	If a pager is involved in this loop, this will contain the current page number (0-based index). If page information is not available, this will be 0.
loop.currentPage1	This value is currentPage + 1. This number can be useful to display the current page number to use user. (people generally count from 1, not 0).
loop.totalPages	Total number of pages avaiable in this loop. This will be 0 if the loop does not support paging.
loop.totalItems	Total number of individual items. This will be 0 if the loop does not support paging.
loop.pageSize	Total number of items on 1 single page. This will be 0 if the loop does not support paging.
media_approvedcomments	The total number of approved comments for this file.
media_notdeniedcomments	The number of comments that have not been denied for this file.
media_channel	The channel-id if the file was associated to a channel.
media_channel_name	The name of the channel if the file was associated to a channel.
media_channel_shortname	The 'shortname' of the channel if the file was associated to a channel.
media_contenttype	The mimetype of the file, for example: audio/mp3.
media_conversiontime	The time needed to transcode the file, in seconds.
media_converttime	The date and time when the transcoding was completed for this file.
media_commentcount	The total number of comments to this file.
media_currentpage	The page number the user is currently on.
media_date	The original creation date of the file. If we cannot detect this, this will be the same as the upload date.
media_duration	The duration of the file in a human-readable format (example: 00:01:07).
media_extension	The original file extension, for example 'mp4'
media_filetype	The filetype. This is specified as a number between 1 and 4. Read below for more information.
media_filename	The original filename
media_filesize	The size of the file, in bytes.
media_height	The height of the original file in pixels.
media_hits	The number of views the file got.
media_id	The unique id of the file.
media_injector	A string describing the application that created the file, for example Uploader or Recorder.
media_length	The duration of the file in as a floating point number in seconds. (example: 187.33, for 3 minutes, 7 seconds)
media_message	The description of the file.
media_metadata	User or developer defined meta-data, read below for more information.
media_ofilesize	The total size of all transcoded versions of this file, including thumbnails in bytes.
media_offset	The offset of the current media-item within the current search query. The first item in the list will have 0, the second 1, the first item on the second page (if there are 30 items per page) will be 30
media_publicUrl	The base-url associated with the file. See below for more information.
media_rating	The average rating. This is a floating point number between 0 and 10. 2 decimals are provided.
media_status	The status of the file. Generally this is always 3, meaning 'succesfully converted'.
media_title	The title of the file.
media_tags	A space delimited list of tags associated with the file. For example "amsterdam holiday".
media_uid	The id of the user who uploaded the file.
media_updownrating	This template variable will give you the "thumbs up/down" rating. The actual formula is actually based on the votecount and average rating, and assumes people rate 0 for down, and 10 for up.
media_upload	The date and time the file was added to the Media Factory.
media_uploadage	The time that has passed since the file was uploaded. The format will be for example 5 seconds, 20 minutes or 12 days.
media_user_city	The submitter's city.
media_user_country	The submitter's 2-letter country code.
media_user_firstname	The submitter's first name.
media_user_lastname	The submitter's last name.
media_user_name	The username of the person uploading the file.
media_user_nickname	The submitter's nickname.
media_user_state	The 2-letter state or province code of the submitter.
media_votecount	The total number of votes cast.
media_width	The width of the original file in pixels.
media_geo_latitude	The latitude of the file if available, otherwise empty.
media_geo_longitude	The longitude of the file if available, otherwise empty.
media_author	This field is used to retrieve the name entered by an anonymous user. Often used when users can comment without registering, by a captcha.

Deprecated Template Variables

Name	Description
filter_string	A url-encoded list of filters used.
media_htmlmessage	The html escaped version of the description of the file.
media_location	The nickname for a server the file is located on.
media_moderationstatus	The id associated with the current moderation status. This variable should be avoided.
media_offensive	The offensiveness rating.
media_searchchannel	The channel used to filter the medialist.
media_searchfiletype	The filetype used to filter the medialist.
media_searchuid	The user-id used to filter the medialist.
totalCount	The total number of media-items for these filters. This includes items possibly not on the current page.
totalPages	The total number of pages, based on the the number of items per page and the total pages.

The media_filetype variable will be 1 for images, 2 for video, 3 for audio and 4 for text.
Meta-data is completely free form, and can contain more information supplied by the developer. An example is media_metadata.myCategory. Note that the sub-elements in media_metadata are separated by punctuation marks (.).
The media_publicUrl is a direct link to the transcoded files. To display a thumbnail for a video, append /11, for a direct link to a flash video file append /21.

More examples

This lists sorts all the media by the number of hits, and filters by a channel. Also, we're only retrieving text files

<fm:MediaList fields="id,title" channel="myBlog" sort="hits DESC" fileTypes="4" evenClass="even">

  <fm:Loop>

     <a href="/article/{$$media_id}" class="{$loop.evenClass}">{$$media_title}</a><br />

  </fm:Loop>

  <fm:NoResults>
      No articles were found!
  </fm:NoResults>

</fm:MediaList>

This lists shows 84x84 jpeg thumbnail for all image and video uploads. We set the limit for this gallery to 100.

<fm:MediaList fields="publicUrl,title" fileTypes="1,2" pageSize="100">

  <fm:Loop>

    <span class="thumbnail">

        <img src="{$publicUrl}/12" alt="{$$media_title}" title="{$$media_title}" />

    </span>
     
  </fm:Loop>

</fm:MediaList>

This lists shows videoplayers, audio players, text entries and large images. Because a lot of flash on one page is a bad idea, we set the limit to 10.

<fm:MediaList fields="id,publicUrl,title,message,user_name,upload,filetype" pageSize="100">

  <fm:Loop>

    <div class="mediaEntry">

        <h1>{$$media_title}</h1>
        <p>{$$media_message}</p>

        <p>Submitted by {$$media_user_name} on {$$media_upload}</p>

        <fm:Switch value="{$$media_filetype}">

            <!-- images -->
            <fm:Case value="1"><img src="{$publicUrl}/15" alt="{$$media_title}" /></fm:Case>

            <!-- video -->
            <fm:Case value="2"><fm:VideoPlayer mid="{$media_id}" autoPlay="0" width="600" height="450" /></fm:Case>

            <!-- audio -->
            <fm:Case value="3"><fm:Mp3 mid="{$media_id}" autoPlayer="0" /></fm:Case>

            <!-- text -->
            <fm:Case value="4">
                <strong>This text file was brought to you by cheesy poofs</strong>
            </fm:Case>

        </fm:Switch>

    </div>

    <hr />

  </fm:Loop>

</fm:MediaList>

<< 7.3.30 fm:Loop 7.3.32 fm:Meta >>

developer documentation r17362