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 (7.6 - 7.10.15)

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

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.

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

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.

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

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

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):
  • Image Management: Master Catalogs | Image Management, see upload_image_management
  • Additional Images section within a product: Master Catalogs | Products | <Productname>, see image_upload_product_page
    
  • Product Image Upload: Master Catalogs | Import & Export | Product Image Upload, see organization_image_upload_impex
• On channel level (2):
  • Additional Images section within a product: Catalogs | Products | <Productname> see image_upload_product_page
  • Product Image Upload: Catalogs | Import & Export | Product Image Upload, see channel_image_upload_impex

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 back-office), or
   • The image type selected (its prefix settings - which selects a channel or the organization)
2. The selected Locale ID
3. And the folder structure below which can be created individually by the back-office 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 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.

Image Upload via Channel Product Image 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.

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

Image Source Path Explained

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.

1. The image type defines the general source in the shared file system defined by the prefix configuration.
   
   1. inSPIRED:/ gets resolved to: https://localhost/INTERSHOP/static/WFS/inSPIRED-inTRONICS-Site/-/inSPIRED - e.g.: Image-Type-ID: 'L'
   2. inSPIRED-inTRONICS:/ gets resolved to: https://localhost/INTERSHOP/static/WFS/inSPIRED-inTRONICS-Site/-/inSPIRED-inTRONICS - e.g.: Image-Type-ID: 'L_channel'
   
2. 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 a different folders structure exist beneath the locale English (en_US) and German (de_DE).
   
3. 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

• Have 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 then the lead locale) is required, it should be upload_image_management.
  • Make sure the folder structure and the file name matches the image of the lead locale. So the existing assignment works for the localized image as well.
  • This is true for all assigned product images and also for the image_type_fallback_image.
• 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_explained.
  • 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.
  
  

Where and How are Product Images Used?

• 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 type used for those product pages are hard coded in multiple templates.
• With the current demo store code, content pages and components, changing image types used means changing the ISML templates in question.

A scenario describes the necessary template modifications in the Cookbook - Image Framework.

Image Assignments

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 (7.6 - 7.10.15).

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.