Introduction

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:

• Allow the management of image objects in the Commerce Management by a product manager
• Import or export image data as part of the product import or export
• Provide mechanisms to make the page component layer look up the right image at the right time

Glossary

References

• Cookbook - Image Framework

Image Management

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.

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.

Image Views

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.

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.

Image Types

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.

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.

Image Set Definitions

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:

• Front view @ S
• Back view @ S
• Front view @ L
• Back view @ L

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.

Images

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.

Import and Export

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>
        :

Image Upload - Shared File System

Uploading an image to a shared file system folder can be done in several places:

• On organization level (1):
  • Master Catalogs | Image Management, see Image Upload via Image Management
  • Master Catalogs | Products | <Productname> | Additional Images section in the General tab, see Image Upload Before Assigning a Product Image
    
  • Import & Export | Product Image Upload, see Image Upload via Master Product Image Upload
• On channel level (2):
  • Catalogs | Products | <Productname> | Additional Images section in the General tab, see Image Upload Before Assigning a Product Image
  • Catalogs | Import & Export | Product Image Upload, see Image Upload via Channel Product Image Upload

The exact location of an image in the shared file system is defined by:

1. The selected channel or organization - depends on:
   • The context in the UI (the chosen channel or organization Commerce Management), or
   • The image type selected (its prefix settings - which select a channel or the organization)
2. The selected locale ID
3. The folder structure below, which can be created individually by the Commerce Management user

Image Upload via Image Management

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.

• The selected locale defines the locale ID folder name below:
  e.g.: \server\share\sites\inSPIRED-Site\1\units\inSPIRED\static\en_US\L
  
  

• By selecting a different locale, e.g., German, the target folder for uploading images changes, too:
  e.g.: server\share\sites\inSPIRED-Site\1\units\inSPIRED\static\de_DE
   

Image Upload Before Assigning a Product Image

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.

Image Upload via Channel Product Image Upload

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.

For information on how to customize the product image upload location, refer to Cookbook - Image Framework.

Image Upload via Master Product Image Upload

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.

Image Source Path

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 image type defines the general source in the shared file system defined by the prefix configuration.
  
  • inSPIRED:/ gets resolved to https://localhost/INTERSHOP/static/WFS/inSPIRED-inTRONICS-Site/-/inSPIRED - e.g.: Image-Type-ID: 'L'
  • inSPIRED-inTRONICS:/ gets resolved to https://localhost/INTERSHOP/static/WFS/inSPIRED-inTRONICS-Site/-/inSPIRED-inTRONICS - e.g.: Image-Type-ID: 'L_channel'
  
• The second part is the subfolder in the shared file system defined by the LocaleID used in the URL, e.g.: en_US/
  • The locale in the Image Upload context can be changed. This also changes the image upload location in the shared file system.
  • The screenshots below show different folder structures existing beneath the locales English (en_US) and German (de_DE).
  
• The third part is the image reference assigned to a product per image view and image type, e.g.: L/5847643-7702.jpg .
  
  

The final image URL looks like this: https://localhost/INTERSHOP/static/WFS/inSPIRED-inTRONICS-Site/-/inSPIRED/en_US/L/5847643-7702.jpg.

Requirements for Localized Images

The following requirements are necessary:

• A full set of pictures in the lead locale's shared file system directory, since there is a fallback that redirects locale-specific images to the lead locale images.
  This ensures that there is always an image available if the shop supports different locales.
• Only where a locale-specific image (other than the lead locale) is required, it should be uploaded by switching to the locale, e.g., German, before uploading, see Image Upload via Image Management.
  • Make sure that the folder structure and the file name match the image of the lead locale. This way the existing assignment works for the localized image as well.
  • This is true for all assigned product images and also for the fallback image defined for each image type.
• Assigning images to products in the Commerce Management must be done only once for the images of the lead locale.
  
  • The assigned and then stored image reference does not contain the locale ID folder.
  • In the storefront, the localized part of the image URL gets switched by the LocaleID (e.g., en_US or de_DE) in the URL of the current request, see Image Source Paths.
  • In case no image with the name and no image-type-specific sub-directory exists, a fallback to the lead locale image is performed.

This explains the specifics for localized images. Of course images for other image views and types must still be assigned.

Product Image Assignment

Chose Image View and Image Type

• The product image assignment in Intershop Commerce Management can be done below the 'General' tab of a product detail page.
• Link/Breadcrumb: inSPIRED - Master Catalogs - Products - <product name> - General
• To assign a product, 1st an available image view and 2nd an available image type must be selected. See screenshot below:

Image Select Buttons

