General mgGetImages Usage

The minimum mgGetImages snippet call outputs a list of thumbnails, linking to an integrated detail page. The minimum snippet call looks like this:

[[!mgGetImages]]

You should always call mgGetImages uncached, as it manages caching internally. This makes sure the images on a Gallery resource are in sync with the frontend, without relying on full site cache clears.

Snippet Properties

&resource

The ID of the MoreGallery resource to get images from. By default, this will use the current resource, so you wont need to specify this if you want to show images from the current resource.

As of 1.5.0, you can also specify a comma separated list of resource IDs to get images from. This is best used in combination with a &sortBy of uploadedon or random.

Default: current resource ID

&sortBy

The field to sort images on. This can be one of the following: filename, name, sortorder, uploadedon, editedon or random to randomise the order of the images.

Default: sortorder

&sortDir

Used with the &sortBy property, this will decide in what direction (ASC: ascending or DESC: descending) the results will be sorted.

Default: ASC

&tags

Specify a comma separated list of tag names or IDs to filter the resulting images on.

To find images that are not tagged with a certain tag, you can specify it with a dash in front (e.g. -highlight) since 1.4.0.

While similar in naming, has no relation to &getTags. If you would like to accept tags through an URL parameter, you can do so with the &tagsFromUrl property. Added in 1.1.0.

Default:

&tagsFromUrl

When not empty, the snippet will look for an URL parameter with the specified name (so if you set this property to "tag" it will look for an URL parameter called "tag") and filter image results on the value of that parameter, which can be a tag ID or actual tag display name. Added in 1.1.0.

&getTags

Set to 1 to load tags for each image and to parse them through the chunk specified in the &tagTpl property.

The result of parsing tags through &tagTpl and separated by the value in &tagSeparator will be set to the [[+tags]] placeholder in both chunks for &imageTpl and &singleImageTpl. For added performance, disable this property by setting it to 0 when not using tags.

Added in 1.1.0.

Default: 1

&getResourceFields

Set to 1 to make resource fields available in the &imageTpl and &singleImageTpl chunks.

The resource fields will be made available as placeholders prefixed by "resource". For example [[+resource.pagetitle]].

When calling mgGetImages on the Gallery resource itself, this isn't typically needed as you could just use the [[*pagetitle]] resource fields, but with multiple galleries this is useful to enable.

Added in 1.0.1.

&getResourceContent

Set to 1 to also load the resource content into the [[+resource.content]] placeholder in the image chunks. &getResourceFields needs to be set to 1 for this property to work.

&getResourceProperties

Set to 1 to also load the resource properties into the [[+resource.properties.NAMESPACE_HERE.KEY_HERE]] placeholders. &getResourceFields needs to be set to 1 for this property to work.

&getResourceTVs

Set to a comma separated list of TV names to make available in the &imageTpl and &singleImageTpl chunks. &getResourceFields needs to be set to 1 for this property to work.

The TVs will be made available as placeholders prefixed by "resource". For example for a TV called "superlongtitle", the placeholder would be [[+resource.superlongtitle]].

When calling mgGetImages on the Gallery resource this isn't typically needed as you could just use the Snippet: mgGetImages resource fields, but with multiple galleries this is useful to enable.

Added in 1.0.1.

&imageTpl

The name of a chunk to use for each image in the result set. The default chunk used is this:

See further down this page for a description of all placeholders available for this chunk.

Individual images will be joined together by the value of the &imageSeparator property.

If you're using videos in MoreGallery, you also need the &youtubeTpl and &vimeoTpl properties. They follow the same structure as the &imageTpl, but which are are applied to YouTube and Vimeo video records respectively. For PDFs, &pdfTpl is available. See below.

&mediaTpl

The name of a chunk to use for each image imported from Sterc's Media Manager. If not specified, this will use the same chunk as provided in the &imageTpl.

You can use the same placeholders as the &imageTpl, but you can also use the following placeholders that are specific to Sterc's media manager:

[[+media.id]] or [[+media_manager_id]]: the ID of the file record in the media manager.

[[+media.media_sources_id]]: the ID of the media source that the media manager keeps the file in.

[[+media.name]]: the name of the file

[[+media.path]]: the path to the file, including the file name, relative to the media source root. The MoreGallery-provided [[+file_url]] and [[+file_path]] are already ready-to-use with the full url/path to the image where the Media Manager uploaded it.

[[+media.version]]: ??

[[+media.file_type]]: the file type/extension

[[+media.file_size]]: the file size in bytes

[[+media.file_dimensions]]: a string in the form of {width}x{height} representing the dimensions of the file. These are also available in MoreGallery's standard [[+width]] and [[+height]] placeholders.

[[+media.file_hash]]: ??

[[+media.upload_date]]: a date string in the format Y-m-d H:i:s when the file was uploaded to the media manager. MoreGallery also provides [[+uploadedon]], which is an integer unix timestamp representing when the file was imported to the Gallery.

[[+media.uploaded_by]]: ID of the user that uploaded the image to the media manager. MoreGallery also provides [[+uploadedby]], which is the ID of the user that imported the image to the Gallery.

