MAM

Media Asset Management (MAM) Upload & Image Upload

MAM- and image upload insert media objects in a template using a special syntax. Depending on whether an image or another object should be displayed in the final document, this syntax differs.

You can use the IMG tag in order to load images from the MAM or the image upload in a document. Other objects such as, for example, flash objects, PDF files or audio files can be integrated using the <OBJECT> tag, resp. <EMBED> tags, or the <A> tag.
Refer to Objects Integration.

Furthermore, it is possible to define the behavior of the Media Asset Management with processing instructions and retrieve Media Asset Management variables (MAM variables). These variables contain information stored in the details for an image or another object in the MAM.
A list of all MAM variables can be found under MAM Variables.

Integrating Images Using the MAM#

Integrating images in a document is done by calling the MAM, using the src attribute of the IMG tag. You may adjust the image size, using the width and height attributes.

Note

If you set the value of the size attribute in quotation marks (XHTML compliant), the Media Asset Management automatically generates an appropriately scaled image file. Reduction in size simultaneously reduces the data amount.
When you set no introductory character (none XHTML compliant, allowed in HTML 4.0 Transitional) the browser scales the representation of the image. In this case, reduction in size does not reduce the data amount, since the same file is used.

The syntax for a MAM call into a template is as follows:

 <img src="IMPERIA:variable_name" alt="IMPERIA:alt" height="180" width="220" />
 <input name="IMPERIA:alt" />

In Edit mode, the default image is displayed until a user selects an image. The link Assets opens the Media Asset Management in a new window, the link Upload opens the image upload.

An example of a call with processing instructions:

<IMG SRC="IMPERIA:image" ALT="IMPERIA:alt" HEIGHT="180" WIDTH="300">
  <?imperia mam copy FILESIZE:filesize LASTMODIF_DATE:lastmod?>
  <?imperia mam default "/imperia/images/gui/default9.png"?>
</IMG>
<input name="IMPERIA:alt" /><br />
<input name="IMPERIA:filesize"> Size in bytes /<br />
<input name="IMPERIA:lastmod"> Last modification date /<br />

This example contains two processing instructions. With the first one the MAM variables are read out and the values are stored in meta variables. These values are entered in the input fields, when a user has selected an image. The second processing instruction specifies a different default image.

After an image is selected, the input field contains the name of the image as stored in the MAM. This input field is optional and is used in this example to give the user the option to enter an alternative title. The information taken from the MAM can be changed using input fields. These changes, however, are only valid for the document and not transferred to the asset in the Media Asset Management.

Important

Please note that with processing instructions the image tag is closed with </IMG>.
Unless the tag is closed in this way the instructions won't be executed.
All instructions should be opened with <? and closed with ?>. If there is a line that opens and closes in a different way, the system won't proceed with the instructions.

Objects Integration#

To integrate objects that cannot be integrated through the IMG tag, you should use different attributes, depending on the tag.

In order to generate a link to a PDF document and additionally display the file size, the following syntax is used:

#IF ("<!--XX-editmode-->")
  <a href="IMPERIA:MAM:download">
  <?imperia mam copy OBJURL:pdfurl NAME:pdfname FILESIZE:pdfsize?>Select file</a>
  <input name="IMPERIA:pdfurl" type="hidden" />
  File Size: <input name="IMPERIA:pdfsize" />
  Filename: <input name="IMPERIA:pdfname" />
#ELSE
  <a href="IMPERIA:MAM:pdfurl"><!--XX-pdfname--></a>
#ENDIF

This code generates a MAM call in the Edit mode of a document. The two input fields under this link are automatically updated with the corresponding data, as soon as a user has selected an object.

Note that you need to create a meta variable for each MAM variable in a template. If the information from the Media Asset Management should not appear in a document, you can, as in the example of the meta variable pdfurl, set the input element as invisible (type attribute set to hidden).

In all modes, except for Save mode, there is a link, which refers to the corresponding object and starts the download.

