Module org.omnifaces
Package org.omnifaces.component.output

Class GraphicImage

  • All Implemented Interfaces:
    ClientBehaviorHolder, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener
    public class GraphicImage
extends HtmlGraphicImage

    The <o:graphicImage> is a component that extends the standard <h:graphicImage> with support for referencing an InputStream or byte[] property in the value attribute, optionally as a data URI.

    Data URI

    Set dataURI attribute to true in order to render image in data URI format. 

     <o:graphicImage name="icon.png" dataURI="true" /> <!-- Faces resource as data URI -->
 <o:graphicImage value="#{bean.icon}" dataURI="true" /> <!-- byte[]/InputStream property as data URI -->

    This basically renders the image inline in HTML output immediately during Faces render response phase. This approach is very useful for a "preview" feature of uploaded images and works also in combination with view scoped beans. This approach is however not recommended for "permanent" and/or "large" images as it doesn't offer the browser any opportunity to cache the images for reuse, ~10KB would typically be the max even less so if there are more such images on the same page.

    Image streaming

    When not rendered as data URI, the InputStream or byte[] property must point to a stateless @GraphicImageBean or @Named @ApplicationScoped bean. The property will namely be evaluated at the moment the browser requests the image content based on the URL as specified in HTML <img src>, which is usually a different request than the one which rendered the Faces page. E.g. 

     @Named
 @RequestScoped
 public class Bean {

     private List<Image> images; // Image class should NOT have "content" property, or at least it be lazy loaded.

     @Inject
     private ImageService service;

     @PostConstruct
     public void init() {
         images = service.list();
     }

     public List<Image> getImages() {
         return images;
     }

 }
 
     @GraphicImageBean
 public class Images {

     @Inject
     private ImageService service;

     public byte[] get(Long id) {
         return service.getContent(id);
     }

 }
 
     <ui:repeat value="#{bean.images}" var="image">
     <o:graphicImage value="#{images.get(image.id)}" />
 </ui:repeat>

    A @RequestScoped and @SessionScoped bean would theoretically work, but this is wrong design (a servlet is inherently also application scoped and stateless, not without reason). A @ViewScoped wouldn't work because the image request doesn't share the Faces view state.

    In case the property is a method expression taking arguments, each of those arguments will be converted to a string HTTP request parameter and back to actual objects using the converters registered by class as available via Application.createConverter(Class). So, most of standard types like Long are already implicitly supported. In case you need to supply a custom object as argument for some reason, you need to explicitly register a converter for it yourself via @FacesConverter(forClass).

    Caching

    In case your "image" entity supports it, you can also supply the "last modified" property which will be used in the ETag and Last-Modified headers and in If-Modified-Since checks, hereby improving browser caching. The lastModified attribute supports both Date and Long as timestamp in milliseconds. 

     <ui:repeat value="#{bean.images}" var="image">
     <o:graphicImage value="#{images.get(image.id)}" lastModified="#{image.lastModified}" />
 </ui:repeat>

    When unspecified, then the "default resource maximum age" as set in either the Mojarra specific context parameter com.sun.faces.defaultResourceMaxAge or MyFaces specific context parameter org.apache.myfaces.RESOURCE_MAX_TIME_EXPIRES will be used, else a default of 1 week will be assumed.

    Image types

    When rendered as data URI, the content type will be guessed based on content header. So far, WEBP, JPEG, PNG, GIF, ICO, SVG, BMP and TIFF are recognized. If the content header is unrecognized, or when the image is rendered as regular image source, then the content type will default to "image" without any subtype. This should work for most images in most browsers. This may however fail on newer images or in older browsers. In that case, you can explicitly specify the image type via the type attribute which must represent a valid file extension. E.g. 

     <o:graphicImage value="#{images.get(image.id)}" type="svg" />

    The content type will be resolved via Faces.getMimeType(String). You can add unrecognized ones as <mime-mapping> in web.xml. E.g. 

     <mime-mapping>
     <extension>svg</extension>
     <mime-type>image/svg+xml</mime-type>
 </mime-mapping>

    SVG view modes

    When serving a SVG image, you can use fragment attribute to trigger SVG view modes (beware of browser support). E.g. 

     <o:graphicImage value="#{images.get(image.id)}" type="svg" fragment="svgView(viewBox(0,50,200,200))" />

    Lazy loading

    Since OmniFaces 3.10, you can set the lazy attribute to true to indicate that the referenced image should only be loaded when the window is finished loading and the image is visible in the viewport. 

     <o:graphicImage ... lazy="true" />

    This attribute is ignored when the dataURI attribute is set to true.

    Design notes

    The bean class name and method name will end up in the image source URL. Although this is technically harmless and not tamperable by hackers, you might want to choose a "sensible" class and method name for this purpose.

    Like <h:graphicImage>, the value attribute is ignored when the name attribute is specified (for Faces resources). And, the value attribute of <o:graphicImage> does not support URLs anymore. For that, just keep using <h:graphicImage> or even plain <img>.

    Since:
    2.0
    Author:
    Bauke Scholtz
    See Also:
    GraphicImageBean, GraphicResource, DynamicResource, GraphicResourceHandler, DefaultResourceHandler, ExpressionInspector, MethodReference

    • Field Detail

      • COMPONENT_TYPE

        public static final String COMPONENT_TYPE
        The component type, which is "org.omnifaces.component.output.GraphicImage".
        See Also:
        Constant Field Values

      • ATTRIBUTE_NAMES

        protected static final Map<String,​String> ATTRIBUTE_NAMES
        Attribute names inherited from superclass.

    • Constructor Detail

      • GraphicImage

        public GraphicImage()
        Constructs the GraphicImage component.

    • Method Detail

      • getSrc

        protected String getSrc​(FacesContext context)
                 throws IOException
        Returns the URL needed for the 'src' attribute.
        Parameters:
        context - The involved faces context.
        Returns:
        The URL needed for the 'src' attribute.
        Throws:
        IOException - When something fails at I/O level.

      • getAlt

        public String getAlt()
        Returns an empty string as default value instead of null, so that the attribute is always rendered, as mandated by HTML5.
        Overrides:
        getAlt in class HtmlGraphicImage

      • isDataURI

        public boolean isDataURI()
        Returns whether or not to render image in data URI format.
        Returns:
        Whether or not to render image in data URI format.
        Since:
        3.10

      • setDataURI

        public void setDataURI​(boolean dataURI)
        Sets whether or not to render image in data URI format.
        Parameters:
        dataURI - Whether or not to render image in data URI format.
        Since:
        3.10.1

      • isLazy

        public boolean isLazy()
        Returns whether or not to lazily load image.
        Returns:
        Whether or not to lazily load image.
        Since:
        3.10

      • setLazy

        public void setLazy​(boolean lazy)
        Sets whether or not to lazily load image.
        Parameters:
        lazy - Whether or not to lazily load image.
        Since:
        3.10