Image

LIVE DEMO

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.

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

    @Column(name = "STATUS")
    private java.lang.Boolean status;

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

    @PropertyDatatype("fileRef")
    @Column(name = "IMAGE")
    private FileRef image;

    /*setters and getters*/
}

In the simplest case image can be declaratively associated with data using the dataContainer and property attributes:

<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 - a resource that is located in the classpath with the given path.

    For example, if your resource has the following path: "ui/ex1/screen/component/image/jmix-logo.png", you can set the resource type declaratively:

    <image scaleMode="SCALE_DOWN"
       width="20%"
       height="20%">
    <resource>
        <classpath path="ui/ex1/screen/component/image/jmix-logo.png"/>
    </resource>
</image>

  • file - a resource that is stored in the file system as the given File. For example:

    <image>
    <resource>
        <file path="D:\JMIX\jmix-logo.png"/>
    </resource>
</image>

  • relativePath - a resource that is stored in the directory of the deployed application.

    To get access to a file using the relative path resource approach, you should create a VAADIN folder in the root of the resource directory. Files stored in this directory are accessible via URL.

    image relative path

    Then you can set the resource type declaratively, for example:

    <image>
    <resource>
        <relativePath path="VAADIN/images/jmix-icon-login.svg"/>
    </resource>
</image>

    The generated URL for a relative path will be http://localhost:8080/VAADIN/images/jmix-icon-login.svg.

  • theme - a theme resource. For example, for the helium-ext custom theme, you can create the images directory with resources:

    images theme resources

    Then set the path to your resource declaratively, for example:

    <image>
    <resource>
        <theme path="images/jmix-icon-login.svg"/>
    </resource>
</image>

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

    <image scaleMode="SCALE_DOWN"
       width="20%"
       height="20%">
    <resource>
        <url url="https://www.jmix.io/uploads/framework_image_9efadbc372.svg"/>
    </resource>
</image>

Also, you can set the resource type 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>
    <resource>
        <url url="https://avatars3.githubusercontent.com/u/17548514?v=4&#38;s=200"
             mimeType="image/png"/>
    </resource>
</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.

  • FileStorageResource - an image stored in the file storage.

  • RelativePathResource - an image stored in a directory of the deployed 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.

Events and Handlers

To generate a handler stub in Jmix Studio, select the component in the screen descriptor XML or in the Component Hierarchy panel and use the Handlers tab of the Component Inspector panel.

Alternatively, you can use the Generate Handler button in the top panel of the screen controller.

ClickEvent

See ClickEvent.

ContextHelpIconClickEvent

See ContextHelpIconClickEvent.

SourceChangeEvent

SourceChangeEvent is sent when a source of an image is changed. SourceChangeEvent has the following methods:

  • getNewSource()

  • getOldSource()

@Subscribe("image")
public void onImageSourceChange(ResourceView.SourceChangeEvent event) {
    notifications.create()
            .withCaption("Old source was: " + event.getOldSource() +
                    "; new source is: " + event.getNewSource());
}

To register the event handler programmatically, use the addSourceChangeListener() component method.

All XML Attributes

You can view and edit attributes applicable to the component using the Component Inspector panel of the Studio’s Screen Designer.

Image XML Attributes

align - alternateText - box.expandRatio - caption - captionAsHtml - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - description - descriptionAsHtml - editable - enable - height - htmlSanitizerEnabled - icon - id - property - required - requiredMessage - property - required - requiredMessage - rowspan - scaleMode - stylename - visible - width

Image XML Elements

resource

Resources XML Elements

classpath - file - relativePath - theme - url