Package com.oorian.html

Class Element<T extends Element<T>>

java.lang.Object
com.oorian.html.Element<T>
Direct Known Subclasses:
Base, ContainerElement, Head, Link, Meta, Param, RawTextElement, Script, Source, Text, Track, VisualElement
public abstract class Element<T extends Element<T>> extends Object
Base class for all HTML elements in the Oorian framework.

The Element class provides the foundation for building dynamic, server-side HTML elements with bidirectional communication between server and client. It manages the element hierarchy, attributes, lifecycle, and event dispatching.

Features:

  • Parent-child element relationships with automatic ID assignment
  • Attribute management with automatic DOM synchronization
  • Event dispatching for both client and server events
  • Lifecycle management (initialization, creation, updates)
  • Weak reference handling to prevent memory leaks
  • Dynamic content updates with minimal DOM manipulation
  • Drag and drop support
  • JavaScript execution from server-side code

Usage:


 public class MyElement extends Element {
     public MyElement() {
         super("div");
     }

     @Override
     protected void initialize() {
         // Setup element structure
         addElement(new Text("Hello World"));
     }

     @Override
     protected void create() {
         // Configure element after initialization
         addAttribute("class", "my-element");
     }
 }
Since:
2007
Version:
1.0
Author:
Marvin P. Warble Jr.
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Element()
    Constructs a new Element with default initialization.
    Element(String tagName)
    Constructs a new Element with the specified HTML tag name.
    Element(String tagName, boolean closed)
    Constructs a new Element with the specified HTML tag name and tag type.

  • Method Summary

    Modifier and Type
    Method
    Description
    final Element
    addAttribute(String name)
    Adds a boolean HTML attribute (an attribute with no value).
    final Element
    addAttribute(String name, boolean flag)
    Adds or removes a boolean HTML attribute based on the flag value.
    final Element
    addAttribute(String name, String value)
    Adds an HTML attribute with the specified name and value.
    final Element
    addAttribute(String name, String value, boolean updateDom)
    Adds an HTML attribute with control over DOM synchronization.
    T
    addElement(Element child)
    Adds a child element to this element.
    protected void
    addLineBreak()
    Adds a line break element.
    protected void
    addLineOfText(String text)
    Appends text content followed by a line break to this element.
    protected void
    addLineOfText(String text, CssStyle style)
    Appends text content with a CssStyle followed by a line break to this element.
    protected void
    addLineOfText(String text, String style)
    Appends text content with inline CSS styling followed by a line break to this element.
    protected void
    addParagraph()
    Adds an empty paragraph element.
    protected void
    addParagraph(String text)
    Adds a paragraph element containing the specified text.
    protected void
    addSpacer(int height)
    Adds a vertical spacer element with the specified height in pixels.
    protected void
    addText(Text text)
    Appends a Text element to this element.
    void
    addText(String text)
    Appends text content to this element.
    protected void
    addText(String text, CssStyle style)
    Appends text content with a CssStyle to this element.
    protected void
    addText(String text, String style)
    Appends text content with inline CSS styling to this element.
    final void
    assignId(HtmlPage page)
    Assigns an auto-generated ID to this element from the page's ID sequence.
    boolean
    containsElement(Element child)
    Checks if this element contains the specified child element.
    boolean
    containsElement(String id)
    Checks if this element contains a descendant with the specified ID.
    protected void
    create()
    Hook method called during element creation.
    final void
    dispatchEvent(ClientEvent event)
    Dispatches a client event to registered listeners.
    final void
    dispatchEvent(ExtServerEvent event)
    Dispatches an extended server event to registered listeners.
    final void
    dispatchEvent(PageEvent event)
    Dispatches a page event to the page's event dispatcher.
    final void
    dispatchEvent(ServerEvent event)
    Dispatches a server event to registered listeners.
    boolean
    equals(Object object)
    Compares this element to another object for equality.
    protected final void
    excludeId()
    Excludes the ID from being rendered in the HTML output.
    protected final void
    executeJs(String statement)
    Executes a JavaScript statement on the client.
    protected final void
    executeJs(String function, Object... parameters)
    Executes a JavaScript function on the client with the specified parameters.
    protected final void
    executeJs(String function, List<Object> parameters)
    Executes a JavaScript function on the client with parameters from a list.
    protected String
    getAccept()
    Returns the accept attribute value.
    Elements
    getAllElements()
    Returns all elements in this element's subtree.
    Element
    getAncestor(int generation)
    Returns an ancestor element at the specified generation distance.
    final String
    getAttribute(String name)
    Returns the value of the specified attribute.
    final AttributeMap
    getAttributes()
    Returns a copy of all attributes on this element.
    final String
    getComponent()
    Returns the data-component attribute value that identifies this element as a custom component.
    String
    getDir()
    Returns the dir attribute value.
    Element
    getElement(int index)
    Returns the child element at the specified index.
    Element
    getElementById(String id)
    Finds a descendant element by its ID.
    int
    getElementCount()
    Returns the number of child elements.
    int
    getElementCount(boolean recursive)
    Returns the number of child elements, optionally including all descendants.
    Elements
    getElements()
    Returns the direct children of this element.
    Elements
    getElements(boolean recursive)
    Returns the children of this element, optionally including all descendants.
    Elements
    getElementsByComponentName(String componentName, boolean recursive)
    Returns all descendant elements that have the specified data-component attribute value.
    Elements
    getElementsByTagName(String tagName, boolean recursive)
    Finds all descendant elements with the specified tag name.
    String
    getHtml()
    Returns the complete HTML of this element including its tags and children.
    void
    getHtml(StringBuilder sb)
    Appends this element's HTML to the provided StringBuilder.
    final String
    getId()
    Returns the unique identifier for this element.
    String
    getInnerHtml()
    Returns the inner HTML content of this element (excluding the element's own tags).
    protected void
    getInnerHtml(StringBuilder sb)
    Appends the inner HTML of this element to the specified StringBuilder.
    protected String
    getIs()
    Returns the is attribute value.
    protected String
    getItemId()
    Returns the itemid attribute value.
    protected String
    getItemProp()
    Returns the itemprop attribute value.
    protected String
    getItemRef()
    Returns the itemref attribute value.
    protected String
    getItemType()
    Returns the itemtype attribute value.
    String
    getLang()
    Returns the lang attribute value.
    Element
    getNextSibling()
    Returns the next sibling element (the element immediately after this one in the parent's children).
    final HtmlPage
    getPage()
    Returns the page this element is attached to.
    final Element
    getParent()
    Returns the parent element.
    protected String
    getPart()
    Returns the part attribute value.
    Element
    getPrevSibling()
    Returns the previous sibling element (the element immediately before this one in the parent's children).
    protected String
    getSlot()
    Returns the slot attribute value.
    final String
    getTagName()
    Returns the HTML tag name for this element.
    String
    getTextContent()
    Returns the text content of this element and all its descendants.
    protected String
    getUrl(Class<? extends HttpFile> pageClass, Object... urlParams)
    Constructs a URL for the specified page class with optional parameters.
    final boolean
    hasAttribute(String name)
    Checks if this element has the specified attribute.
    boolean
    hasElements()
    Checks if this element has any child elements.
    protected void
    hidden()
    Called when this element has been hidden due to a parent's visibility change.
    protected void
    initialize()
    Hook method called during element initialization.
    protected T
    insertElement(int index, Element child)
    Inserts a child element at the specified index.
    boolean
    isChildOf(String id)
    Checks if this element is a direct child of the element with the specified ID.
    boolean
    isClosedTag()
    Checks if this element uses a self-closing tag.
    final boolean
    isCreated()
    Checks if this element has been created (completed the create lifecycle).
    boolean
    isDescendantOf(Element element)
    Checks if this element is a descendant of the specified element.
    boolean
    isDescendantOf(String id)
    Checks if this element is a descendant of the element with the specified ID.
    boolean
    isInitialized()
    Checks if this element has been initialized.
    protected boolean
    isItemScope()
    Returns whether the itemscope attribute is set.
    boolean
    isTranslate()
    Returns whether translate is enabled.
    void
    onCallback(String callbackId)
    Callback method invoked when a client callback is received.
    protected void
    onCreated()
    Hook method called after the element has been created.
    protected void
    onElementAdded(Element child)
    Hook method called when a child element has been added.
    protected void
    onElementRemoved(Element child)
    Hook method called when a child element has been removed.
    protected void
    onHashChange(String hash)
    Hook method called when the URL hash fragment changes.
    protected void
    onHidden()
    Hook method called when this element is hidden.
    protected void
    onInitialized()
    Hook method called after the element has been initialized.
    void
    onJsReturn(String callbackId, String retval)
    Callback method invoked when a JavaScript function returns a value.
    protected void
    onPageLoaded()
    Hook method called when the page has finished loading.
    protected void
    onPageUnloaded()
    Hook method called when the page is being unloaded.
    protected void
    onRefresh()
    Hook method called during refresh operations.
    protected void
    onRemovedFromPage()
    Hook method called when this element is removed from a page.
    protected void
    onShown()
    Hook method called when this element is shown.
    protected void
    onUpdated()
    Hook method called after the element has been updated.
    void
    onUserEvent(UserEvent event)
    Callback method invoked when a user event is received.
    protected void
    prewrite()
    Hook method called before the element is written to output.
    final void
    recreate()
    Recreates this element by resetting and re-running the create lifecycle.
    void
    refresh()
    Refreshes this element and all its descendants.
    void
    refresh(Element refresher)
    Refreshes this element and descendants, excluding the refresher element.
    protected void
    registerAddition()
    Registers this element for addition to the DOM.
    void
    registerListener(ClientEventListener listener, Class<? extends ClientEvent> eventType)
    Registers a listener for client events of the specified type.
    void
    registerListener(ClientEventListener listener, Class<? extends ClientEvent> eventType, Boolean value)
    Registers a listener for client events with a boolean value.
    void
    registerListener(ClientEventListener listener, Class<? extends ClientEvent> eventType, Number value)
    Registers a listener for client events with a numeric value.
    void
    registerListener(ClientEventListener listener, Class<? extends ClientEvent> eventType, String value)
    Registers a listener for client events with a string value.
    void
    registerListener(ExtServerEventListener listener, Class<? extends ExtServerEvent>... eventTypes)
    Registers a listener for one or more extended server event types.
    void
    registerListener(PageEventListener listener, Class<? extends PageEvent>... eventTypes)
    Registers a listener for page-level events.
    void
    registerListener(ServerEventListener listener, Class<? extends ServerEvent>... eventTypes)
    Registers a listener for one or more server event types.
    protected void
    registerSubtraction()
    Registers this element for removal from the DOM.
    void
    registerUpdate()
    Registers this element for update in the DOM.
    protected void
    removeAllElements()
    Removes all child elements from this element.
    final void
    removeAttribute(String name)
    Removes an HTML attribute from this element.
    final void
    removeAttribute(String name, boolean updateDom)
    Removes an HTML attribute with control over DOM synchronization.
    protected void
    removeElement(Element child)
    Removes a child element from this element.
    protected void
    removeElement(String id)
    Removes a child element by its ID.
    final void
    removeFromParent()
    Removes this element from its parent.
    void
    requestCallback()
    Requests a callback from the client.
    void
    requestCallback(long delay)
    Requests a delayed callback from the client.
    void
    requestCallback(String id)
    Requests a callback from the client with a specific identifier.
    void
    requestCallback(String id, long delay)
    Requests a delayed callback from the client with a specific identifier.
    final void
    resetId(String parentId)
    Resets the element's ID if it matches the specified parent ID prefix.
    final void
    scrollTo(int pos)
    Scrolls this element to the specified position.
    final void
    scrollToBottom()
    Scrolls this element to the bottom.
    final void
    scrollToTop()
    Scrolls this element to the top.
    protected final T
    self()
     
    protected void
    sendCommand(Command command)
    Sends a command to the client.
    void
    sendUpdate()
    Sends pending updates to the client.
    protected T
    setAccept(String accept)
    Sets the accept attribute.
    final void
    setComponent(String componentName)
    Sets the data-component attribute to identify this element as a custom component in the DOM.
    T
    setDir(TextDirection direction)
    Sets the text direction for the element using a TextDirection enum value.
    T
    setDir(String dir)
    Sets the dir attribute for text directionality.
    protected T
    setElement(Element child)
    Replaces all child elements with a single child element.
    final T
    setId(String id)
    Sets the unique identifier for this element.
    protected T
    setIs(String is)
    Sets the is attribute for custom element identification.
    protected T
    setItemId(String itemId)
    Sets the itemid attribute for microdata.
    protected T
    setItemProp(String itemProp)
    Sets the itemprop attribute for microdata.
    protected T
    setItemRef(String itemRef)
    Sets the itemref attribute for microdata.
    protected T
    setItemScope(boolean itemScope)
    Sets the itemscope boolean attribute for microdata.
    protected T
    setItemType(String itemType)
    Sets the itemtype attribute for microdata.
    T
    setLang(String lang)
    Sets the lang attribute for the element's language.
    void
    setOnError(String value)
    Sets the JavaScript onerror event handler for this element.
    void
    setOnLoad(String value)
    Sets the JavaScript onload event handler for this element.
    final void
    setPage(HtmlPage page)
    Associates this element and all its descendants with the specified page.
    final void
    setParent(Element parent)
    Sets the parent element for this element.
    protected T
    setPart(String part)
    Sets the part attribute for CSS shadow parts.
    protected T
    setSlot(String slot)
    Sets the slot attribute for shadow DOM slot assignment.
    protected final void
    setTagName(String tagName)
    Sets the HTML tag name for this element.
    void
    setText(String text)
    Sets the text content of this element, replacing any existing content.
    protected void
    setText(String text, CssStyle style)
    Sets the text content of this element with a CssStyle, replacing any existing content.
    protected void
    setText(String text, Font font)
    Sets the text content of this element with a font, replacing any existing content.
    protected void
    setText(String text, String style)
    Sets the text content of this element with inline CSS styling, replacing any existing content.
    T
    setTranslate(boolean translate)
    Sets the translate attribute.
    protected void
    shown()
    Called when this element has become visible due to a parent's visibility change.
    String
    toString()
    Returns a string representation of this element.
    void
    unregisterListener(EventListener listener)
    Unregisters a listener from this element's event dispatcher.
    final void
    update()
    Triggers a DOM update for this element.
    final void
    updateAttributes()
    Triggers an attribute update for this element.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Element

      public Element()
      Constructs a new Element with default initialization.

      Initializes the children collection, attributes map, and event dispatcher.

    • Element

      public Element(String tagName)
      Constructs a new Element with the specified HTML tag name.

      Creates a closed tag element (requires closing tag like </div>).

      Parameters:
      tagName - The HTML tag name (e.g., "div", "span", "table").

    • Element

      public Element(String tagName, boolean closed)
      Constructs a new Element with the specified HTML tag name and tag type.
      Parameters:
      tagName - The HTML tag name (e.g., "div", "span", "br").
      closed - true for closed tags (requires closing tag), false for self-closing tags.

  • Method Details

    • setId

      public final T setId(String id)
      Sets the unique identifier for this element.

      The ID is also added as an HTML attribute for client-side identification.

      Parameters:
      id - The unique identifier for this element.
      Returns:
      This element for method chaining.

    • setComponent

      public final void setComponent(String componentName)
      Sets the data-component attribute to identify this element as a custom component in the DOM.

      The data-component attribute provides a semantic way to mark elements that represent custom components, independent of their HTML tag name or CSS classes. This is useful for:

      • Identifying custom component instances within a complex element tree
      • Locating components programmatically via getElementsByComponentName(String, boolean)
      • Client-side JavaScript component initialization and binding
      • Distinguishing between multiple instances of the same element type serving different roles

      Usage:

      
 // Mark a div as a custom "user-card" component
 Div card = new Div();
 card.setComponent("user-card");

 // Later, find all user-card components in a container
 Elements cards = container.getElementsByComponentName("user-card", true);
      Parameters:
      componentName - the component name to assign; should be a descriptive, lowercase, hyphen-separated identifier (e.g., "date-picker", "user-card")

    • setParent

      public final void setParent(Element parent)
      Sets the parent element for this element.

      The parent is stored as a weak reference to prevent memory leaks.

      Parameters:
      parent - The parent element.

    • setPage

      public final void setPage(HtmlPage page)
      Associates this element and all its descendants with the specified page.

      This method assigns an ID to this element if needed and propagates the page reference to all child elements. If page is null, it triggers the onRemovedFromPage() callback.

      Parameters:
      page - The page to associate with, or null to disassociate.

    • setDir

      public T setDir(String dir)
      Sets the dir attribute for text directionality.

      Specifies the text direction (ltr, rtl, auto).

      Parameters:
      dir - The text direction value.
      Returns:
      This element for method chaining.

    • setDir

      public T setDir(TextDirection direction)
      Sets the text direction for the element using a TextDirection enum value.
      Parameters:
      direction - The text direction (LTR or RTL).
      Returns:
      This element for method chaining.

    • setLang

      public T setLang(String lang)
      Sets the lang attribute for the element's language.

      Specifies the language of the element's content.

      Parameters:
      lang - The BCP 47 language tag.
      Returns:
      This element for method chaining.

    • setTranslate

      public T setTranslate(boolean translate)
      Sets the translate attribute.

      Specifies whether the element's content should be translated when the page is localized.

      Parameters:
      translate - True to enable translation, false to disable.
      Returns:
      This element for method chaining.

    • setOnLoad

      public void setOnLoad(String value)
      Sets the JavaScript onload event handler for this element.

      Fires when the element and its dependent resources have finished loading. Applicable to elements such as <script>, <link>, <style>, <img>, <iframe>, <body>, <object>, and <embed>.

      Parameters:
      value - The JavaScript code to execute on load.

    • setOnError

      public void setOnError(String value)
      Sets the JavaScript onerror event handler for this element.

      Fires when the element fails to load its dependent resource. Applicable to elements such as <script>, <link>, <style>, <img>, <audio>, <video>, and <object>.

      Parameters:
      value - The JavaScript code to execute on error.

    • addElement

      public T addElement(Element child)
      Adds a child element to this element.

      The child is removed from its previous parent if it has one, then added to this element's children. If this element is already attached to a page, the child is also attached and registered for DOM addition.

      Parameters:
      child - The child element to add.
      Returns:
      this element for method chaining

    • addText

      public void addText(String text)
      Appends text content to this element.
      Parameters:
      text - The text content to append.

    • setText

      public void setText(String text)
      Sets the text content of this element, replacing any existing content.
      Parameters:
      text - The text content to set.

    • getDir

      public String getDir()
      Returns the dir attribute value.
      Returns:
      The text direction, or null if not set.

    • getLang

      public String getLang()
      Returns the lang attribute value.
      Returns:
      The language tag, or null if not set.

    • isTranslate

      public boolean isTranslate()
      Returns whether translate is enabled.
      Returns:
      true if translation is enabled, false otherwise.

    • isInitialized

      public boolean isInitialized()
      Checks if this element has been initialized.
      Returns:
      true if initialize() has been called, false otherwise.

    • getParent

      public final Element getParent()
      Returns the parent element.
      Returns:
      The parent element, or null if this element has no parent.

    • getPage

      public final HtmlPage getPage()
      Returns the page this element is attached to.
      Returns:
      The HtmlPage, or null if not attached to a page.

    • getTagName

      public final String getTagName()
      Returns the HTML tag name for this element.
      Returns:
      The tag name (e.g., "div", "span", "table").

    • getId

      public final String getId()
      Returns the unique identifier for this element.
      Returns:
      The element's ID, or null if not set.

    • getComponent

      public final String getComponent()
      Returns the data-component attribute value that identifies this element as a custom component.

      Returns the component name previously set via setComponent(String), or null if no component name has been assigned to this element.

      Returns:
      the component name, or null if the data-component attribute is not set
      See Also:

    • hasAttribute

      public final boolean hasAttribute(String name)
      Checks if this element has the specified attribute.
      Parameters:
      name - The attribute name to check.
      Returns:
      true if the attribute exists, false otherwise.

    • getAttribute

      public final String getAttribute(String name)
      Returns the value of the specified attribute.
      Parameters:
      name - The attribute name.
      Returns:
      The attribute value, or null if not found.

    • getAttributes

      public final AttributeMap getAttributes()
      Returns a copy of all attributes on this element.
      Returns:
      A copy of the attribute map.

    • isCreated

      public final boolean isCreated()
      Checks if this element has been created (completed the create lifecycle).
      Returns:
      true if create() has been called, false otherwise.

    • getInnerHtml

      public String getInnerHtml()
      Returns the inner HTML content of this element (excluding the element's own tags).
      Returns:
      The HTML content of all child elements.

    • getHtml

      public String getHtml() throws ElementException
      Returns the complete HTML of this element including its tags and children.
      Returns:
      The complete HTML representation.
      Throws:
      ElementException - If an error occurs during HTML generation.

    • getAncestor

      public Element getAncestor(int generation)
      Returns an ancestor element at the specified generation distance.

      A generation of 1 returns the parent, 2 returns the grandparent, etc.

      Parameters:
      generation - The number of generations up the hierarchy.
      Returns:
      The ancestor element, or null if not found.

    • getTextContent

      public String getTextContent()
      Returns the text content of this element and all its descendants.

      HTML tags, script content, style content, and HTML comments are removed. Special HTML entities are replaced with spaces.

      Returns:
      The plain text content.

    • hasElements

      public boolean hasElements()
      Checks if this element has any child elements.
      Returns:
      true if this element has children, false otherwise.

    • getElement

      public Element getElement(int index)
      Returns the child element at the specified index.
      Parameters:
      index - The zero-based index of the child.
      Returns:
      The child element, or null if index is out of bounds.

    • getElements

      public Elements getElements()
      Returns the direct children of this element.
      Returns:
      A copy of the children collection.

    • getElements

      public Elements getElements(boolean recursive)
      Returns the children of this element, optionally including all descendants.
      Parameters:
      recursive - If true, returns all elements at every level; if false, returns only direct children.
      Returns:
      A collection of elements.

    • getAllElements

      public Elements getAllElements()
      Returns all elements in this element's subtree.
      Returns:
      A collection of all elements at every level.

    • getElementCount

      public int getElementCount()
      Returns the number of child elements.
      Returns:
      The count of direct child elements.

    • getElementCount

      public int getElementCount(boolean recursive)
      Returns the number of child elements, optionally including all descendants.
      Parameters:
      recursive - If true, counts all descendants; if false, counts only direct children.
      Returns:
      The element count.

    • getNextSibling

      public Element getNextSibling()
      Returns the next sibling element (the element immediately after this one in the parent's children).
      Returns:
      The next sibling, or null if this is the last child or has no parent.

    • getPrevSibling

      public Element getPrevSibling()
      Returns the previous sibling element (the element immediately before this one in the parent's children).
      Returns:
      The previous sibling, or null if this is the first child or has no parent.

    • containsElement

      public boolean containsElement(Element child)
      Checks if this element contains the specified child element.
      Parameters:
      child - The element to check for.
      Returns:
      true if the child is a direct child of this element, false otherwise.

    • containsElement

      public boolean containsElement(String id)
      Checks if this element contains a descendant with the specified ID.
      Parameters:
      id - The ID to search for.
      Returns:
      true if a descendant with the ID exists, false otherwise.

    • getElementById

      public Element getElementById(String id)
      Finds a descendant element by its ID.

      Searches this element's children and all descendants recursively.

      Parameters:
      id - The ID to search for.
      Returns:
      The element with the matching ID, or null if not found.

    • getElementsByTagName

      public Elements getElementsByTagName(String tagName, boolean recursive)
      Finds all descendant elements with the specified tag name.
      Parameters:
      tagName - The HTML tag name to search for.
      recursive - If true, searches all descendants; if false, only direct children.
      Returns:
      A collection of matching elements.

    • getElementsByComponentName

      public Elements getElementsByComponentName(String componentName, boolean recursive)
      Returns all descendant elements that have the specified data-component attribute value.

      Searches the children of this element for elements whose data-component attribute matches the given component name. This provides a way to locate custom component instances within the element tree, similar to how getElementsByTagName(String, boolean) locates elements by HTML tag name.

      Usage:

      
 // Find all "chart-widget" components in the page body
 Elements charts = body.getElementsByComponentName("chart-widget", true);

 // Find only direct child components (non-recursive)
 Elements topLevel = container.getElementsByComponentName("nav-item", false);
      Parameters:
      componentName - the component name to search for, as set by setComponent(String)
      recursive - if true, searches the entire subtree; if false, searches only direct children
      Returns:
      an Elements collection of matching elements; never null but may be empty
      See Also:

    • isChildOf

      public boolean isChildOf(String id)
      Checks if this element is a direct child of the element with the specified ID.
      Parameters:
      id - The ID of the potential parent.
      Returns:
      true if this element's parent has the specified ID, false otherwise.

    • isDescendantOf

      public boolean isDescendantOf(Element element)
      Checks if this element is a descendant of the specified element.
      Parameters:
      element - The potential ancestor element.
      Returns:
      true if this element is a descendant, false otherwise.

    • isDescendantOf

      public boolean isDescendantOf(String id)
      Checks if this element is a descendant of the element with the specified ID.
      Parameters:
      id - The ID of the potential ancestor.
      Returns:
      true if this element is a descendant, false otherwise.

    • resetId

      public final void resetId(String parentId)
      Resets the element's ID if it matches the specified parent ID prefix.

      This method is used during element re-parenting to reset hierarchical IDs.

      Parameters:
      parentId - The parent ID to check against.

    • assignId

      public final void assignId(HtmlPage page)
      Assigns an auto-generated ID to this element from the page's ID sequence.

      If the element doesn't already have an ID and IDs are not excluded, a new unique ID is generated in the format "ai-{sequence}".

      Parameters:
      page - The page to get the next ID from.

    • removeFromParent

      public final void removeFromParent()
      Removes this element from its parent.

      If this element has a parent, it is removed from the parent's children collection.

    • addAttribute

      public final Element addAttribute(String name, String value)
      Adds an HTML attribute with the specified name and value.

      If the value is null, the attribute is removed instead.

      Parameters:
      name - The attribute name.
      value - The attribute value.
      Returns:
      This element for method chaining.

    • addAttribute

      public final Element addAttribute(String name, String value, boolean updateDom)
      Adds an HTML attribute with control over DOM synchronization.

      If the value is null, the attribute is removed instead.

      Parameters:
      name - The attribute name.
      value - The attribute value.
      updateDom - If true, triggers a DOM update on the client.
      Returns:
      This element for method chaining.

    • addAttribute

      public final Element addAttribute(String name)
      Adds a boolean HTML attribute (an attribute with no value).

      Boolean attributes like "disabled", "readonly", or "checked" are present or absent rather than having a value.

      Parameters:
      name - The attribute name.
      Returns:
      This element for method chaining.

    • addAttribute

      public final Element addAttribute(String name, boolean flag)
      Adds or removes a boolean HTML attribute based on the flag value.

      If flag is true, the attribute is added. If false, it is removed.

      Parameters:
      name - The attribute name.
      flag - If true, adds the attribute; if false, removes it.
      Returns:
      This element for method chaining.

    • removeAttribute

      public final void removeAttribute(String name)
      Removes an HTML attribute from this element.
      Parameters:
      name - The attribute name to remove.

    • removeAttribute

      public final void removeAttribute(String name, boolean updateDom)
      Removes an HTML attribute with control over DOM synchronization.
      Parameters:
      name - The attribute name to remove.
      updateDom - If true, triggers a DOM update on the client.

    • registerListener

      public void registerListener(ClientEventListener listener, Class<? extends ClientEvent> eventType)
      Registers a listener for client events of the specified type.

      The element's attributes are updated to trigger event generation on the client side.

      Parameters:
      listener - The listener to receive events.
      eventType - The class of client event to listen for.

    • registerListener

      public void registerListener(ClientEventListener listener, Class<? extends ClientEvent> eventType, Number value)
      Registers a listener for client events with a numeric value.
      Parameters:
      listener - The listener to receive events.
      eventType - The class of client event to listen for.
      value - A numeric value associated with the event registration.

    • registerListener

      public void registerListener(ClientEventListener listener, Class<? extends ClientEvent> eventType, Boolean value)
      Registers a listener for client events with a boolean value.
      Parameters:
      listener - The listener to receive events.
      eventType - The class of client event to listen for.
      value - A boolean value associated with the event registration.

    • registerListener

      public void registerListener(ClientEventListener listener, Class<? extends ClientEvent> eventType, String value)
      Registers a listener for client events with a string value.

      This is the core registration method that updates client event attributes and registers the listener with the event dispatcher.

      Parameters:
      listener - The listener to receive events.
      eventType - The class of client event to listen for.
      value - A string value associated with the event registration.

    • registerListener

      public void registerListener(ServerEventListener listener, Class<? extends ServerEvent>... eventTypes)
      Registers a listener for one or more server event types.
      Parameters:
      listener - The listener to receive events.
      eventTypes - The classes of server events to listen for.

    • registerListener

      public void registerListener(ExtServerEventListener listener, Class<? extends ExtServerEvent>... eventTypes)
      Registers a listener for one or more extended server event types.
      Parameters:
      listener - The listener to receive events.
      eventTypes - The classes of extended server events to listen for.

    • registerListener

      public void registerListener(PageEventListener listener, Class<? extends PageEvent>... eventTypes)
      Registers a listener for page-level events.

      The listener is registered with the page rather than the element.

      Parameters:
      listener - The listener to receive page events.
      eventTypes - The classes of page events to listen for.

    • unregisterListener

      public void unregisterListener(EventListener listener)
      Unregisters a listener from this element's event dispatcher.
      Parameters:
      listener - The listener to unregister.

    • dispatchEvent

      public final void dispatchEvent(ServerEvent event)
      Dispatches a server event to registered listeners.

      The event is dispatched to listeners registered on this element. If the event bubbles, it is also dispatched to parent elements.

      Parameters:
      event - The server event to dispatch.

    • dispatchEvent

      public final void dispatchEvent(ExtServerEvent event)
      Dispatches an extended server event to registered listeners.

      The event is dispatched to listeners registered on this element. If the event bubbles, it is also dispatched to parent elements.

      Parameters:
      event - The extended server event to dispatch.

    • dispatchEvent

      public final void dispatchEvent(ClientEvent event)
      Dispatches a client event to registered listeners.

      The event is dispatched to listeners registered on this element. If the event bubbles, it is also dispatched to parent elements.

      Parameters:
      event - The client event to dispatch.

    • dispatchEvent

      public final void dispatchEvent(PageEvent event)
      Dispatches a page event to the page's event dispatcher.
      Parameters:
      event - The page event to dispatch.

    • update

      public final void update()
      Triggers a DOM update for this element.

      The element is registered for update with the page, causing its HTML to be re-rendered and sent to the client.

    • updateAttributes

      public final void updateAttributes()
      Triggers an attribute update for this element.

      If the element has been created, only the attributes are updated on the client. Otherwise, a full element update is triggered.

    • scrollTo

      public final void scrollTo(int pos)
      Scrolls this element to the specified position.
      Parameters:
      pos - The scroll position in pixels.

    • scrollToTop

      public final void scrollToTop()
      Scrolls this element to the top.

    • scrollToBottom

      public final void scrollToBottom()
      Scrolls this element to the bottom.

    • recreate

      public final void recreate()
      Recreates this element by resetting and re-running the create lifecycle.

      This triggers a full DOM update for this element.

    • refresh

      public void refresh()
      Refreshes this element and all its descendants.

      Calls onRefresh() on this element and recursively on all children.

    • refresh

      public void refresh(Element refresher)
      Refreshes this element and descendants, excluding the refresher element.

      Useful when an element triggers a refresh but should not be refreshed itself.

      Parameters:
      refresher - The element that initiated the refresh (will be excluded).

    • getHtml

      public void getHtml(StringBuilder sb)
      Appends this element's HTML to the provided StringBuilder.
      Parameters:
      sb - The StringBuilder to append to.

    • sendUpdate

      public void sendUpdate()
      Sends pending updates to the client.

      If this element has been created and is attached to a page, triggers the page to send all pending DOM updates to the client.

    • requestCallback

      public void requestCallback()
      Requests a callback from the client.

      Sends a command to the browser to trigger a callback to this element's onCallback(String) method with an empty identifier.

    • requestCallback

      public void requestCallback(long delay)
      Requests a delayed callback from the client.

      Sends a command to the browser to trigger a callback to this element's onCallback(String) method after the specified delay.

      Parameters:
      delay - The delay in milliseconds before the callback is triggered.

    • requestCallback

      public void requestCallback(String id)
      Requests a callback from the client with a specific identifier.

      Sends a command to the browser to trigger a callback to this element's onCallback(String) method with the specified identifier.

      Parameters:
      id - The callback identifier to pass to onCallback(String).

    • requestCallback

      public void requestCallback(String id, long delay)
      Requests a delayed callback from the client with a specific identifier.

      Sends a command to the browser to trigger a callback to this element's onCallback(String) method with the specified identifier after the specified delay.

      Parameters:
      id - The callback identifier to pass to onCallback(String).
      delay - The delay in milliseconds before the callback is triggered.

    • isClosedTag

      public boolean isClosedTag()
      Checks if this element uses a self-closing tag.
      Returns:
      true if the tag is self-closing (e.g., <br/>), false otherwise.

    • equals

      public boolean equals(Object object)
      Compares this element to another object for equality.

      Two elements are equal if they have the same ID.

      Overrides:
      equals in class Object
      Parameters:
      object - The object to compare to.
      Returns:
      true if the elements have the same ID, false otherwise.

    • toString

      public String toString()
      Returns a string representation of this element.
      Overrides:
      toString in class Object
      Returns:
      An empty string (subclasses may override for debugging).

    • onCallback

      public void onCallback(String callbackId)
      Callback method invoked when a client callback is received.

      Override this method to handle callbacks requested via requestCallback(String).

      Parameters:
      callbackId - The callback identifier.

    • onJsReturn

      public void onJsReturn(String callbackId, String retval)
      Callback method invoked when a JavaScript function returns a value.

      Override this method to handle return values from JavaScript executions.

      Parameters:
      callbackId - The callback identifier.
      retval - The return value from JavaScript.

    • onUserEvent

      public void onUserEvent(UserEvent event)
      Callback method invoked when a user event is received.

      Override this method to handle custom user events.

      Parameters:
      event - The user event.

    • setTagName

      protected final void setTagName(String tagName)
      Sets the HTML tag name for this element.
      Parameters:
      tagName - The HTML tag name (e.g., "div", "span", "table").

    • setIs

      protected T setIs(String is)
      Sets the is attribute for custom element identification.

      Specifies that a standard HTML element should behave like a registered custom built-in element.

      Parameters:
      is - The custom element name.
      Returns:
      This element for method chaining.

    • setItemId

      protected T setItemId(String itemId)
      Sets the itemid attribute for microdata.

      The global identifier for a microdata item.

      Parameters:
      itemId - The item identifier URL.
      Returns:
      This element for method chaining.

    • setItemProp

      protected T setItemProp(String itemProp)
      Sets the itemprop attribute for microdata.

      Adds a property name to a microdata item.

      Parameters:
      itemProp - The property name.
      Returns:
      This element for method chaining.

    • setItemRef

      protected T setItemRef(String itemRef)
      Sets the itemref attribute for microdata.

      References other elements that are not descendants of the element with the itemscope attribute.

      Parameters:
      itemRef - Space-separated list of element IDs.
      Returns:
      This element for method chaining.

    • setItemScope

      protected T setItemScope(boolean itemScope)
      Sets the itemscope boolean attribute for microdata.

      Creates a new item scope for microdata.

      Parameters:
      itemScope - True to add itemscope, false to remove.
      Returns:
      This element for method chaining.

    • setItemType

      protected T setItemType(String itemType)
      Sets the itemtype attribute for microdata.

      Specifies the URL of the vocabulary used to define item properties.

      Parameters:
      itemType - The item type URL.
      Returns:
      This element for method chaining.

    • setPart

      protected T setPart(String part)
      Sets the part attribute for CSS shadow parts.

      Contains space-separated part names of the element for styling with ::part().

      Parameters:
      part - The part name(s).
      Returns:
      This element for method chaining.

    • setSlot

      protected T setSlot(String slot)
      Sets the slot attribute for shadow DOM slot assignment.

      Assigns a slot in a shadow DOM shadow tree to an element.

      Parameters:
      slot - The slot name.
      Returns:
      This element for method chaining.

    • setAccept

      protected T setAccept(String accept)
      Sets the accept attribute.

      Specifies a comma-separated list of content types that the server accepts. Used on <input> elements with type="file" to filter file selection, and on <form> elements to specify accepted MIME types.

      Parameters:
      accept - Comma-separated list of accepted content types.
      Returns:
      This element for method chaining.

    • getIs

      protected String getIs()
      Returns the is attribute value.
      Returns:
      The custom element name, or null if not set.

    • getItemId

      protected String getItemId()
      Returns the itemid attribute value.
      Returns:
      The item identifier, or null if not set.

    • getItemProp

      protected String getItemProp()
      Returns the itemprop attribute value.
      Returns:
      The item property name, or null if not set.

    • getItemRef

      protected String getItemRef()
      Returns the itemref attribute value.
      Returns:
      The item references, or null if not set.

    • isItemScope

      protected boolean isItemScope()
      Returns whether the itemscope attribute is set.
      Returns:
      true if itemscope is present, false otherwise.

    • getItemType

      protected String getItemType()
      Returns the itemtype attribute value.
      Returns:
      The item type URL, or null if not set.

    • getPart

      protected String getPart()
      Returns the part attribute value.
      Returns:
      The part name(s), or null if not set.

    • getSlot

      protected String getSlot()
      Returns the slot attribute value.
      Returns:
      The slot name, or null if not set.

    • getAccept

      protected String getAccept()
      Returns the accept attribute value.

      The accept attribute specifies which file types are accepted by an <input type="file"> element. The value is a comma-separated list of file extensions (.jpg), MIME types (image/png), or special tokens like audio/*, video/*, image/*.

      Returns:
      The accept value, or null if not set.

    • getUrl

      protected String getUrl(Class<? extends HttpFile> pageClass, Object... urlParams)
      Constructs a URL for the specified page class with optional parameters.

      Delegates to HttpFile.getUrl(Class, Object...) to build the URL.

      Parameters:
      pageClass - The page class to generate a URL for.
      urlParams - The URL parameters to include.
      Returns:
      The constructed URL string.

    • excludeId

      protected final void excludeId()
      Excludes the ID from being rendered in the HTML output.

      When called, the element's ID will not appear in the generated HTML.

    • self

      protected final T self()

    • sendCommand

      protected void sendCommand(Command command)
      Sends a command to the client.
      Parameters:
      command - The command to send.

    • getInnerHtml

      protected void getInnerHtml(StringBuilder sb)
      Appends the inner HTML of this element to the specified StringBuilder.

      Iterates through all child elements and appends their HTML representations to the builder. Uses a synchronized copy of the children list to avoid concurrent modification issues.

      Parameters:
      sb - The StringBuilder to append the inner HTML to.

    • executeJs

      protected final void executeJs(String statement)
      Executes a JavaScript statement on the client.

      Sends a JavaScript command to the browser to execute the specified statement. The command is associated with this element's ID.

      Parameters:
      statement - The JavaScript statement to execute.

    • executeJs

      protected final void executeJs(String function, Object... parameters)
      Executes a JavaScript function on the client with the specified parameters.

      Sends a JavaScript command to the browser to call the specified function with the provided parameters. Parameters are serialized to JSON for transmission.

      Parameters:
      function - The JavaScript function to call.
      parameters - The parameters to pass to the function.

    • executeJs

      protected final void executeJs(String function, List<Object> parameters)
      Executes a JavaScript function on the client with parameters from a list.

      Sends a JavaScript command to the browser to call the specified function with parameters from the provided list. Parameters are serialized to JSON for transmission.

      Parameters:
      function - The JavaScript function to call.
      parameters - The list of parameters to pass to the function.

    • setElement

      protected T setElement(Element child)
      Replaces all child elements with a single child element.

      All existing children are removed before adding the new child.

      Parameters:
      child - The child element to set as the only child.
      Returns:
      This element for method chaining.

    • insertElement

      protected T insertElement(int index, Element child)
      Inserts a child element at the specified index.

      The child is removed from its previous parent if it has one, then inserted at the specified index in this element's children.

      Parameters:
      index - The index at which to insert the child.
      child - The child element to insert.
      Returns:
      this element for method chaining

    • removeElement

      protected void removeElement(Element child)
      Removes a child element from this element.

      The child is unlinked from this parent and registered for DOM removal if the element is attached to a page.

      Parameters:
      child - The child element to remove.

    • removeElement

      protected void removeElement(String id)
      Removes a child element by its ID.
      Parameters:
      id - The ID of the child element to remove.

    • removeAllElements

      protected void removeAllElements()
      Removes all child elements from this element.

      Each child is unlinked and registered for DOM removal if the element is attached to a page.

    • setText

      protected void setText(String text, String style)
      Sets the text content of this element with inline CSS styling, replacing any existing content.
      Parameters:
      text - The text content to set.
      style - The inline CSS style string to apply to the text.

    • setText

      protected void setText(String text, Font font)
      Sets the text content of this element with a font, replacing any existing content.
      Parameters:
      text - The text content to set.
      font - The font to apply to the text.

    • setText

      protected void setText(String text, CssStyle style)
      Sets the text content of this element with a CssStyle, replacing any existing content.
      Parameters:
      text - The text content to set.
      style - The CssStyle to apply to the text.

    • addText

      protected void addText(String text, String style)
      Appends text content with inline CSS styling to this element.
      Parameters:
      text - The text content to append.
      style - The inline CSS style string to apply to the text.

    • addText

      protected void addText(String text, CssStyle style)
      Appends text content with a CssStyle to this element.
      Parameters:
      text - The text content to append.
      style - The CssStyle to apply to the text.

    • addText

      protected void addText(Text text)
      Appends a Text element to this element.
      Parameters:
      text - The Text element to append.

    • addLineOfText

      protected void addLineOfText(String text)
      Appends text content followed by a line break to this element.
      Parameters:
      text - The text content to append.

    • addLineOfText

      protected void addLineOfText(String text, String style)
      Appends text content with inline CSS styling followed by a line break to this element.
      Parameters:
      text - The text content to append.
      style - The inline CSS style string to apply to the text.

    • addLineOfText

      protected void addLineOfText(String text, CssStyle style)
      Appends text content with a CssStyle followed by a line break to this element.
      Parameters:
      text - The text content to append.
      style - The CssStyle to apply to the text.

    • addLineBreak

      protected void addLineBreak()
      Adds a line break element.

    • addSpacer

      protected void addSpacer(int height)
      Adds a vertical spacer element with the specified height in pixels.
      Parameters:
      height - The height of the spacer in pixels.

    • addParagraph

      protected void addParagraph()
      Adds an empty paragraph element.

    • addParagraph

      protected void addParagraph(String text)
      Adds a paragraph element containing the specified text.
      Parameters:
      text - the text content for the paragraph

    • initialize

      protected void initialize()
      Hook method called during element initialization.

      Override this method to set up the element's structure by adding child elements. This is called before create() and only once during the element's lifecycle.

    • create

      protected void create()
      Hook method called during element creation.

      Override this method to configure the element after initialization. This is called after initialize() and only once during the element's lifecycle.

    • prewrite

      protected void prewrite()
      Hook method called before the element is written to output.

      Override this method to perform any last-minute configuration before rendering.

    • onInitialized

      protected void onInitialized()
      Hook method called after the element has been initialized.

      Override this method to perform actions after initialization is complete.

    • onCreated

      protected void onCreated()
      Hook method called after the element has been created.

      Override this method to perform actions after creation is complete.

    • onUpdated

      protected void onUpdated()
      Hook method called after the element has been updated.

      Override this method to perform actions after a DOM update.

    • onPageLoaded

      protected void onPageLoaded()
      Hook method called when the page has finished loading.

      Override this method to perform actions after the page is fully loaded in the browser.

    • onPageUnloaded

      protected void onPageUnloaded()
      Hook method called when the page is being unloaded.

      Override this method to perform cleanup actions when the user navigates away.

    • onElementAdded

      protected void onElementAdded(Element child)
      Hook method called when a child element has been added.
      Parameters:
      child - The child element that was added.

    • onElementRemoved

      protected void onElementRemoved(Element child)
      Hook method called when a child element has been removed.
      Parameters:
      child - The child element that was removed.

    • onRemovedFromPage

      protected void onRemovedFromPage()
      Hook method called when this element is removed from a page.

      Override this method to perform cleanup when the element is detached.

    • onRefresh

      protected void onRefresh()
      Hook method called during refresh operations.

      Override this method to update the element's state during a refresh.

    • onHashChange

      protected void onHashChange(String hash)
      Hook method called when the URL hash fragment changes.

      Override this method to respond to hash-based navigation changes within the page.

      Parameters:
      hash - The new hash fragment value.

    • shown

      protected void shown()
      Called when this element has become visible due to a parent's visibility change.

      StyledElement overrides this as final to check CSS visibility, call onShown(), and cascade to child elements.

    • hidden

      protected void hidden()
      Called when this element has been hidden due to a parent's visibility change.

      StyledElement overrides this as final to call onHidden() and cascade to child elements.

    • onShown

      protected void onShown()
      Hook method called when this element is shown.

      Override this method to respond to the element becoming visible.

    • onHidden

      protected void onHidden()
      Hook method called when this element is hidden.

      Override this method to respond to the element being hidden.

    • registerAddition

      protected void registerAddition()
      Registers this element for addition to the DOM.

    • registerSubtraction

      protected void registerSubtraction()
      Registers this element for removal from the DOM.

      Notifies the page that this element should be removed from the client-side DOM during the next update cycle.

    • registerUpdate

      public void registerUpdate()
      Registers this element for update in the DOM.

      Notifies the page that this element has been modified and should be synchronized with the client-side DOM during the next update cycle.