Skip to content

Upload template

In this chapter you will learn how to create an upload template for a media category.

Configuration of the media category#

Each media category requires an upload template, which is specified when configuring the media category.

In the site/sample/templates directory, you will find three sample templates that you can use as a guide when creating your upload template: upload-minimal.htms, upload-advanced.htms and upload-expert.htms.

Structure of the upload template#

Before imperia 11.4, an upload template in imperia always required the instructions <!--upload_start--> and <!--upload_end--> to mark the upload field. These instructions are no longer necessary. A minimal upload template that only includes the title currently looks like this:

<!DOCTYPE html>
<html lang="de">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Upload files</title>
</head>
<body>
<!--template-description:Upload Minimal-->
<!--formstart-->

  <?imperia asset_data
    name: title
    label: Title
    source: *:headline,*:title,*:objectname
    hint: Under this title you will find the file in the CMS.
  ?>

<!--formend-->
</body>
</html>

Description of media content#

A good description of media content is a central topic in content management in many fields, but one that is often only given attention afterwards. Well-described media content is an important building block for accessibility and for the search engine's ability to find the content. Mandatory legal information such as the copyright notice is part of the basics of labeling media content.
Many media have established formats for recording metadata. For images in particular, there is a wide range of standardized metadata formats, such as EXIF, XMP or IPTC. Especially if the images come from a picture agency, they usually already contain a description text, a title and a copyright notice.
Professional photographers often at least maintain the legal information on copyright and authorship. However, some editorial offices also use external media management systems to centrally record media metadata.

Depending on the origin of your media, there is a good chance that a media file already contains a lot of interesting information that can be used editorially. Since imperia 11.4, the metadata can now be read from the media in a very user-friendly way when uploading and used internally.

But media metadata can also be a security risk. Confidential information stored via the metadata in your media can inadvertently become public when a website is published. Since imperia 11.4, you can clean up your media on a large scale during upload and preserve only safe information.

Processing instruction asset_data#

In templates that are used as upload templates in media categories, there is now a processing instruction ("PI" for short) with the name asset_data. You may also be familiar with PIs from other contexts, such as the PIs <?imperia mam?> or <?imperia iwe2?>.

The PI <?imperia asset_data?> has various tasks. The main task is to generate special input fields or text areas that are extended for the use of file metadata.

Example of an input field for entering the title of the file:

 <?imperia asset_data
    name: title
    label: Title
    source: *:headline,*:title,EXIF:XPTitle,IPTC:ObjectName
    hint: Under this title you will find the file again.
    required: 0
    set: EXIF:XPTitle,IPTC:ObjectName
  ?>

The source option is used to search the specified field names of various metadata formats, such as EXIF, XMP or IPTC, and make them available to this field.

The syntax *:fieldname means that all available metadata formats are searched. Alternatively, you can also explicitly specify a format (iptc:fieldname).

Option Description Example
source This parameter is used to read the metadata list and make the results available to the input field. source: IPTC:ObjectName
name Parameter for specifying the meta info variable in which the entered value is saved. name: title
label The label of the input field or text area is specified in this parameter. label: Title
hint This parameter is used to specify the help text that is displayed below the input field or text area. hint: You will find this file under this name in the Media Manager.
no_autofill You can use this parameter to prevent the automatic pre-filling of content from the image metadata. no_autofill: 1
set You can use this parameter to write the entries back into the asset's metadata. set: EXIF:XPTitle
required You can use this parameter to determine whether the field must be filled in to complete the upload required:1

Set, delete or preserve media metadata#

With the PI asset_data, media metadata can not only be used for editorial support, the media metadata can also be cleaned during upload. This gives you control over which metadata is displayed in your published media.

There are three parameters for managing the media metadata: set, delete and preserve. The set parameter has already been mentioned above. It is used to write the editorial content back into the metadata. The set parameter has the highest priority. All content that is set via an asset_data input field with the set option is written to the metadata of the respective image, regardless of the deletion settings.

