com.vaadin.flow.data.renderer.Renderer Maven / Gradle / Ivy

Go to download
/*
 * Copyright 2000-2024 Vaadin Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.vaadin.flow.data.renderer;

import java.io.Serializable;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;

import com.vaadin.flow.data.provider.CompositeDataGenerator;
import com.vaadin.flow.data.provider.DataGenerator;
import com.vaadin.flow.data.provider.DataKeyMapper;
import com.vaadin.flow.dom.Element;
import com.vaadin.flow.function.SerializableConsumer;
import com.vaadin.flow.function.ValueProvider;
import com.vaadin.flow.internal.JsonSerializer;

/**
 * Base class for all renderers - classes that take a given model object as
 * input and outputs a set of elements that represents that item in the UI.
 *
 * @author Vaadin Ltd
 *
 * @param 
 *            the type of the input object used inside the template
 *
 * @see ValueProvider
 * @see ComponentRenderer
 * @see LitRenderer
 * @see https://www.polymer-project.org/2.0/docs/devguide/templates
 */
public class Renderer implements Serializable {

    private String template;
    private Map> valueProviders;
    private Map> eventHandlers;

    /**
     * Default constructor.
     */
    protected Renderer() {
    }

    /**
     * Builds a renderer with the specified template.
     *
     * @param template
     *            the template used by the renderer
     *
     * @deprecated since Vaadin 22
     */
    @Deprecated
    protected Renderer(String template) {
        this.template = template;
    }

    /**
     * Sets a property to be used inside the template. Each property is
     * referenced inside the template by using the {@code [[item.property]]}
     * syntax.
     * 
     * Examples:
     *
     * 
     * {@code
     * // Regular property
     * TemplateRenderer. of("Name: [[item.name]]")
     *          .withProperty("name", Person::getName);
     *
     * // Property that uses a bean. Note that in this case the entire "Address" object will be sent to the template.
     * // Note that even properties of the bean which are not used in the template are sent to the client, so use
     * // this feature with caution.
     * TemplateRenderer. of("Street: [[item.address.street]]")
     *          .withProperty("address", Person::getAddress);
     *
     * // In this case only the street field inside the Address object is sent
     * TemplateRenderer. of("Street: [[item.street]]")
     *          .withProperty("street", person -> person.getAddress().getStreet());
     * }
     * 
     *
     * Any types supported by the {@link JsonSerializer} are valid types for the
     * Renderer.
     *
     * @param property
     *            the name of the property used inside the template, not
     *            null
     * @param provider
     *            a {@link ValueProvider} that provides the actual value for the
     *            property, not null
     *
     * @deprecated since Vaadin 22
     */
    @Deprecated
    protected void setProperty(String property,
            ValueProvider provider) {
        Objects.requireNonNull(property, "The property must not be null");
        Objects.requireNonNull(provider, "The value provider must not be null");
        if (valueProviders == null) {
            valueProviders = new HashMap<>();
        }
        valueProviders.put(property, provider);
    }

    /**
     * Sets an event handler for events from elements inside the template. Each
     * event is referenced inside the template by using the {@code on-event}
     * syntax.
     * 
     * Examples:
     *
     * 
     * {@code
     * // Standard event
     * TemplateRenderer.of("")
     *          .withEventHandler("handleClick", object -> doSomething());
     *
     * // You can handle custom events from webcomponents as well, using the same syntax
     * TemplateRenderer.of("")
     *          .withEventHandler("onCustomEvent", object -> doSomething());
     * }
     * 
     *
     * The name of the function used on the {@code on-event} attribute should be
     * the name used at the handlerName parameter. This name must be a valid
     * Javascript function name.
     *
     * @param handlerName
     *            the name of the handler used inside the
     *            {@code on-event="handlerName"}, not null
     * @param handler
     *            the handler executed when the event is triggered, not
     *            null
     * @see https://www.polymer-project.org/2.0/docs/devguide/events
     *
     * @deprecated since Vaadin 22
     */
    @Deprecated
    protected void setEventHandler(String handlerName,
            SerializableConsumer handler) {
        Objects.requireNonNull(handlerName, "The handlerName must not be null");
        Objects.requireNonNull(handler, "The event handler must not be null");
        if (eventHandlers == null) {
            eventHandlers = new HashMap<>();
        }
        eventHandlers.put(handlerName, handler);
    }

    /**
     * Handles the rendering of the model objects by creating a new
     * {@code