API de Java™ para la entrega de imágenes optimizadas para la web

Aprenda a utilizar las API de Java™ de entrega de imágenes optimizadas para la web de AEM as a Cloud Service para desarrollar experiencias web de alto rendimiento.

AEM as a Cloud Service admite entrega de imágenes optimizadas para la web, lo cual genera automáticamente representaciones web de imágenes optimizadas de los recursos. La entrega de imágenes optimizadas para la web se puede utilizar con tres enfoques principales:

  1. AEM Usar componentes principales de WCM de la
  2. AEM Crear un componente personalizado que amplía el componente de imagen del componente principal de WCM
  3. Cree un componente personalizado que utilice la API Java™ de AssetDelivery para generar direcciones URL de imagen optimizadas para la web.

Este artículo explora el uso de las API de Java™ de imagen optimizada para la web en un componente personalizado, de una manera que permite que la función basada en código funcione tanto en AEM as a Cloud Service AEM como en el SDK de la.

API de Java™

La API AssetDelivery es un servicio OSGi que genera direcciones URL de entrega optimizadas para la web para los recursos de imagen. AssetDelivery.getDeliveryURL(...) opciones permitidas están documentadas aquí.

El servicio OSGi AssetDelivery solo se cumple cuando se ejecuta en AEM as a Cloud Service. AEM En el SDK de la, las referencias al servicio OSGi AssetDelivery devuelven null. Es mejor utilizar de forma condicional la URL optimizada para la web cuando se ejecuta en AEM as a Cloud Service AEM y utilizar una URL de imagen de reserva en el SDK de la. Normalmente, la representación web del recurso es una reserva suficiente.

Uso de API en el servicio OSGi

AEM Marque la referencia AssetDelivery como opcional en los servicios OSGi personalizados para que el servicio OSGi personalizado permanezca disponible en el SDK de la.

import com.adobe.cq.wcm.spi.AssetDelivery;
...
@Reference(cardinality = ReferenceCardinality.OPTIONAL)
private volatile AssetDelivery assetDelivery;

Uso de API en el modelo Sling

AEM Marque la referencia AssetDelivery como opcional en los modelos Sling personalizados, de modo que el modelo Sling personalizado permanezca disponible en el SDK de la.

import com.adobe.cq.wcm.spi.AssetDelivery;
...
@OSGiService(injectionStrategy = InjectionStrategy.OPTIONAL)
private AssetDelivery assetDelivery;

Uso condicional de API

Devolver condicionalmente la URL de imagen optimizada para la web o la URL de reserva en función de la disponibilidad del servicio OSGi AssetDelivery. AEM El uso condicional permite que el código funcione al ejecutarlo en el SDK de la.

if (assetDelivery != null ) {
    // When running on AEM as a Cloud Service use the real web-optimized image URL.
    return assetDelivery.getDeliveryURL(...);
} else {
    // When running on AEM SDK, use some fallback image so the experience does not break.
    // What the fallback is up to you!
    return getFallbackURL(...);
}

Código de ejemplo

El siguiente código crea un componente de ejemplo que muestra una lista de recursos de imagen mediante direcciones URL de imagen optimizadas para la web.

Cuando el código se ejecuta en AEM as a Cloud Service, las representaciones de imágenes web optimizadas para la web se utilizan en el componente personalizado.

Imágenes optimizadas para la web en AEM as a Cloud Service

AEM as a Cloud Service admite la API AssetDelivery, por lo que se utiliza la representación web optimizada

AEM Cuando el código se ejecuta en el SDK de la, se utilizan las representaciones web estáticas menos óptimas, lo que permite que el componente funcione durante el desarrollo local.

AEM imágenes de reserva optimizadas para la web en el SDK de la

AEM El SDK de no admite la API AssetDelivery, por lo que se utiliza la representación web estática de reserva (PNG o JPEG)

La implementación se divide en tres partes lógicas:

  1. AEM El servicio OSGi de WebOptimizedImage actúa como un "proxy inteligente" para el servicio OSGi de AssetDelivery proporcionado por el usuario que puede controlar la ejecución en AEM as a Cloud Service AEM y en el SDK de la.
  2. El modelo Sling ExampleWebOptimizedImages proporciona lógica empresarial para recopilar la lista de recursos de imagen y sus direcciones URL optimizadas para la web que se van a mostrar.
  3. AEM El componente example-web-optimized-images de la implementa HTL para mostrar la lista de imágenes optimizadas para la web.

El código de ejemplo siguiente se puede copiar en la base de código y actualizar según sea necesario.

