com.gwtplatform.idhandler.client.ElementIdHandler Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of cedar-common-gwt Show documentation
Utility code for use with GWT and Mvp4g.
There is a newer version: 5.8.4
/**
 * Copyright 2011 ArcBees Inc.
 *
 * 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.gwtplatform.idhandler.client;

/**
 * Interface implemented by classes that generate and set DOM element IDs into appropriate fields of an owner.
 *
 * Code Source
 *
 * 
 * This is external code that was copied into the CedarCommon codebase under
 * the terms of its license.
 * 
 *
 * 
 *    
 *       
 *          
 *             
 *             
 *          
 *          
 *             
 *             
 *          
 *       
 *    Source: GWTP Issue #389
Date: March, 2011
 * 
 *
 * Original Documentation
 *
 * 
 * Generated element IDs are guaranteed to be unique and deterministic within the context of the given owner type.
 * 

 * Implementations of this interface are intended to be generated for each specific owner type, for example:
 *
 * 
 * public class HelloWorld {
 *
 *     interface MyIdHandler extends ElementIdHandler<HelloWorld> {}
 *     private static MyIdHandler idHandler = GWT.create(MyIdHandler.class);
 *
 *     @WithElementId
 *     Label label;
 *
 *     public HelloWorld() {
 *         label = new Label("Hello World");
 *         idHandler.generateAndSetIds(this);
 *     }
 *
 * }
 * 
 *
 * In the example above, the label widget's DOM element will have its ID set to {@code HelloWorld_label}.
 * 
 * In case there are multiple instances of the same owner type displayed on the page, you can extend IDs generated for
 * those instances during runtime, for example:
 *
 * 
 * public class HelloWorld {
 *
 *     ...
 *
 *     @WithElementId
 *     Label label;
 *
 *     public HelloWorld(String extension) {
 *         label = new Label("Hello World");
 *         idHandler.setIdExtension(extension);
 *         idHandler.generateAndSetIds(this);
 *     }
 *
 * }
 *
 * public class MyApplication {
 *
 *     public void initialize() {
 *         new HelloWorld("One");
 *         new HelloWorld("Two");
 *     }
 *
 * }
 * 
 *
 * This will cause label widgets to have following IDs set on their DOM elements:
 * 
 * 

 * {@code HelloWorld_label_One} for {@code HelloWorld} instance "One"
 * 
{@code HelloWorld_label_Two} for {@code HelloWorld} instance "Two"
 * 
 *
 * @param 
 *            The type of an object that contains {@literal @WithElementId} fields.
 *
 * @see WithElementId
 * @see HasElementId
 */
public interface ElementIdHandler {

    /**
     * Generates and sets DOM element IDs into appropriate fields of the given root object.
     *
     * @param owner
     *            The object whose {@literal @WithElementId} fields need to be processed.
     */
    void generateAndSetIds(T owner);

    /**
     * Extends generated DOM element IDs with the given value at runtime.
     * 
     * This can be helpful when there are multiple instances of the same owner type displayed on the page.
     * 
     * Providing {@code null} or empty String has no effect.
     *
     * @param extension
     *            String value to append to DOM element IDs.
     */
    void setIdExtension(String extension);

}