If an object should be started directly in a document, for example, a flash film, the <src> attribute of the <embed> tag should contain the path of the desired object. Example:

 #IF (<!--XX-editmode-->)
   <a href="IMPERIA:MAM:download">
   <?imperia mam copy FILESIZE:size
    NAME:name?>Choose Flash</a><br>
   <input name="IMPERIA:size" />
   <input name="IMPERIA:name" />
 #ELSE
   <object classid= [...] ID="<!--XX-name-->" width="550" height="400">
   <param name=movie VALUE="<!--XX-OBJ-download-->">
   <param name=quality VALUE=high>
   <param name=bgcolor VALUE=#FFFFFF>
   <embed src="<!--XX-OBJ-download-->"> [...] </embed>
   </object><p>
 #ENDIF

Note

Omitted, not relevant parts of the code are indicated by [...].

This code generates a link in Edit mode that opens the Media Asset Management in order to select a file. Additionally, there are two input fields for the name and size of the selected file. In every other mode, the selected object is shown. Make sure to reference these objects with the XXOBJ variable type, so that imperia can resolve the paths to the appropriate files. Refer also to XX variables and XX-OBJ Variables.

Image gallery#

To generate an image gallery, please refer to Generating image galleries in the chapter Templates, as it is an issue of configurating the template.

Adjusting the MAM Invocation#

The following MAM properties can be adjusted with processing instructions:

displayed links
preset action for editing
text of links
the default image when no object is currently selected
the method by which images are to be scaled down

mam switchbyname or mam switchbyvalue

This command controls which links should be displayed in the MAM call in Edit mode via a meta variable (mam, upload, remove and/or actions). Please refer to Configuration with Processing Instructions for more details.

mam label

With this command you can configure the link label for opening the Media Asset Management.

Example: <?imperia mam mam_label MAM?>

The example code changes the link text in the MAM call from Assets to MAM.

upload label

This command changes the link label for opening the image upload dialog.

Example: <?imperia mam upload_label Filesystem?>

The example code changes the link label in the MAM call from Upload to Filesystem (see screenshot).

Media Asset Management call with customized labels

mam actions_action

With this command one can define which actions (for example cropping) should be executed, when a user clicks on the link “Customize” in the MAM call.

<?imperia mam actions_action (AssetActions_PLUGINNAME)?>

mam default

With this command you may specify a different default image. Provide a path to the new image.

mam quickupload

If this option is set, the image upload is replaced by a simple upload into the MAM. The user has no choice for selecting into which MAM category to upload, the category id is set directly in the invocation.

<?imperia mam quickupload /3/23/651?>

If additionally you want to limit which types of documents can be uploaded, this can be controlled with the instruction:

<?imperia mam quickupload_mime_filter REGEXP ?>

The parameter REGEXP is a regular expression which checks the files' mime type. In order, for example, to allow only images to be uploaded, use:

<?imperia mam quickupload_mime_filter image ?>

If you want to allow only PNG images, use:

<?imperia mam quickupload_mime_filter image/png ?>

and for PDF files:

<?imperia mam quickupload_mime_filter application/pdf ?>

mam quickupload_mime_filter

With this command you can define which types of assets (for example, image or file formats) can be uploaded when using quick upload.

<?imperia mam quickupload_mime_filter [regular expression for comparing the MIME type]?>

mam letterbox

This command modifies the behavior for downscaling an image. Normally, when an image from the MAM with a different aspect ratio is inserted into a document, the image is first downscaled and then cropped to fill the given image size. With the processing instruction “letterbox” the image is not cropped, but scaled and the remaining space is filled with a color.

As a parameter an HTML color value without a hash (e.g. “606060”) or “trans” must be specified; “trans” results in transparent borders of GIF and PNG images. Since the JPEG format does not recognize border transparency, when you use “trans” the borders are black.

<?imperia mam letterbox 606060?>
<?imperia mam letterbox trans?>

Adjusting the MAM Window#

The following properties of the MAM window can be adjusted with processing instructions:

height and width
the automatically opened MAM category

Adjusting the height and width

The width and height of the MAM window can be adjusted with processing instructions (PI) in the MAM call.

<?imperia mam window_width 500?>
<?imperia mam window_height 500?>

These two processing instructions set the width and height of the MAM window to 500 pixel each.

Preset MAM category

Furthermore, you can define which category should be opened, when calling the Media Asset Management. See Opening a Defined MAM Category.

Further Processing Instructions#

Using processing instructions, you can read out MAM variables values and store them in meta variables. You can use an arbitrary number of processing instructions in one MAM call. The order of the processing instructions is arbitrary as well.

