This document gives a high-level overview of the Image Framework. Media resources need to be administrated in the context of a product or any other business object. Furthermore, it is important to abstract away from the direct binding between images required to present an object and the low-level lookup of physical resources. The Image Framework aims to solve these issues.
From a customer's perspective, the Image Framework is mostly invisible. As with all types of content, a wide range of page components is used to actually show images on the front end. For further details on page components see Concept - CMS - Overview.
The Image Framework has three core tasks:
a person using the shop front end to browse for or buy products
a person logged in to the Commerce Management with permissions to change product data
The Image Framework brings along four new objects: image views, image types, image set definitions and images as such. All these objects are written to the persistence layer. In addition, there is a business object which only exists in memory: the image container. However, it is not a value object. It has an identity as it embodies a container of images bound to a specific image reference holder.
Real world object
Image Set Definition
The different image business objects are managed by their corresponding repository. Business object extensions are used to manage the assignments of images to other business objects.
An image view embodies the view or way an object has been photographed, painted or otherwise recorded. Typical image views are front view, back view, on model, neutral background and so on. The image view is simply an extensible object owning an ID as well as a localizable name and description stored on organization level. An infinite number of image views can exist for an organization. An image view can be assigned to one or more image types.
A primary image view can be defined on organization or product level. The idea is to define one image view which is shown whenever nothing special is requested. This way a page component can show a product image without knowing any details about the views actually available.
There might be a product where no image is available for the view defined as organization primary. This is where the product level primary view comes into play. It offers a simple way to overwrite the global setting for the product at hand.
The organization's default image view is organization data rather than image view data. The information is not part of the image view table but an organization domain preference.
In the Commerce Management, image views can be managed navigating to the following path: Master Catalogs | Image Management | Image Views. The following picture shows a list of image views. The right column can be used to define a view as the organization's primary view.
The following picture shows an image view detail page in the Commerce Management. A check box is available to set or unset the view as the organization's primary view. Several image types are assigned to the view.
The following picture shows the selection of a primary view on product level. If set to (Use Default Setting), the organization level primary view will be used.
An image type embodies the technical representation of an image. Representation parameters are image file path, image resolution, mime type etc. Typical image types are thumbnail, large, zoom, external and so on. The image type is simply an extensible object owning an ID, a source type, a prefix and also a localizable name and description stored on organization level. Additional information can be provided optionally. An infinite number of image types can exist for an organization. An image type can be assigned to one or more image views.
The attributes Source and URL Prefix need further explanation. Currently, two source types are available: Internal and External. An internal image is stored in the shared file system. In addition, there is now a new external type. It allows to point to all kinds of external resources. To do so the prefix attribute is required. It defines the address of the external server to be asked for an image. A typical prefix for external images could be http:// images.inspired.com/S.
For internal images the prefix simply defines the site or domain where the image can be found. A typical prefix for internal images could be inSPIRED:/. In both cases the remaining part to address a specific image comes from the corresponding image object. The image object is described later.
There is only one source type setting per image type. Therefore, the source type Internal / External defines the calculation of the regular and fallback image URLs. It is no valid use case to set an External source type and define an internal fallback image URL afterwards. Image URL calculation will always fail in such a case.
In the Commerce Management, image types can be managed navigating the following path: Master Catalogs | Image Management | Image Types. The following picture shows a list of image types. The right columns show optional width and height information.
The following picture shows an image type detail page in the Commerce Management. Note that you can easily define custom attributes for an image type in case you need to save additional information.
An image set definition represents a group of images. More formally, this is a group of pairs consisting of a specific image view and a specific image type. It is an extensible object owning an ID as well as a localizable name and description stored on organization level. For an organization, an infinite number of image set definitions can exist.
A specific image is defined by image view and image type. For example, when viewing the wishlist of a customer, a small thumbnail (image type S) showing the front view of the product should be displayed for each list item. To get the actual image, we would need to ask for an image of view front view and type S.
The image view and type pairs can be stored in a defined order. This way, for example, we can ensure that the front end is able to show a list of alternate images always starting with the front view. It is also possible to flag images as mandatory or optional.
Image set definitions can be assigned to classification categories. The motivation behind this is to define a set of images for all products which are specifically classified. Let's say we have a classification category named "fashion". We can now create a set definition called fashion and assign two image view and type pairs:
This way, we are able to define that a fashion product always needs to offer the defined set of images. But there is more: an infinite number of definitions can be assigned to a classification category. Moreover, all those image set contents of image sets are merged together that are assigned to some node of the tree path leading to the node a product is assigned to. Also, a product can even be assigned to more than one classification category.
In the Commerce Management, image set definitions can be managed navigating the following path: Master Catalogs | Image Management | Image Sets. The following diagram shows the interplay of image set definitions, image type view pairs, classification categories and products. The example product Runner AirGuard Pro has image requirements for all image type view pairs shown on the right. Some requirements come from direct image set assignments (Shoes, Lining) to the classification category the product is assigned to (Shoes). However, most requirements are inherited from an indirect assignment to a parent node in the classification tree (Fashion).
The following picture shows an image set definition detail page in the Commerce Management. The set definition has three view and type pairs assigned to it and is assigned to one classification category.
An image embodies a physically existing image. It belongs to a defined image view and image type and holds a path to an image resource. The current implementation binds an image to exactly one specific object. For example, there could be an image of view front view and type S assigned to a product sku_123 and a path pointing to a physical image sku_123_front_S.jpg. The name of the physical image is saved at the image object in an attribute called
imageBaseName. Together, the image type prefix and the image base name form the full path to a specific image. Example: A prefix http:// images.inspired.com/S plus a base name sku_123_front_S.jpg results in a path http:// images.inspired.com/S/sku_123_front_S.jpg.
In addition, an image can have values for width and height.
In the Commerce Management, images can be added or removed from products navigating to the following path: (Master) Catalogs | Products | General. The following picture shows the General tab of the product detail page. Image sets and additional images can be managed here. Also note the primary view select box below the product's long description.
Image data are imported or exported as part of the regular product import or export. The example snippet below is taken from the inTRONICS demo data:
<product sku="3740178"> : <images> <image-ref image-view="side" image-type="S" image-base-name="S/3740178_2813.jpg" domain="inSPIRED-MasterRepository" /> <image-ref image-view="back" image-type="S" image-base-name="S/3740178_2509.jpg" domain="inSPIRED-MasterRepository" /> <image-ref image-view="front" image-type="S" image-base-name="S/3740178-1748.jpg" domain="inSPIRED-MasterRepository" /> : </images> : </product>
A separate import/export exists for the image metadata:
: <image-view id="front" primary-view="true"> <name xml:lang="en-US">Front View</name> <image-type-assignments> <image-type-assignment image-type="S"/> <image-type-assignment image-type="L"/> : </image-type-assignments> </image-view> : <image-type id="S" source="Internal"> <name xml:lang="en-US">S</name> <prefix>inSPIRED:/</prefix> <width>110</width> <height>110</height> <fallback-image>inSPIRED:/not_available.png</fallback-image> <custom-attributes> <custom-attribute name="name" dt:dt="string" xml:lang="en-US">S</custom-attribute> : </custom-attributes> </image-type> : <image-set id="ElectronicsImageSet"> <name xml:lang="en-US">Electronics Image Set</name> <type-view-assignments> <type-view-assignment image-view="front" image-type="S"/> : </type-view-assignments> </image-set> :
Uploading images into the shared file system works only for image types with source set to Internal.
Image types with source set to External point to an external CDN image server (e.g.: akamai). Uploading images there is not part of our back-office UI.
Uploading an image to a shared file system folder can be done in several places:
The exact location of an image in the shared file system is defined by:
The image type ID must be unique to each. But can be reused for either.
The image management for the organization and for each partner beneath the partner channel uploads images in their corresponding shared file system folders.
By selecting the Browse button, the user can select an image to be uploaded into the selected folder beneath the selected locale.
An image can be uploaded at the Additional Image section within a product. Therefore the product must be locked.
Two things define the location where the images get uploaded to and which previously uploaded images get displayed for selection:
The image type chosen right before
The chosen locale
The following section shows the locations of the images to be uploaded and/or to be displayed for selection.
The image types available in this image upload dialog are configured in the organization or partner organization | Master Catalogs | Image Management | Image Types.
Below is an example of an image type pointing to the organization's shared file system (L) and another pointing to the channel's shared file system (L_channel).
The image type ID does not always reflect where its prefix points to:
The locale in the Image Upload context can be changed. This also changes the image upload location in the shared file system, see locale_specific_upload.
The channel product image upload can be found at channel level at Catalogs | Import & Export | Product Image Upload.
By using the channel product image upload, new images will be uploaded to the channel's shared file system.
The prefix of an image type has to match the image upload location! Only then the previously uploaded image can be assigned to an ImageReferenceHolder! (e.g.: Product ,Category, ...)
The locale in the Product Image Upload context can be changed. This also changes the image upload location in the shared file system, see locale_specific_upload.
For information on how to customize the product image upload location, refer to Cookbook - Image Framework.
The master product image upload can be found at organization level at Master Catalogs | Import & Export | Product Image Upload.
New images will be uploaded to the organization's shared file system, the UI is identical to the one for the channel image upload though.
To select the image during product image assignment an image type with prefix related to the organization has to be selected to see the uploaded images and assign them.
Uploading images was described in the previous chapter in detail. This section describes what happens in the storefront to render an image URL.
The image source used in the storefront templates is compiled of several pieces.
The final image URL looks like this: https://localhost/INTERSHOP/static/WFS/inSPIRED-inTRONICS-Site/-/inSPIRED/en_US/L/5847643-7702.jpg
If you just upload and assign a product image for a locale which is not the lead locale, the image will only be available for the locale it is uploaded for. The fall back to the lead locale will not work unless you upload an image with that same name into the lead locale folder and matching sub-folder as well.
This way all other locales get the image uploaded to the lead locale and only one image is specific to the explicit locale.
A scenario describes the necessary template modifications in the Cookbook - Image Framework.
Current implementation allows to assign images to products and catalogs. This assignment can easily be extended. Each object to which images are to be assigned must implement the ImageReferenceHolder interface. Image reference holders can provide the images assigned to them and can have a different primary image view than the one set for the organization.
Following the idea of loose coupling, all high-level image functionality is not hard-wired to the product or catalog business objects but is accessible through an image extension. This extension again provides an image container. The image container is the best option for dealing with images assigned to a specific object. It abstracts away from all low-level persistence layer operations. It is used for managing the image references assigned to a specific object.
Several extension scenarios are described in the Cookbook - Image Framework (7.6 - 7.10.15).
All of the business objects discussed above use extensible objects internally. This means, custom data can be attached to each of them. Later on, these data can be processed by customized pipelines and templates.
All business object interfaces and implementations and their corresponding repositories are wired together using the Component Framework. This way, every single brick of functionality can easily be replaced or extended.