Image

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

Component’s XML-name: image.

Basics

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

@JmixEntity
@Table(name = "UIEX1_PERSON")
@Entity(name = "uiex1_Person")
public class Person {
    @JmixGeneratedValue
    @Column(name = "ID", nullable = false)
    @Id
    private UUID id;

    @InstanceName
    @Column(name = "NAME", nullable = false)
    @NotNull
    private String name;

    @PropertyDatatype("fileRef")
    @Column(name = "IMAGE")
    private FileRef image;
}
<data readOnly="true">
    <instance id="personDc"
              class="ui.ex1.entity.Person">
        <fetchPlan extends="_base"/>
        <loader/>
    </instance>
</data>
<layout spacing="true">
        <image id="fileRefImage"
               dataContainer="personDc"
               property="image"/>
</layout>

In the example above, the component displays the image attribute of the Person entity located in the personDc data container.

Resources

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

  • classpath - resource in the classpath.

  • file - resource in the file system.

  • relativePath - resource in the application directory.

  • theme - theme resource.

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

For example:

<image>
    <classpath path="ui/ex1/screen/component/image/jmix-logo.png"/>
</image>

Also, you can do it programmatically, using one of the resource types.

Resource Settings

  • bufferSize - size of the download buffer in bytes used for this resource.

  • cacheTime - length of cache expiration time in milliseconds.

  • mimeType - MIME type of the resource.

For example:

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

Attributes

  • alternateText - sets an alternate text for an image in case the resource is not set or unavailable.

  • 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 to find the smallest concrete size of the object.

    • NONE - the image will retain its real size.

Methods

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

  • setValueSource() - sets the data container, and the entity attribute name. Only FileRef and byte[] type of attributes are supported.

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

    <data readOnly="true">
        <collection id="personsDc"
                    class="ui.ex1.entity.Person">
            <fetchPlan extends="_base"/>
            <loader id="personsDl">
                <query>
                    <![CDATA[select e from uiex1_Person e]]>
                </query>
            </loader>
        </collection>
    </data>
    <layout spacing="true">
            <groupTable id="personsTable"
                        width="100%"
                        dataContainer="personsDc">
                <columns>
                    <column id="name"/>
                </columns>
            </groupTable>
    </layout>
    @Autowired
    private GroupTable<Person> personsTable;
    @Autowired
    private UiComponents uiComponents;
    
    @Subscribe
    public void onInit(InitEvent event) {
        personsTable.addGeneratedColumn("image", entity -> {
            Image<FileRef> image = uiComponents.create(Image.NAME);
            image.setValueSource(new ContainerValueSource<>(personsTable.getInstanceContainer(entity), "image"));
            image.setHeight("100px");
            image.setScaleMode(Image.ScaleMode.CONTAIN);
            return image;
        });
    }
  • setSource() - sets the content source for the component. The method accepts the resource type and returns the resource object that can be configured using the fluent interface.

    <layout spacing="true">
            <image id="programmaticImage"/>
    </layout>
    @Autowired
    private Image<FileRef> programmaticImage;
    
    @Subscribe
    public void onInit(InitEvent event) {
        String address = "https://www.cuba-platform.com/sites/all/themes/cuba_adaptive/img/upper-header-logo.png";
        URL url = null;
        try {
            url = new URL(address);
            programmaticImage.setSource(UrlResource.class).setUrl(url);
        } catch (MalformedURLException e) {
            e.printStackTrace();
        }
    }

Resource Types

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

  • FileResource - an image stored in the file system.

  • RelativePathResource - an image stored in a directory of the application.

  • StreamResource - an image from a stream.

  • ThemeResource - a theme image, for example, VAADIN/themes/yourtheme/some/path/image.png.

  • UrlResource - an image that can be loaded from the given URL.

Listeners

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

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

For example:

@Autowired
private Notifications notifications;
@Autowired
private Image<FileRef> programmaticImage;

@Subscribe
public void onInit(InitEvent event) {
    programmaticImage.addClickListener(clickEvent -> {
        if (clickEvent.isDoubleClick())
            notifications.create()
                    .withCaption("Double clicked")
                    .show();
    });
}