Example:

<?imperia MAM command1 MAM_variable1:meta_variable1 MAM_variable2:meta_variable2?>
<?imperia MAM command2 MAM_variable3:meta_variable3 MAM_variable4:meta_variable4?>

The following commands are available as parts of the processing instructions:

mam copy: Coppying values in the meta variable

This command copies values from the MAM in a meta variable.

mam mcopy: Copying multiple value variables in meta variables

The mcopy command is an extension to the copy command, which can function also with multiple value variables (arrays). While copy transfers only the first value, the mcopy transfers all values.

Example:

<?imperia mam mcopy name:name width:img_width?>

mam prefilter: Setting an unchangeable filter

The command prefilter offers the possibility of displaying only particular assets in MAM. The following filter criteria are available:

directory=/desired directory Shows only assets located in the “desired directory” and its subdirectories. The path should be specified relative to the document root.
category=/desiredID Shows only assets, located in the category with “desiredID”.
category_recursive=/desiredID Shows only assets, located in the category with the “desiredID” and its subdirectories.
Metavariable=~search word Shows only assets, in which the meta variable matches the selected operator. The following operators are permitted: (<, <=, !~, =~, =). All imperia meta variables, available in the Global Meta Info, can be prompted.

Example:

<?imperia mam prefilter title=~imperia ?>

mam filter: Setting a changeable filter

The command filter offers the possibility of displaying only particular assets in MAM. The same filter criteria as in prefilter are available. The difference is that the user can additionally change the filter rules in the MAM.

mam directory: Preselection of a directory

This command specifies a category to open when the MAM is called. The user has the possibility to navigate out of it. To define the category use the category id or the directory name.

mam sortby: Sorting by a column

The command sortby followed by a MAM column name indicates the sorting criteria.

mam setsrc MAM variable : Meta variable : Imagename

This command sets the SRC attribute of the image Imagename to the value of the meta variable meta variable. Furthermore, the SRC attribute updates itself every time a user selects a new object from the Media Asset Management. For this purpose, a connection between the meta variables and the Media Asset Management variables (MAM variable) should be established.

Assignment pair MAM variable : Meta variable

With such an assignment pair, the value of a MAM variable is assigned and it can be further processed in a document. The assignment pairs consist of the name of the MAM variable and the name of the meta variable, divided by a colon. A processing instruction can include multiple assignment pairs.

Adjusting the Links in the MAM Call#

By default, the MAM call displays both a link to run the Media Asset Management, as well as a link to open the image upload. However, most of the time only the MAM or the image upload is used, and the other link would only confuse users.

Furthermore, it is sometimes useful to restrict the ability to upload files via the image upload.

In order to control which links should be shown in the MAM call, you have the following options:

for the entire system through the system.conf variable MD-DEFAULT-LINKS
via the meta variable __imperia_MAM_linkswitch
from the template with the processing instructions switchbyvalue or switchbyname

Please consider that the settings of the system configuration variable are overwritten by the settings of the meta variable __imperia_MAM_linkswitch. The settings of the meta variable __imperia_MAM_linkswitch is in turn overwritten by the processing instructions.

Configuration with a System Configuration Variable#

The following settings can be overwritten by all other settings.

Set the MD-DEFAULT-LINKS variable in the site/config/system.conf file. The following values are available:

none

Neither of the two links is displayed. The frame around the default image is not displayed and the image is not editable.

mam

Only the Assets link is displayed.

upload

Only the Uploadlink is displayed.

mam, upload

Both links are displayed. This is the default.

The variable is only assessed when it is set. If not, the default behavior is assumed.

Configuration with an imperia Variable#

In this variant, the imperia variable __imperia_mam_linkswitch that must be set in a document to the appropriate value, is evaluated. The system does not generate this variable automatically, it must be set either with a meta file or with a workflow step.

The values and their definition are identical to the ones of the MD-DEFAULT-LINKS variable.

Configuration with Processing Instructions#

Alternatively, you can also configure by:

1. Passing a value to a processing instruction

...through a value passed to the processing instruction.

This is done with the following syntax:

<?imperia mam switchbyvalue value?>

The possible values are mam and upload.

2. Adjustment by the value of a meta variable