Servicio OSGi

El servicio OSGi WebOptimizedImage está dividido en una interfaz pública a la que se puede dirigir (WebOptimizedImage) y una implementación interna (WebOptimizedImageImpl). WebOptimizedImageImpl devuelve una URL de imagen optimizada para la web al ejecutarse en AEM as a Cloud Service AEM AEM y una URL de representación web estática en el SDK de la, lo que permite que el componente siga funcionando en el SDK de la.

Interfaz

La interfaz define el contrato de servicio OSGi con el que pueden interactuar otros códigos, como los modelos Sling.

package com.adobe.aem.guides.wknd.core.images;

import org.apache.sling.api.resource.ResourceResolver;
import org.osgi.annotation.versioning.ProviderType;

import java.util.Map;

/**
 * OSGi Service that acts as a facade for the AssetDelivery API, such that a fallback can be automatically served on the AEM SDK.
 *
 * This service can be extended to provide additional functionality, such as srcsets, etc.
 */
@ProviderType
public interface WebOptimizedImage {
    /**
     * Returns the Web Optimized Image URL.
     * @param resourceResolver the user's resource resolver
     * @param path the path to the asset
     * @param options the options to pass to the AssetDelivery API
     * @return the Web Optimized Image URL
     */
    String getDeliveryURL(ResourceResolver resourceResolver, String path, Map<String, Object> options);
}

Implementación

AEM AEM La implementación del servicio OSGi incluye una referencia opcional al servicio OSGi de AssetDelivery y una lógica de reserva para seleccionar una URL de imagen adecuada cuando AssetDelivery es null en el SDK de la. La lógica de reserva se puede actualizar según los requisitos.

package com.adobe.aem.guides.wknd.core.images.impl;

import com.adobe.aem.guides.wknd.core.images.WebOptimizedImage;
import com.adobe.cq.wcm.spi.AssetDelivery;
import com.day.cq.dam.api.Asset;
import com.day.cq.dam.api.Rendition;
import com.day.cq.dam.api.RenditionPicker;
import com.day.cq.dam.commons.util.DamUtil;
import org.apache.commons.lang3.StringUtils;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.osgi.service.component.annotations.ReferenceCardinality;

import java.util.Map;
@Component
public class WebOptimizedImageImpl implements WebOptimizedImage {
    private static final String DEFAULT_FORMAT = "webp";
    @Reference(cardinality = ReferenceCardinality.OPTIONAL)
    private volatile AssetDelivery assetDelivery;

    /**
     * Returns the Web Optimized Image URL.
     * @param resourceResolver the user's resource resolver
     * @param path the path to the asset
     * @param options the options to pass to the AssetDelivery API
     * @return the Web Optimized Image URL
     */
    @Override
    public String getDeliveryURL(ResourceResolver resourceResolver, String path, Map<String, Object> options) {
        if (assetDelivery != null) {
            return getWebOptimizedUrl(resourceResolver, path, options);
        } else {
            return getFallbackUrl(resourceResolver, path);
        }
    }
    /**
     * Uses the AssetDelivery API to get the Web Optimized Image URL.
     * @param resourceResolver the user's resource resolver
     * @param path the path to the asset
     * @param options the options to pass to the AssetDelivery API
     * @return the Web Optimized Image URL
     */
    private String getWebOptimizedUrl(ResourceResolver resourceResolver, String path, Map<String, Object> options) {
        Resource resource = resourceResolver.getResource(path);
        Asset asset = DamUtil.resolveToAsset(resource);

        // These 3 options are required for the AssetDelivery API to work, else it will return null
        options.put("path", asset.getPath());
        options.put("format", StringUtils.defaultString((String) options.get("format"), DEFAULT_FORMAT));
        options.put("seoname", StringUtils.defaultString((String) options.get("seoname"), asset.getName()));

        // The resource only provides the security context into AEM so the asset's UUID can be looked up for the Web Optimized Image URL
        return assetDelivery.getDeliveryURL(resource, options);
    }

    /**
     * Fallback to the static web rendition if the AssetDelivery API is not available, meaning the code is running on the AEM SDK.
     * @param resourceResolver the user's resource resolver
     * @param path the path to the asset
     * @return the path to the web rendition
     */
    private String getFallbackUrl(ResourceResolver resourceResolver, String path) {
        Resource resource = resourceResolver.getResource(path);
        Asset asset = DamUtil.resolveToAsset(resource);

        return asset.getRendition(WebRenditionPicker).getPath();
    }

