21 Images

This chapter provides details about configuring images for display in the Fusion Client. It includes the following sections:

• Overview

• Images

• XML Fragments

• CSV File

• Utilities

Overview

Images are represented in RPAS as string-typed dimension attributes or measures with a UI type of media. In general, these behave like regular string attributes and measures; however, the Fusion Client handles them in a special way for display. They are loaded in the same way as any other string value.

Note that all dimension attribute measures are automatically loaded in a new workbook except when the measure is included in the workbook template, either explicitly or as a hidden measure. In that case, a load rule is required to bring the values of the measure from the domain into a new workbook.

Information about the image files must be prepared as data and collected into a CSV file that can be loaded into attributes or measures using the loadmeasure utility.

The set of images associated with a particular position or cell is called a media bundle. This data is prepared externally and loaded into the domain. The value of a media bundle measure or attribute is a text string in a defined XML fragment format. The XML consists of a number of <image> tags, one for each image. The Fusion Client UI chooses which image to use and how to display it, based on the UI context.

The media bundle lists the image attributes and measures. The Fusion Client User Interface chooses which one to use and how to use it, based on UI context and information provided in the bundle.

Images

The images used in the media bundles must be of the of the appropriate size and file type. Two sizes of image are recommended: a thumb image that is 100 x 100 pixels and a full image that is 400 x 400 pixels.

The thumb image is used for pivot table position headers, pivot table cell values, media item browser in the detail pop-up, and treemap chart images.

The full image is used for the selected item in the detail pop-up and the view image position carousel.

The supported image file types are the ones supported by your browser without an additional player. The valid image types are listed in the rpasConfig.properties file. These file types can include jpeg, jpg, png, and gif. You must obtain the necessary images and prepare them to meet these requirements.

The images can be stored in either of two locations: a local repository directory or an external content server. The images are identified by the URL for the location in which they are stored. So the image files are identified as follows:

/repository/<image-name>.jpg

http://.../<image-name>.png

https://.../<image-name>.gif

The naming of the image files depends on individual preference; however, the prepareMediaData.sh utility, described later in this chapter, has specific file-naming requirements, which depend in part on whether the image is for an attribute or a measure.

XML Fragments

The data for each image is described in an XML fragment consisting of an image tag for each image in the value. The following example has three images, a view of the product, a view of the product worn by a model, and a view of the fabric sample. An image XML fragment can contain the number of images and the variety of images required by a specific customer.

Figure 21-1 XML Fragment Example

Each image has an "id" that indicates the type of image. The image with the "id" of main is used by the Fusion Client as the primary image. If no image is identified as main, then the first image in the XML media bundle is the one that is used as the primary image. The primary image is displayed in the pivot table. All the images in the XML fragment can be viewed in the detail pop-up.

Each image also has a label. The label consists of a text string that is displayed with the image, generally when you hover over the image. The label is not translated.

A particular SKU can be associated with a single image or a group of images that illustrate different aspects of the SKU, such as back and front.

Each image must have a thumb and a full. The thumb size image in a thumbnail image used in the pivot table and whenever many images are shown on a single page. It is typically shown in an area of 100 x 100 pixels or smaller. These images must be small so that they can be loaded quickly by a browser. The full size image is a larger image that is used in the detail pop-up for browsing through a series of images. It is typically shown in an area of 400 x 400 pixels.

The URL in the XML fragment can refer to either the local repository (via /repository) or to a valid external server (via a complete web URL, beginning with http:// or https://).

The ID of the primary image and the size IDs and dimensions used by the Fusion Client UI are all confiurable in rpasConfig.properties.

CSV File

The CSV file used by the loadmeasure utility to load the image data contains string values that contain XML fragments quoted as required by the CSV file format. To construct a single value for an XML fragment, put it on one line and enclose it in quotes. Quotes that are internal to the XML fragment must be doubled.

Figure 21-2 CSV Example

The Fusion Client validates all image data before displaying the image. The data must be in valid XML format, with valid urls for security purposes and valid image file types. Any URL using an external server must point to a valid image host, as defined in rpasConfig.properties. You can use prepareMediaData.sh to generate the CSV file and validateMediaData.sh to validate the CSV file. These utilities are described in the following section.

Utilities

Two utilities are available for generating and validating the CSV file. The loadmeasure utility uses the CSV file to load the images into the designated location.

prepareMediaData.sh

The prepareMediaData.sh utility generates a number of CSV files from a directory of image files. The image files required by the utility must be named as follows:

For an attribute:

<attrName>-<position>-<imageId>-<sizeId>.<imageFileType>

For a measure:

<measureName>-<position1>-<position2>-<imageId>-<sizeId>.<imageFileType>

Note that you must include as many positions as the measure's intersection requires.

Usage

prepareMediaData.sh <tools_home> <Source_dir> <Target_dir> [-labelGenerated] [-labelUserDefined] [--help] [-properties <path-to-label.properties>] [-prefixURL <URL-to-be-prefixed>

The following arguments are required:

Argument	Description
tools_home	Location of tools_home, which contains /lib/media-utilty.jar
Source_dir	Location of image files
Target_dir	Location for generated CSV file output

The following parameters are optional:

Option	Description
-labelGenerated	Generate image labels
-labelUserDefined	Use image labels after ! in image-file name
-prefixURL <prefix>	Specify a prefix for URLs (default is /repository/). This is useful when generating data for images that are served by a content server.
-properties <path>	Specify a path to a label.properties file, which maps image IDs to label strings. For example, main=Product Front; modelFront=Model Front; fabric=Fabric Sample.
-?, --help or -usage	Print this help text

validateMediaData.sh

The validateMediaData.sh utility validates a CSV file that has been generated either using the above utility or some other method. The validation utility checks for the proper file format and valid urls, based on the security settings in rpasConfig.properties. These security settings include valid.image.file.type and valid.image.url.hosts.

Usage

validateMediaData.sh <tools_home> <Source_csv_file> <Target_dir> [--help] [-validateColumns <columns>]

The following arguments are required:

Argument	Description
tools_home	Location of tools_home, which contains /lib/media-utilty.jar
Source_csv_file	Input CSV file to be validated
Target_dir	Target folder where output files should be created

The following parameters are optional:

Option	Description
-validateColumns	Specify which columns to validate. Takes comma-separated column numbers (for example -validateColumns 4,7).
-?, --help or -usage	Print this help text