Skip to main content

Elements

Open in ChatGPT
Java API

webforJ developers have the option of choosing not only from the rich library of components provided, but also integrating components from elsewhere. To facilitate this, the Element component can be used to simplify the integration of anything from simple HTML elements, to more complex custom web components.

important

The Element component can't be extended, and isn't the base component for all components within webforJ. To read more about webforJ's component hierarchy, read this article.

Show Code

Adding events​

In order to utilize events that may come with your element, you can use the Element component's addEventListener methods. Adding an event requires at least the type/name of the event the component expects, and a listener to be added to the event.

There are also additional options to further customize events by using the Event Options configurations.

Show Code

Component interaction​

The Element component acts like a container for other components. It provides a way to organize and retrieve information for child components, and offers a clear set of functions to add or remove these child components as needed.

Adding child components​

The Element component supports the composition of child components. Developers can organize and manage complex UI structures by adding components as children to the Element. Three methods exist to set content within an Element:

  1. add(Component... components): This method allows one or multiple components to be added to an optional String which designates a specified slot when used with a Web Component. Omitting the slot will add the component between the HTML tags.

  2. setHtml(String html): This method takes the String passed to the method and injects it as HTML within the component. Depending on the Element, this may be rendered in different ways.

  3. setText(String text): This method behaves similarly to the setHtml() method, but injects literal text into the Element.

Show Code

Replacing content

Calling setHtml() or setText() will replace content currently contained between the element's opening and closing tags.

Removing components​

In addition to adding components to an Element, the following methods are implemented for removal of various child components:

  1. remove(Component... components): This method takes one or more components and removes them as child components.

  2. removeAll(): This method removes all child components from the Element.

Accessing components​

To access the various child components present within an Element, or information regarding these components, the following methods are available:

  1. getComponents(): This method returns a Java List of all children of the Element.

  2. getComponents(String id): This method is similar to the method above, but takes the server-side ID of a specific component and returns it when found.

  3. getComponentCount(): Returns the number of child components present within the Element.

Calling JavaScript functions​

The Element component provides two API methods which allow for JavaScript functions to be called on HTML elements.

  1. callJsFunction(String functionName, Object... arguments): This method takes a function name as a string, and optionally takes one or more Objects as parameters for the function. This method is executed synchronously, meaning that the executing thread is blocked until the JS method returns, and results in a round trip. The results of the function are returned as an Object, which can be cast and used in Java.

  2. callJsFunctionAsync(String functionName, Object... arguments): As with the previous method, a function name and optional arguments for the function can be passed. This method executes asynchronously and doesn't block the executing thread. It returns a PendingResult, which allows for further interaction with the function and its payload.

Passing parameters​

Arguments that are passed to these methods which are used in the execution of JS functions are serialized as a JSON array. There are two notable argument types that are handled as follows:

  • this: Using the this keyword will give the method a reference to the client-side version of the invoking component.
  • Component: Any Java component instances passed into one of the JsFunction methods will be replaced with the client-side version of the component.
Waiting for component arguments

Both synchronous and asynchronous function calling will wait until the Element has been added to the DOM before executing a function, but callJsFunction() won't wait for any component arguments to attach, which can result in failure. Conversely, invoking callJsFunctionAsync() may never complete if a component argument is never attached.

In the demo below, selecting Focus search calls the native focus() method on the search input with callJsFunctionAsync(). The resulting PendingResult is used to confirm the call with a toast once the asynchronous function completes.

Show Code

Executing JavaScript​

Beyond calling named functions, an Element can run raw scripts scoped to that element with executeJs, executeJsAsync, and executeJsVoidAsync. See Execute JavaScript for these methods, their synchronous and asynchronous behavior, and how returned values convert to Java types.