Image - CUBA Platform. Developer’s Manual

5.5.2.1.19. Image

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

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 datasource and property attributes:

<image id="image" datasource="employeeDs" property="avatar"/>

In the example above, component displays the avatar attribute of the Employee entity located in the employeeDs datasource.

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

Methods of the Image interface:

setDatasource() - sets the datasource and the entity attribute name. Only FileDescriptor and byte[] attributes are supported.

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

frameworksTable.addGeneratedColumn("image", entity -> {
    Image image = componentsFactory.createComponent(Image.class);
    image.setDatasource(frameworksTable.getItemDatasource(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 = componentsFactory.createComponent(Image.class); 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(event -> {
    if (event.isDoubleClick())
        showNotification("Double clicked");
});

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

Attributes of image: align - alternateText - caption - colspan - datasource - description - editable - enable - height - 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 - setDatasource - setSource