...through a meta variable value set accordingly elsewhere.

This is done with the following syntax:

<?imperia mam switchbyname meta_variable_name?>

Indicate the meta variable name in place of Meta variable name. The value of this meta variable must be set elsewhere with mam, upload, remove or actions or with comma-sepparated combinations (for example mam, upload).

Important

The processing instructions switchbyvalue and switchbyname are mutually exclusive within the same MAM invocation.

Configuration of the image source set (srcset)#

You can enable the integration of images variants by using the HTML 5 attribute srcset. By that, the different variants (sizes) of an image are displayed as links in the MAM call, see following example:
variants of srcset
This will publish not only the original image but also its selected variants.

The srcset attribute is also used for resizing in imperia. In this case, the original image is resized to the resolution of the selected variant. During publishing, all variants will be published, too.

In order to insert the code in the MAM call, proceed as follows:

Note

The following codes are wrapped for better readability.

1. In the desired template enter the following code into the MAM call

<img src="IMPERIA:<img_meta_key>"
srcset="[IMPERIA[:<width>x<height>]:
<img_set_entry_meta_key_prefix> <instructions for the browser>]">

Example:

<img src="IMPERIA:img"
srcset="IMPERIA:600x300:size2 600w, IMPERIA:1000x300:size3 1000w">
<?imperia mam copy RETURNSIZE:200x100 ?>
</img>

2. When entering multiple srcsets, always include the following parameters

Executing a JavaScript Function During an Object Transfer#

When transferring an object from the MAM to a document, a custom JavaScript function can be executed. The default function is ACApplyValues.

In order to use this feature, you should proceed as follows:

Generate the file function name in the /imperia/md/develop/javascript/ directory. This file is automatically added to the main frame of the MAM window. The file must have the .js extension.

In this file, define a function with the same name as the file itself. This function is called by the Media Asset Management, after the asset to be added has been selected and edited.

The function must be entered in the value attributes of the form fields and in the src attributes of the img tags.

This function is passed as an argument to an array object whose elements are in turn array objects with three string elements. The sub-array format is as follows:

[TYPE,NAME,VALUE]

TYPE src is used with images and value with other objects. NAME defines the name of the form field, resp. the name of the img tags. VALUE defines the value transferred to the defined by TYPE attribute.

Example - let's assume that a template contains the following MAM invocation:

<img name="IMPERIA:my_width" width="100">
  <?imperia mam copy COPYRIGHT:copyright?>
  <?imperia mam function mymamFunction?>
</img>

This is transformed to the following function call:

mymamFunction([['src',
          'my_img',
          '/imperia/md/images/spiders/image_100x150.jpg'],
          ['value',
           'copyright',
           '2011, Cross Spider Co.']]);

The ACApplyValues function can be used as basis for your own functions. For this reason, this function can also be called from the revised function. But it also follows that the function name is a reserved name.

Opening a Defined MAM Category#

Use the following processing instructions in order to open a particular MAM category:

<?imperia mam directory /path/to/directory?>
<?imperia mam directory numerical directory ID?>

mam directory: path to the directory

The path to the directory is given starting from the document root.

Example:

<?imperia mam directory /images/marketing?>

When opening the MAM, /images/marketing is opened automatically.

MAM Variables#

Below you will find a list of all MAM variables that can be read from the Media Asset Management, using processing instructions. In addition to the names of the variables, the data type used is shown in brackets.

NAME (char(255))

This variable contains the name of an object, which is defined on upload or in the Changing Object Properties dialog. If the object has no name, this variable contains the filename without the extension.

DATATYPE (char (255))

This variable contains the data type which is determined by the file extension. If the object in question is, for instance, a JPEG image the variable contains the value jpg.

FILESIZE (int)

This variable contains the size of an object in bytes.

OBJURL (char (255))

TThis variable contains the URL of the Media Asset Management object starting from the server's document root directory.

PREVFILE (char (255))

This parameter contains a thumbnail's URL. In the case of a Flash4 film, it is, for example, the following URL: /imperia/md/defaults/icons/ico_flash4.gif.

PREVSRC (char(255))

This variable contains the URL of an object. It cannot be read out, but is merely used in conjunction with the keyword setsrc.

SELLPRICE (char(255))

This variable contains the value of the field SELLPRICE from the Changing Object Properties dialog.

