This concept is valid for ICM version 7.10.16 and higher. For previous versions see Concept - Image Framework (7.5 - 7.10.15).
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, for example, front view, back view, on model and neutral background. 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 with no available image 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 of an organization domain preference.
In the Commerce Management, image views can be managed by navigating to Master Catalogs | Image Management | Image Views. The following screenshot shows a list of image views. The right column can be used to define a view as the organization's primary view.
The following screenshot 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 screenshot shows the selection of a primary view on product level. If set to (Use Default Setting), the organization level's 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 etc. 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. Setting an external source type and defining an internal fallback image URL afterwards is not a valid use case. Image URL calculation will always fail in such a case.
In the Commerce Management, image types can be managed by navigating to Master Catalogs | Image Management | Image Types. The following screenshot shows a list of image types. The right columns show optional width and height information.
The following screenshot 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 by navigating to 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 screenshot 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 by navigating to (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 only works 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 the Commerce Management 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:
As far as the reuse of image type IDs is concerned, note the following:
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 in the Additional Images 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 under | Master Catalogs | Image Management | Image Types.
In the screenshot below, an example of an image type pointing to the organization's shared file system (L) is shown. The other example in the screenshot points 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 Image Source Path.
The channel product image upload can be found on channel level under 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 if this is the case, 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 Image Source Path.
For information on how to customize the product image upload location, refer to Cookbook - Image Framework.
The master product image upload can be found on organization level under 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 to assign them.
In the previous chapter, a detailed description on how to upload images was given. This section describes what happens in the storefront when rendering 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.
The following requirements are necessary:
This explains the specifics for localized images. Of course images for other image views and types must still be assigned.
If you only 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 fallback 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.
Uploading images is also possible here. But here also, the root location in the SFS is defined by the selected image-type prefix configuration!
In all previous ICM versions the image type used for catalog and category images was defined to be the image type ID 'M'. To change that in a project, it was necessary to change a pipeline, java code and templates. To make this more flexible, a configuration was introduced to select the category image type ID in the Commerce Management. The configuration is available for organizations and partner channels, as part of the image management - image type configuration and can be found on organization level under Master Catalogs | Image Management | Image Types.
Unlike for products, only one image can be assigned to categories. The image view used is the primary image view. The image type is defined by using the drop down menu mentioned in Configure an Image Type for Categories.
Catalog and category images are assigned in the General tab, by using the Select button.
The dialog behind that button cannot process all image types that can be selected in Configure Image Type for Categories.
The Select button that is used to assign catalog and category images has three different states: not visible, disabled and active.
If the image type is External or Internal with an empty prefix (2b+2c), the image name input field is active and an image name can be entered and saved by using the Apply button.
The tooltip appearing on mouseover provides information on how to solve the problem.
The tooltip appearing on mouseover provides information on how to solve the problem.
The demo storefront ISML-templates use the image types S and L for small and large as well as a few M product images. The image type M is mainly used for category images. As described in Image Source Paths, the prefix of an image type defines the location of the image and its size. Allowing the internal image type prefix to be empty makes the location of the image within the shared file system flexible. This means that images can come not only from the organization, but also from the channel shared file system. It is also possible to restrict access to the images of the organization and to force the user to use channel images only. This can all be done without changing the storefront templates and their specific image types used. See Usage of Product Images and Cookbook - Image Framework, Recipe: Customizing the Product Images ImageType and ImageView for details.
For the configuration a new image type in the image management needs to be created. Furthermore, the source must be set to internal and the prefix left empty.
Having an empty prefix is only possible for the image management on organization level and does not work for the partner channel. The reason for this is that a partner channel has partners which have their own image management. In the partner's Commerce Management empty prefixes are allowed as well.
Product images assigned to this image type will store the prefix information with the image name, for example:
Assigning category images with an empty prefix by using the Select button is not possible. The assignment can be done by entering something valid as image name and confirming with the Apply button. For example, you have to enter something like: inSPIRED:/M/0027242869158_Back.jpg - like the empty prefix image name above.
The import and export functions support the new configuration. The differences are described in this section. See Import and Export for more details.
For the image type the prefix is left empty.
<image-type id="L_empty_prefix" source="Internal"> <name xml:lang="en-US">L_empty_prefix</name> <prefix></prefix> <width>500</width> <height>500</height> <fallback-image>inSPIRED:/not_available.png</fallback-image> <custom-attributes> <custom-attribute name="name" dt:dt="string" xml:lang="en-US">L_empty_prefix</custom-attribute> </custom-attributes> </image-type>
For the product image import the image base name attribute simply has the domain in front of the regular image base name.
<image-ref image-view="front" image-type="M" image-base-name="M/7918683-8271.jpg" domain="inSPIRED-MasterRepository" /> <image-ref image-view="front" image-type="L_empty_prefix" image-base-name="inSPIRED-inTRONICS:/L/L_201807194_side.jpg" />
The product image assignment can be done under (Master) Catalogs | Products on the General tab at the bottom in the Additional Images section. After having chosen an image view and image type (with an empty prefix), the '...' button is activated. By clicking on it, the Select Image dialog allows to select an image for the product.
Only in the Select Image dialog on channel level an additional drop down box is available. It allows to select what the prefix configuration was holding before and still holds for regular prefix configurations. This drop down box lets you chose the location in the shared file system where the images to be assigned come from. Usually, the organization or the channel can be chosen, for example inSPIRED and inSPIRED-inTRONICS.
The resulting image assigned will look like the following example: inSPIRED:/L/232455353_front.jpg or inSPIRED-SalesChannelB2C:/S/932875353_back.jpg. If an image type with an empty prefix was chosen for category images, the entered image reference has to look like these examples when the image is getting assigned to a category.
On organization level under Master Catalogs | Image Management on the Image Settings tab it is possible to grant or revoke access to the images of the organization for individual channels.
This only affects images for which image types with an empty prefix were chosen. In the drop down box mentioned in Concept - Image Framework#Assignment only the channel will be available, not the organization (no access).
However, this does not affect previously assigned images.
This configuration supersedes the Recipe: Customizing the Product Image Upload Location.
Product images on channel level can be uploaded under Catalogs | Import & Export | Product Image Upload. In the Product Image Upload dialog, there is an information box which shows the product image directory location (channel or organization). It also shows already existing images and sub-folders.
The channel preference Image Settings allows to configure the location where images are uploaded to, by using the radio buttons in the Product Image Upload dialog. The options are organization or channel, unless the acces to the images in the organization has been revoked, see Granting/Revoking Access to Images from the Organization. In this case an information box describes the access restriction and that only channel images can be assigned. This does not affect previously assigned images.
The Product Image Upload dialog allows to upload images, delete images and create folders for images. These images can then be assigned to products or categories. The configuration defines at which location in the ICM server shared file system the images are uploaded to (beneath the organization folder or the channel folder).
The alt attribute of an image tag is SEO relevant. This feature allows more flexibility to define the value of the
<img alt=""> attribute.
The template module
ISProductImage contains the logic which defines the content of the
alt attribute, resulting into something like
<img src="some-image.jpg" alt="some-image-alt-content">. The template module's location is a_responsive\app_sf_responsive\staticfiles\cartridge\templates\default\modules\product\ProductImage.isml. In the demo storefront the
ISProductImage module is used for all product images on display.
<ISProductImage AltText="some-image-alt-content" ProductBO="#ProductBO#" ...> module has an attribute
AltText. The content in the
AltText attribute defines the
alt="" attribute's value from the outside, everytime the
ISProductImage module is used in other templates. Any logic inside the module defining the
alt="" attribute does not have any effect on the
<img src="" alt=""> created by the module. As can be seen in the demo store templates, only one template (inc\product\variation\PresentationSwatchImage.isml) uses the
AltText attribute under certain conditions.
AltText attribute of the
ISProductImage module is not defined, a module-internal logic defines the
alt="" attribute's value. It uses the
ProductBO:Name and a fixed text as prefix to define it. The fixed prefix localization key is
product.image.text.alttext and its current value is
product photo. This results into something like
alt="ISH Laptop xyz product photo", with
ProductBO:Name="ISH Laptop xyz". This option is most commonly used in the responsive demo store.
The internal logic of option 2 was extended to additionally consider the custom attribute named
ImageAltText to be defined for each product. If the product custom attribute named
ImageAltText does not exist, the logic falls back to its default behavior as in option 2.
A new java extension for the
ProductBOSeoExtension was created to obtain the value for the
alt="" attribute. This extension also allows to create a custom implementation, to do something different for the methods used in the
ISProductImage module. Methods used in the module are
(ProductBO:Extension("Seo"):ImageAltTextByCurrentLocale). The extension interface is f_business\f_sales\sld_ch_b2c_base\src\main\java\com\intershop\sellside\appbase\b2c\capi\product\seo\ProductBOSeoExtension.java. If the
ProductBOSeoExtension methods called in the
ISProductImage module return
null, it falls back to its default logic described in chapter Current Default Behavior. If the module calling template provides a
LocaleInformation object, it can be called as shown here:
<ISProductImage ProductBO="#ProductBO#" ImageType="L" Class="ish-product-image" Locale="#RequiredLocale#">
Locale available, the extension extracts the localized attribute value, based on the given
LocaleInformation object passed. Otherwise it uses the locale passed with the current request.
The implementation of the extension performs three steps to extract the value:
The configuration only works if the
ISProductImage module does not use its
AltText attribute while it is called within other templates. This feature works by reading a product custom attribute named
There are a few options how to use this feature:
<img alt="">value for any language.
<img alt="">will be different for each locale.
Product images are used in the demo store storefront. CMS Components use product images for product list views after a search or while browsing through a catalog and in the product detail page. The image types used for those product pages are hard-coded in multiple templates. With the current demo store code, content pages and components, changing image types are used, which means also changing the ISML templates in question. A scenario describes the necessary template modifications in the Cookbook - Image Framework.
The 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.
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.
The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.