• Once the image type is selected, the 'image select' button (1) '...' is active. See screenshot below:

• The 'image select' buttons (1), (2), (3) open a dialog where images can be selected.
• By clicking 'OK' in the 'select image' dialog, the image can be assigned to the product for the chosen image view/image type combination.
• Only one image per image view/image type combination can be assigned for each product!
• 'image select' buttons:
  
  • (1) - Opens a dialog to select a new image
  • (2), (3) - Opens a dialog, to select a different image for the image-view/image-type combination.

Image Select Buttons - Location in (SFS)

• 'Image-Select' buttons: - and the location in Shared-File-System(SFS)
  
  • The location in the SFS where the image can be selected depends on the 'prefix' configuration of the selected image type.
  • Hence, clicking the 'image select' button (1) or (2) will lead to the SFS sub folder for the 'inSPRED' organization.
  • Clicking the 'image select' button (3) will lead to the SFS sub folder for the 'inSPRED-inTRONICS' channel.
  • See the image types configuration of the image management below:

Select Image Dialog

• 'Image select' button (1) or (2) will lead to the 'Select Image' dialog (4)
  • It shows the sub-folder structure belonging to 'inSPIRED' organization.
• 'Image-Select' button (3) will lead to the 'Select Image' dialog (5)
  • It shows the sub-folder structure belonging to 'inSPIRED-inTRONICS' channel.

Configure an Image Type for Categories

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.

Category Image Assignment

Description

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.

 Select Button State

The Select button that is used to assign catalog and category images has three different states: not visible, disabled and active.

• The Select button is not visible in the following cases:
  
  • The Commerce Management user does not have the permission to manage catalog and categories.
  • A channel uses a shared catalog. For a catalog shared from an organization to a channel, data located in the General tab cannot be modified.
    
• The Select button is disabled in the following cases:
  
  • In the category image type selection no image type is selected.
  • In the category image type selection an image type with source=External is selected.
  • The category image type selection has an image type with source=Internal and the image type prefix with an empty string.
    

  • 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.

    Note

    The data entered in the image name input field is not validated.

The tooltip appearing on mouseover provides information on how to solve the problem.

• The Select button is active if the category image type selection is an image type with an internal image source and the prefix has a valid domain, e.g., 'inSPIRED:/' or 'inSPIRED-inTRONICS:/'.
  

Image Type with Empty Prefix

Intentions

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.

Configuration

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.

Effect on Image Assignments

Product images assigned to this image type will store the prefix information with the image name, for example:

• Image type prefix for a regular prefix: inSPIRED:/ and image assignment image name: S/0027242869158_1.jpg
• Image type prefix for an empty prefix: left empty and image assignment image name: inSPIRED:/S/0027242869158_1.jpg
  

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.

Import and Export

The import and export functions support the new configuration. The differences are described in this section. See Import and Export for more details.

Image Type Import

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>

Image Import During Product Import

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" />

Product Image Assignment with Empty Prefix Image Type

Location

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.

Assignment

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.

Also see Configure an Image Type for Categories and Effect on Image Assignments.

Granting/Revoking Access to Images from the Organization

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.

Image Upload Location for Product Images of the Channel

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.

Configuration (Preference)

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.

Description

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).

Defining Product Image Alt Attribute for SEO

Intentions

The alt attribute of an image tag is SEO relevant. This feature allows more flexibility to define the value of the <img alt=""> attribute.

Current Default Behavior

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.

Option 1

The <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.

Option 2

If the 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.

Option 3

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.

Extended Module for Option 3

A new java extension for the ProductBO called 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 getImageAltTextByLocale(LocaleInformation) and getImageAltTextByCurrentLocale()  (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#">

With the 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:

• Localized value (given locale parameter or current request locale),
• Localized value, fall back to lead locale,
• Fall back to the non-localized variable with the same name.

Configuration of the Product Attribute for SEO Alt 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 ImageAltText.

There are a few options how to use this feature:

• Not having any attribute with that name as product custom attribute
  In this case it falls back to the previous logic as explained in Current Default Behavior.
• Creating or importing a non-localized attribute with that name
  This attribute is used as <img alt=""> value for any language.
• Creating or importing a localized attribute with that name for several or all locales available in the system
  In this case, the following has to be considered:
  
  • Create at least a localized value for the lead locale of the system.
  • The <img alt=""> will be different for each locale.
  • In case no value is available for the current request locale, the lead locale value will be used instead.

Usage of Product Images

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.

Image Assignments

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.

Extending Functionality

Several extension scenarios are described in the Cookbook - Image Framework.

Persistence Layer

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.

Business Object Layer

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.