With the other two options delete and preserve you can control which of the existing metadata should be deleted.

As the list of metadata fields is very long and can be extended, we recommend the following procedure to ensure that you have effective control over the published metadata.
First select all metadata fields for deletion using the delete option and then exclude the metadata fields that you want to preserve from this solution using the preserve option. You do not need to preserve the fields that you set directly elsewhere with set. These are generally excluded from deletion.
If you use the following PI options in your upload template, all image metadata will be deleted on upload. Exceptions to this are the two copyright details of the image metadata formats Exif and IPTC as well as all image metadata that was explicitly set elsewhere via set.

<?imperia asset_data 
delete: *:*
preserve: EXIF:copyright, IPTC:CopyrightNotice
?>

Please note, however, that all metadata formats automatically set some information from the image, which means that they cannot be deleted.

Upload templates by file type#

You can also use conditional statements to load different templates, i.e. different input fields, for different file types. An input that makes sense for image files does not necessarily also make sense for PDF documents.
The distinction is made at the level of the individual input fields by conditional statements (IF, ELSIF, ELSE), as you know it from the imperia template language. The function with which the temporarily uploaded file can be evaluated is called XX-ASSET. And this is how you use the function in a conditional statement:

#IF ("<!--XX-ASSET(File:MIMEType):1-->" REQ "^image\/")

All input fields for image files

#ELSIF ("<!--XX-ASSET(File:MIMEType):1-->" REQ "^application\/pdf$")

All input fields for PDF documents

#ELSE

All input fields for other file types

#ENDIF

Your own input fields#

In many cases, you want to combine your own input fields and fields generated by the PI asset_data. To ensure that all fields have the same layout, use this HTML structure for your own fields:

   <div class="custom_asset_field_group">
        <label for="copyright">Copyright</label>
        <input name="IMPERIA:copyright" id="copyright" class="i-custom-field" type="text" />
         <span class="hint">Firstname Last name, source</span> 
    </div>

Restriction of accepted file types and sizes#

The metavariable must contain a valid JSON object. The supported restrictions in the form of JSON keys are: You can use the __imperia_upload_restrictions metavariable to set restrictions for a category on accepted file types and sizes
. This makes it easier to control which assets can be uploaded to a category and thus ensure system and user security as well as the integrity of the media library.

This is supported by a mechanism that checks files that have already been uploaded and validates the assets after the upload.

Die Metavariable muss ein gültiges JSON-Objekt enthalten. Die unterstützten Einschränkungen in Form von JSON keys sind:

  • max_size: <number in KB>
  • min_size: <number in KB>
  • allowed_filetypes: <array of mimetypes that can be uploaded>

Example for a JSON object:

{
    "max_size":3550,
    "min_size":2000,
    "allowed_filetypes":[
        "png",
        "image/jpeg"
    ]
}

Re-importing an existing media file

  • If upload restrictions have been set for a category when re-importing an asset, these will NOT be applied to the re-imported asset.
  • When the asset is replaced, the newly uploaded file is validated with the checks before and after the upload.

Note on the old direct upload via drag-and-drop#

Before imperia 11.4, there was a tabular direct upload that uploaded assets directly to the selected category bypassing the workflow. This direct upload is still available in a modified form.

So if you still want to upload files directly to a category without an intermediate step and well-maintained titles, copyright notices and alternative texts do not have priority in your scenario, you can activate this alternative upload in the system configuration using MAM_ENABLE_INSTANTUPLOAD = 1.

And of course, additional fields can still be activated here, but only to the limited extent that was possible before imperia 11.4. Additional input fields can be added in the system configuration via MAM_INSTANTUPLOAD_FIELDS = title:Title:1,copyright:Copyright:1. Several fields can be entered separated by commas. Each input field requires the specification of three values: meta field name (e.g. title), description (e.g. title) and mandatory field (e.g. 1).