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

    @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;

    public java.lang.Boolean getStatus() {
        return status;
    }

    public void setStatus(java.lang.Boolean status) {
        this.status = status;
    }
}
<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>
    <resource>
        <classpath path="ui/ex1/screen/component/image/jmix-logo.png"/>
    </resource>
</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>
    <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.

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

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

The SourceChangeEvent is sent when a source of an image is changed and 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());
}

Programmatic registration of the event handler: 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.

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