[[+media.edited_on]]: a date string in the format Y-m-d H:i:s when the file was last edited in the media manager. MoreGallery also provides [[+editedon]], which is an integer unix timestamp representing when the image record in MoreGallery was last updated.

[[+media.edited_by]]: ID of the user that last edited the file. MoreGallery also provides [[+uploadedby]], which is the ID of the user that last edited the image record in the gallery.

[[+media.is_archived]]: a boolean representing if the file was archived.

[[+media.archive_date]]: a date string or null representing when the file was archived.

&youtubeTpl

The name of a chunk to use for templating a YouTube video. Works identical to &imageTpl for videos from YouTube.

&pdfTpl

The name of chunk to use for templating a PDF file. Works identical to &imageTpl. The [[+mgr_thumb]] placeholder and crops will contain an image of the first page of the PDF, while [[+file_url]] will be a link to the actual PDF.

When no chunk is specified, the &imageTpl is used by default.

&imageSeparator

A string to be used between images parsed through the chunk specified in &imageTpl.

Default: linebreak (\n)

&tagTpl

The name of a chunk to use for each tag for each image, only if &getTags is enabled. Individual tags will be joined together by the value of the &tagSeparator property. The default chunk is stored in the filesystem to prevent changes which are overwritten on upgrade, but looks like this:

This generates links to the current resource, passing along a "tag" URL parameter.

If the mgGetImages snippet call has &tagsFromUrl=tag added, that will filter the image results based on the tag.

Placeholders in the tagTpl are [[+id]], [[+display]] (the tag itself), [[+createdon]] (the first time the tag was added to an image) and createdby (the user ID of the user that used the tag the first time).

Added in 1.1.0.

&tagSeparator

A string to be used between tags parsed through the chunk specified in &tagTpl. Added in 1.1.0.

Default: linebreak (\n)

&singleImageEnabled

Set to 1 to enable the single image view, or 0 to disable it. When enabled, the snippet will automatically show a single image with a different template (see &singleImageTpl) if the &singleImageParam is present in the URL. Useful for accessible image galleries. The single image view has been available since v1.0, the singleImageEnabled property was added in v1.4.

Default: 1

&singleImageParam

The URL param to use for the single image view. This will contain the ID of an image inside the gallery that needs to be shown with the &singleImageTpl chunk. The single image view has been available since v1.0, but this property was added in v1.4. This setting inherits from the moregallery.single_image_url_param setting if left empty.

Default: iid

&singleImageResource

For advanced setups where you may be retrieving images from a different resource, but need the single image view to happen on the current resource, you can specify this property. For example you may list images from &resource=15, but provide &singleImageResource=[[*id]] so the single images open on the current resource.

Added in 1.5.0.

Default: the value of &resource

&singleImageTpl

The name of a chunk to use for the single image view. See further down this page for the default and placeholders for this chunk.

There are also &singleYoutubeTpl and &singleVimeoTpl properties for YouTube and Vimeo videos respectively, and a &singlePdfTpl for PDFs, which both follow the same behaviour as the &singleImageTpl.

&singlePdfTpl

The name of a chunk to use for a single PDF file being shown. Works identical to the &singleImageTpl property. The [[+mgr_thumb]] and crops will contain images of the first page in the PDF, while [[+file_url]] is a link to the actual PDF.

&limit

&offset

Note: if you're specifying an offset, you also need to specify a limit larger than 0. This can be a crazy big amount if you want all images, but without a limit offset wont work.

&scheme

The scheme to be used in url generation when the url field of an image is a resource ID. Defaults to the value of the link_tag_scheme (core) system setting.

&cache

When enabled, mgGetImages will cache the images on various levels.

There really is no need to turn this off since 0.9.6. Changes to chunks and snippet properties are automatically recognised, causing it to regenerate the markup.

Default: 1

&where

A JSON object for generic filtering. For example you can use this to get a specific image by passing {"id":5}.

&activeOnly

By default mgGetImages will only show active images, but if you also want hidden images to be returned you can set this property to 0.

Default: 1

&debug

When set to 1, MoreGallery will output a debug log showing how it processed the snippet call and ended up with the results it showed. This debug information is appended to the output of the snippet.

&timing

When set to 1, MoreGallery will output the total time it took to process the snippet. This will be appended to the end of the snippet. Useful when combined with &debug to identify performance bottlenecks.

The expected timing for a cached result (so a repeat request) is expected to be around 5-10ms, while the uncached result strongy depends on the number of images that are loaded and the complexity of your templates.

To show the image, the main placeholders to use are [[+file_url]], [[+file_path]] in combination with a thumbnail snippet like pthumb, [[+view_url]] for the single image view, or [[+mgr_thumb]] for the thumbnail also used in the manager.

When using video the [[+video_id]] placeholder contains the unique video ID for the service that can be used to create an embed code to suit your needs. The [[+service]] placeholder contains either youtube or vimeo. The chunk names for video are specified in either the &youtubeTpl or &vimeoTpl properties.