Package com.vaadin.flow.dom

Class JsFunction

java.lang.Object
com.vaadin.flow.dom.JsFunction
All Implemented Interfaces:
Serializable
public final class JsFunction extends Object implements Serializable
A JavaScript function value with captured parameters that can be passed to Element.executeJs(String, Object...) as a parameter and reified on the client as an actual callable JS function.

The body is a JavaScript function body. Captures are referenced positionally as $0, $1, … (the same naming convention as executeJs parameters). Additional named runtime arguments can be declared with withArguments(String...): the materialised function then accepts them positionally and the body references them by name. On the client the value materialises as a function with the captures pre-bound, so the parent executeJs can invoke it as $N(arg1, arg2, ...) without ever concatenating user-supplied JavaScript with framework boilerplate.

Captures may be any value accepted as a parameter to executeJs, including Element (attached elements arrive as DOM nodes, detached ones as null) and nested JsFunction instances. Capture types are validated when the value is created.

Inside the body, this is whatever the caller of the materialised function chooses (i.e. it follows normal JavaScript call semantics – not the host element). To use the host element from within the body, pass it as a capture.

Author:
Vaadin Ltd
See Also:

  • Method Details

    • of

      public static JsFunction of(String body, @Nullable Object... captures)
      Creates a JavaScript function value with the given body and captured parameters.
      Parameters:
      body - the JavaScript function body, with captures referenced as $0, $1, …; not null
      captures - the values to capture; each must be a type supported as a parameter to Element.executeJs(String, Object...)
      Returns:
      a new JsFunction instance
      Throws:
      IllegalArgumentException - if any capture has a type that cannot be sent to the client

    • withArguments

      public JsFunction withArguments(String... argumentNames)
      Returns a copy of this function that declares the given names as positional runtime arguments. The materialised function accepts these arguments at call time, and the body references them by name.

      Example: 

       JsFunction alerter = JsFunction.of("alert(message);")
         .withArguments("message");
 element.executeJs("$0('Hello')", alerter);
      Parameters:
      argumentNames - the names of runtime arguments, in positional order; each must be a valid JavaScript identifier
      Returns:
      a new JsFunction with the given argument names
      Throws:
      IllegalStateException - if argument names have already been set on this instance

    • getBody

      public String getBody()
      The JavaScript function body.
      Returns:
      the body string

    • getCaptures

      public List<@Nullable Object> getCaptures()
      The captured values, in declaration order.
      Returns:
      an unmodifiable list of captures

    • getArgumentNames

      public List<String> getArgumentNames()
      The names of the runtime arguments declared via withArguments(String...), in positional order.
      Returns:
      an unmodifiable list of argument names; empty if none were declared