Image - CUBA Platform. Developer’s Manual

3.5.2.1.21. Image

Image component is designed for displaying images from different sources. The component can be bound to a data container or configured programmatically.

See Working with Images in CUBA applications guide to learn how to upload and display images in the application.

XML name of the component: image.

The Image component can display the value of an entity attribute of FileDescriptor or byte[] type. In the simplest case image can be declaratively associated with data using the dataContainer and property attributes:

<image id="image" dataContainer="employeeDс" property="avatar"/>

In the example above, component displays the avatar attribute of the Employee entity located in the employeeDс data container.

Alternatively, the Image component can display images from different resources. You can set the resource type declaratively using the image elements listed below:

classpath - a resource in the classpath.

<image>
    <classpath path="com/company/sample/web/screens/myPic.jpg"/>
</image>

file - a resource in the file system.

<image>
    <file path="D:\sample\modules\web\web\VAADIN\images\myImage.jpg"/>
</image>

relativePath - resource in the application directory.

<image>
    <relativePath path="VAADIN/images/myImage.jpg"/>
</image>

theme - a theme resource, e.g.,VAADIN/themes/customTheme/some/path/image.png.
```
<image>
    <theme path="com.company.sample/myPic.jpg"/>
</image>
```

url - a resource which can be loaded from the given URL.

<image>
    <url url="https://www.cuba-platform.com/sites/all/themes/cuba_adaptive/img/lori.png"/>
</image>

image attributes:

scaleMode - applies the scale mode to the image. The following scale modes are available:
- FILL - the image will be stretched according to the size of the component.
- CONTAIN - the image will be compressed or stretched to the minimum dimension of the component while preserving the proportions.
- COVER - the image will be compressed or stretched to fill the entire area of the component while maintaining the component’s proportions. If the image proportions do not match the component’s proportions, then the image will be clipped to fit.
- SCALE_DOWN - the content changes size by comparing the difference between NONE and CONTAIN in order to find the smallest concrete size of the object.
- NONE - the image will retain its real size.

alternateText - sets an alternate text for an image in case the resource is not set or unavailable.
```
<image id="image" alternateText="logo"/>
```

image resources settings:

bufferSize - the size of the download buffer in bytes used for this resource.
```
<image>
    <file bufferSize="1024" path="C:/img.png"/>
</image>
```

cacheTime - the length of cache expiration time in milliseconds.

<image>
    <file cacheTime="2400" path="C:/img.png"/>
</image>

mimeType - the MIME type of the resource.

<image>
    <url url="https://avatars3.githubusercontent.com/u/17548514?v=4&#38;s=200"
         mimeType="image/png"/>
</image>

To programmatically manage the Image component, use the following methods:

setValueSource() - sets the data container and the entity attribute name. Only FileDescriptor and byte[] attributes are supported.

The data container can be set programmatically, for example, to display images in table cells:

frameworksTable.addGeneratedColumn("image", entity -> {
    Image image = uiComponents.create(Image.NAME);
    image.setValueSource(new ContainerValueSource<>(frameworksTable.getInstanceContainer(entity), "image"));
    image.setHeight("100px");
    return image;
});

setSource() - sets the content source for the component. The method accepts the resource type and return the resource object that can be configured using the fluent interface. Each resource type has its own methods, for example, setPath() for ThemeResource type or setStreamSupplier() for StreamResource type:
Image image = uiComponents.create(Image.NAME); image.setSource(ThemeResource.class) .setPath("images/image.png");
or
image.setSource(StreamResource.class) .setStreamSupplier(() -> new FileDataProvider(fileDescriptor).provide()) .setBufferSize(1024);
You can use one of the following resource types implementing the Resource interface or extend it to create a custom resource:
- ClasspathResource - an image located in classpath. This resource can be also set declaratively using the classpath element of the image component.
- FileDescriptorResource - an image which can be obtained from the FileStorage using the given FileDescriptor.
- FileResource - an image stored in the file system. This resource can be also set declaratively using the file element of the image component.
- RelativePathResource - an image stored in a directory of the application. This resource can be also set declaratively using the relativePath element of the image component.
- StreamResource - an image from a stream.
- ThemeResource - a theme image, for example, VAADIN/themes/yourtheme/some/path/image.png. This resource can be also set declaratively using the theme element of the image component.
- UrlResource - an image which can be loaded from the given URL. This resource can be also set declaratively using the url element of the image component.

createResource() - creates the image resource implementation by its type. The created object can be later passed to the setSource() method.

FileDescriptorResource resource = image.createResource(FileDescriptorResource.class)
        .setFileDescriptor(avatar);
image.setSource(resource);

addClickListener() - adds a listener that will be notified when a user clicks on an image area.

image.addClickListener(clickEvent -> {
    if (clickEvent.isDoubleClick())
        notifications.create()
                .withCaption("Double clicked")
                .show();
});

addSourceChangeListener() - adds a listener that will be notified when a source of an image is changed.

Attributes of image: align - alternateText - caption - captionAsHtml - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - description - descriptionAsHtml - editable - enable - box.expandRatio - height - htmlSanitizerEnabled - icon - id - property - required - requiredMessage - responsive - rowspan - scaleMode - stylename - stylename - visible - width
Attributes of image resources: bufferSize - cacheTime - mimeType
Elements of image: classpath - file - relativePath - theme - url
API: addClickListener - addSourceChangeListener - createResource - setScaleMode - setSource - setValueSource