org.fluentlenium.core.inject.Parent Maven / Gradle / Ivy

package org.fluentlenium.core.inject;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * Mark a field whose class declaration is annotated with one of Selenium's {@code Find...} annotation,
 * with this annotation to inject the parent container. Parent container in this case means parent in the HTML DOM.
 *
 * It doesn't matter if the parent is a direct parent or is any element that is upper in the DOM relative to the current element.
 * What element the parent represents depends on the {@code Find...} annotation applied on the parent component or page class.
 *
 * Examples
 * For an HTML snippet like
 *  *  <div id="homepage">
 *      <div class="component">
 *          <div class="sub-component">
 *              ...
 *          </div>
 *      </div>
 * </div>
 * 
 * there can be a custom component for the {@code div.component} element:
 *  * @FindBy(className = "component")
 * public class Component extends FluentWebElement {
 *      @Parent
 *      public Homepage homepage;
 *      ...
 * }
 * 
 * for which a sub-component can include it as a parent component:
 *  * @FindBy(className = "sub-component")
 * public class SubComponent extends FluentWebElement {
 *      @Parent
 *      public Component parent;
 *      ...
 * }
 * 
 * Similarly a parent can be created for {@code Component} in the form of a page:
 *  * @FindBy(id = "homepage")
 * public class Homepage extends FluentPage {
 *      ...
 * }
 * 
 * This structure can be achieved with any page-component/component-page relationship using custom
 * {@link org.fluentlenium.core.FluentPage} and {@link org.fluentlenium.core.domain.FluentWebElement} implementations.
 */
@Target(FIELD)
@Retention(RUNTIME)
public @interface Parent {
}