    /**
     * Picks the web rendition of the asset.
     */
    private static final RenditionPicker WebRenditionPicker = new RenditionPicker() {
        @Override
        public Rendition getRendition(Asset asset) {
            return asset.getRenditions().stream().filter(rendition -> StringUtils.startsWith(rendition.getName(), "cq5dam.web.")).findFirst().orElse(asset.getOriginal());
        }
    };
}

Modelo Sling

El modelo Sling de ExampleWebOptimizedImages se divide en una interfaz pública a la que se puede dirigir (ExampleWebOptimizedImages) y una implementación interna (ExampleWebOptimizedImagesImpl);

El modelo Sling ExampleWebOptimizedImagesImpl recopila la lista de recursos de imagen que se van a mostrar e invoca el servicio OSGi personalizado WebOptimizedImage para obtener la dirección URL de la imagen optimizada para la web. AEM Dado que este modelo de Sling representa un componente de, tiene los métodos habituales como isEmpty(), getId() y getData(); sin embargo, estos métodos no son directamente relevantes para utilizar imágenes optimizadas para la web.

Interfaz

La interfaz define el contrato del modelo Sling con el que puede interactuar otro código, como HTL.

package com.adobe.aem.guides.wknd.core.models;

import com.adobe.cq.wcm.core.components.models.datalayer.ComponentData;
import com.fasterxml.jackson.annotation.JsonProperty;

import java.util.List;

public interface ExampleWebOptimizedImages {

    /**
     * @return a list of web optimized images for the component to display. Each item in the list has necessary information to render the image.
     */
    List<Img> getImages();

    /**
     * @return true if this component has no images to display.
     */
    boolean isEmpty();

    /**
     * @return String representing the unique identifier of the ExampleWebOptimizedImages component on a page
     */
    String getId();

    /**
     * @return JSON data to populate the data layer
     */
    @JsonProperty("dataLayer")
    default ComponentData getData() {
        return null;
    }

    /**
     * Describes a web optimized image.
     */
    interface Img {
        /**
         * @return the URL to the web optimized rendition of the image.
         */
        String getSrc();

        /**
         * @return the alt text of the web optimized image.
         */
        String getAlt();

        /**
         * @return the height of the web optimized image.
         */
        String getHeight();
        /**
         * @return the width of the web optimized image.
         */
        String getWidth();
    }
}

Implementación

El modelo Sling utiliza el servicio OSGi personalizado WebOptimizeImage para recopilar las direcciones URL de imagen optimizadas para la web de los recursos de imagen que muestra su componente.

En este ejemplo, se utiliza una consulta simple para recopilar recursos de imagen.

package com.adobe.aem.guides.wknd.core.models.impl;

import com.adobe.aem.guides.wknd.core.images.WebOptimizedImage;
import com.adobe.aem.guides.wknd.core.models.ExampleWebOptimizedImages;
import com.adobe.cq.wcm.core.components.models.datalayer.ComponentData;
import com.adobe.cq.wcm.core.components.models.datalayer.builder.DataLayerBuilder;
import com.adobe.cq.wcm.core.components.util.ComponentUtils;
import com.day.cq.dam.api.Asset;
import com.day.cq.dam.commons.util.DamUtil;
import com.day.cq.wcm.api.Page;
import com.day.cq.wcm.api.components.ComponentContext;
import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.models.annotations.DefaultInjectionStrategy;
import org.apache.sling.models.annotations.Model;
import org.apache.sling.models.annotations.Required;
import org.apache.sling.models.annotations.injectorspecific.OSGiService;
import org.apache.sling.models.annotations.injectorspecific.ScriptVariable;
import org.apache.sling.models.annotations.injectorspecific.Self;

import java.util.*;

@Model(
        adaptables = {SlingHttpServletRequest.class},
        adapters = {ExampleWebOptimizedImages.class},
        resourceType = {ExampleWebOptimizedImagesImpl.RESOURCE_TYPE},
        defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL
)
public class ExampleWebOptimizedImagesImpl implements ExampleWebOptimizedImages {

    protected static final String RESOURCE_TYPE = "wknd/components/example-web-optimized-images";

    private static final int MAX_RESULTS = 10;

    @Self
    @Required
    private SlingHttpServletRequest request;

    @OSGiService
    private WebOptimizedImage webOptimizedImage;

    @ScriptVariable
    private Page currentPage;

    @ScriptVariable
    protected ComponentContext componentContext;

    private List<Img> images;