VIEWPRICE (char(255))

This variable contains the value of the VIEWPRICE field from the Changing Object Properties dialog.

PLAYLENGTH (char(100))

This variable contains the length of a playable object, as an AVI file, a flash movie or similar. You can define it when uploading the object or in the Changing Object Properties dialog.

XRES (int)

This variable contains the number of horizontal pixels of an image. This is defined in the X-PIXEL field when uploading the object or in the Changing Object Properties dialog.

YRES (int)

This variable contains the number of vertical pixels of an image. This is defined in the Y-PIXEL field when uploading the object or in the Changing Object Properties dialog.

DPI (int)

This variable contains the resolution of an image. It is defined in the field DPI when uploading the object or in the Changing Object Properties dialog.

COPYRIGHT (char(255))

This variable contains the value of the COPYRIGHT field from the Changing Object Properties dialog.

UPLOAD_DATE (date)

This variable contains the date, on which an object is transferred in the Media Asset Management.

LASTMODIF_DATE (date)

This variable contains the last modification date of an object's properties.

COMMENT1 (char(255))

This variable contains the value of the COMMENT1 field from the Changing Object Properties dialog.

COMMENT2 (char(255))

This variable contains the value of the COMMENT2 field from the Changing Object Properties dialog.

Example: Thumbnail with Link to the Original Image#

A thumbnail with a link to the original image can be generated with the following code:

<input name="IMPERIA:myicon_url" type="hidden">
<a href="IMPERIA:MAM:mylink">
  <?imperia mam copy PREVFILE:myicon_url?>
  <?imperia mam setsrc PREVSRC:myicon_url:myicon_img?>
  <img name="IMPERIA:myicon_img" src="/imperia/md/defaults/icons/
  ico_smiley1.gif" />
</a>

In this example a user selects an image from the Media Asset Management. In the final document a thumbnail to this object is displayed. The thumbnail is linked to the original image.

First, the URL of the thumbnail from the Media Asset Management has to be read out and stored in a meta variable. This is done via a hidden input field (first code line in the example) and a processing instruction (third code line in the example). With the processing instruction the value of the MAM variable PREVFILE is read out and stored in the meta variable myicon_url.

Furthermore, you must set the href attribute of the link to the URL of the selected original image and the src attribute of the img tag to the URL of the thumbnail. This is done with the second processing instruction. When translated, this processing instruction roughly has the following meaning:

Place the href attribute of the a tags to the URL of the selected assets. At the same time, transfer the URL of the thumbnail of this asset in the src attribute of the img tags with the name myicon_img.

The example code can also be used for the generation of a download link. The img tag shows the icon, which is assigned to the object type (Flash, PDF, MPEG etc.) in the Media Asset Management.

Generating Image Variants#

imperia provides you the possibility to create and specify a name for an asset variant of the currently uploaded asset, using the Transform plug-in.

So you could, for example, generate a variant with a fixed name, using the Transform plug-in, when uploading an asset, and then initiate the generation of an imperia document that is referenced in the gallery via SiteActive.

    $metainfsetValues('gallery01_ready',1);
    # Create variant.
    my $asset_plugin = 'FitToSize';
    my $node_id = $metainfgetNodeID;
    require IWL::Stash;
    require Imperia::AC::Variant;
    my $params = IWL::Stash->new({action => $asset_plugin,
                                  display => 1,
                                  node_id => $node_id,
                                  __workflow => 1,
                                  width => 188,
                                  height => 133,
                                  last => '1'});

    my $loader = Document::Loader->new(id => $metainfgetNodeID);
    my $variant = Imperia::AC::Variant->new($node_id, $asset_plugin);
    $variant->initForWorkflow($loader);
        die "Error: " . $variant->errorSuck
            if $variant->bad;
    my $binfo = $loader->getBinaryMetaInfo() or  die $loader->errorSuck;

    my $doc_id= $node_id;
    $doc_id =~ s:.*/::;
    my $filename = '__image_'.$doc_id .'_preview.jpeg' ;
    $variant->create($params, undef, $binfo, $filename) or
        die ("Variant creation failed: ") . $variant->errorSuck;

The code above would generate a preview image_image_{id}_preview.jpeg in the desired size in the directory of the asset.