    // XPath query to find image assets to display
    private static final String XPATH_QUERY = "/jcr:root/content/dam/wknd-shared/en/adventures//element(*, dam:Asset) [ (jcr:contains(jcr:content/metadata/@dc:format, 'image/')) ]";
    @Override
    public List<Img> getImages() {

        if (images == null) {
            images = new ArrayList<>();

            // Set the AssetDelivery options to request a web-optimized rendition.
            // These options can be set as required by the implementation (Dialog, pass in from HTL via @RequestAttribute)
            final Map<String, Object> options = new HashMap<>();
            options.put("format", "webp");
            options.put("preferwebp", "true");
            options.put("width", "350");
            options.put("height", "350");

            final Iterator<Resource> results = request.getResourceResolver().findResources(XPATH_QUERY, "xpath");

            while (results.hasNext() && images.size() < MAX_RESULTS) {
                Resource resource = results.next();
                Asset asset = DamUtil.resolveToAsset(resource);

                // Get the image URL; the web-optimized rendition on AEM as a Cloud Service, or the static web rendition fallback on AEM SDK
                final String url = webOptimizedImage.getDeliveryURL(request.getResourceResolver(), resource.getPath(), options);

                // Add the image to the list that is passed to the HTL component to display
                // We'll add some extra attributes so that the HTL can display the image in a performant, SEO-friendly, and accessible way
                // ImgImpl can be extended to add additional attributes, such as srcset, etc.
                images.add(new ImgImpl(url, asset.getName(), (String) options.get("height"), (String) options.get("width")));
            }
        }

        return this.images;
    }

    @Override
    public boolean isEmpty() {
        return getImages().isEmpty();
    }

    @Override
    public String getId() {
        return ComponentUtils.getId(request.getResource(), currentPage, componentContext);
    }

    @Override
    public ComponentData getData() {
        if (ComponentUtils.isDataLayerEnabled(request.getResource())) {
            return DataLayerBuilder.forComponent()
                    .withId(() -> getId())
                    .withType(() -> RESOURCE_TYPE)
                    .build();
        }
        return null;
    }

    class ImgImpl implements Img {
        private final String url;
        private final String alt;
        private final int height;
        private final int width;

        public ImgImpl(String url, String alt, String height, String width) {
            this.url = url;
            this.alt = alt;
            this.height = Integer.parseInt(height);
            this.width = Integer.parseInt(width);
        }

        @Override
        public String getSrc() {
            return url;
        }

        @Override
        public String getAlt() {
            return alt;
        }

        @Override
        public String getHeight() {
            return height + "px";
        }

        @Override
        public String getWidth() {
            return width + "px";
        }
    }
}

AEM Componente

AEM Un componente de Sling está enlazado al tipo de recurso Sling de la implementación del modelo Sling WebOptimizedImagesImpl y es responsable de mostrar la lista de imágenes.

El componente recibe una lista de Img objetos a través de getImages() que incluyen las imágenes WEBP optimizadas para la web al ejecutarse en AEM as a Cloud Service El componente recibe una lista de Img objetos a través de getImages() que incluyen imágenes web PNG/JPEG AEM estáticas al ejecutarse en el SDK de la.

HTL

HTL usa el modelo Sling WebOptimizedImages y procesa la lista de objetos Img devueltos por getImages().

<style>
    .cmp-example-web-optimized-images__list {
        width: 100%;
        list-style: none;
        padding: 0;
        display: flex;
        flex-wrap: wrap;
        justify-content: space-between;
        gap: 2rem;
    }

    .cmp-example-web-optimized-images-list__item {
        margin: 0;
        padding: 0;
    }
</style>

<div data-sly-use.exampleImages="com.adobe.aem.guides.wknd.core.models.ExampleWebOptimizedImages"
     data-sly-use.placeholderTemplate="core/wcm/components/commons/v1/templates.html"
     data-sly-test.hasContent="${!exampleImages.empty}"
     data-cmp-data-layer="${exampleImages.data.json}">

    <h3>Example web-optimized images</h3>

    <ul class="cmp-example-web-optimized-images__list"
        data-sly-list.item="${exampleImages.images}">
        <li class="cmp-example-web-optimized-images-list__item">
            <img class="cmp-example-web-optimized-images__image"
                 src="${item.src}"
                 alt="${item.alt}"
                 width="${item.width}"/>
        </li>
    </ul>
</div>
<sly data-sly-call="${placeholderTemplate.placeholder @ isEmpty=!hasContent, classAppend='cmp-example-web-optimized-images'}"></sly>
recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69