Element Properties and Attributes

Warning
Values updated in the browser are by default not sent back to the server. See the Retrieving User Input tutorial to learn how to get data back to the server.

Attributes

Attributes are mainly used for initial configuration of an element. Attribute values are always stored as strings.

Java

  1. Element nameField = ElementFactory.createInput();
  2. nameField.setAttribute("id", "nameField");
  3. nameField.setAttribute("placeholder", "John Doe");
  4. nameField.setAttribute("autofocus", "");

The above example expressed as HTML would look like <input id="nameField" placeholder="John Doe" autofocus>.

You can also investigate and manipulate attributes that have already been set.

Java

  1. // "John Doe"
  2. String placeholder = nameField.getAttribute("placeholder");
  4. // true
  5. nameField.hasAttribute("autofocus");
  7. nameField.removeAttribute("autofocus");
  9. // ["id", "placeholder"]
  10. nameField.getAttributeNames().toArray();

Properties

Properties are mainly used for dynamically changing the settings of an element after it has been initialized. In the browser, any JavaScript value can be used as a property value. You can use different variations of the setProperty method for setting a property value as String, boolean, double and JsonValue.

Java

  1. Element element = ElementFactory.createInput();
  2. element.setProperty("value", "42.2");

Similarly, the value of a property can be fetched as any of those types using different getProperty method variations. The value will be converted according to JavaScript type coercion rules if it is fetched as some other type than how it was set. For instance, a property set as a non-empty string will result in true if fetched as a boolean.

Java

  1. // true, since any non-empty string is true in JavaScript
  2. boolean helloBoolean = element.getProperty("value", true);
  4. // 42, string is parsed to a JS number and truncated to an int
  5. int helloInt = element.getProperty("value", 0);
Warning
There are many cases where you can use either an attribute or a property with the same name for the same effect. In some cases only one of them works, in other cases the attribute is considered when the element is initialized, but after initialization only the property is effective. Please check documentation specific to the element you’re using to find out whether a feature should be configured using a property or an attribute.

Class / ClassList / ClassName

Class names for elements can be added, removed and inspected using the collection returned by the getClassList method. You cannot modify the classList or className properties directly using setProperty. Using element.getProperty("className") you can get all of the set classes as a concatenated string.

Java

  1. element.getClassList().add("error");
  2. element.getClassList().add("critical");
  3. element.getClassList().remove("primary");
  5. element.getProperty("className"); // will return "error critical".
Note
You can set the element’s class attribute using element.setAttribute(“class”, “foo bar”);. This will clear any previously set classList property. You can get the element’s class attribute using element.getAttribute(‘class’) which will return the contents of the classList property as a single concatenated string.

Style object

Element inline styles can be set using the Style object returned by element.getStyle(). Style property names could be in the camelCase format or in the kebab-case, e.g. backgroundColor or background-color.

Java

  1. element.getStyle().set("color", "red");
  2. //camelCase
  3. element.getStyle().set("fontWeight", "bold");
  4. //kebab-case
  5. element.getStyle().set("font-weight", "bold");
  7. //camelCase
  8. element.getStyle().remove("backgroundColor");
  9. //kebab-case
  10. element.getStyle().remove("background-color");
  12. element.getStyle().has("cursor");
Note
You cannot set the element’s style attribute using the element.setAttribute method. However you can use element.getAttribute(‘style’) to get all the style rules in a single concatenated string.

TextContent

The element’s textContent property can be set using the setText method. Note that this removes all children of the element and replaces them with a single text node with the given value.

Tip
ElementFactory provides helpers for creating elements with a given text content.

Java

  1. Element element = ElementFactory.createDiv("Hello world");  // <div>Hello world</div>
  3. element.appendChild(ElementFactory.createSpan()); // <div>Hello world<span></span></div>
  5. element.setText("Replacement text"); // <div>Replacement text</div>

You can fetch the text of an element using the getText or getTextRecursively methods.

  • getText returns the text inside the element itself, ignoring text inside child elements.

  • getTextRecursively returns the text of the entire element tree by recursively concatenating the text from all child elements.

Java

  1. element.setText("Welcome back ");
  3. Element name = ElementFactory.createStrong("Rudolph Reindeer");
  4. element.appendChild(name); // <div>Welcome back <strong>Rudolph Reindeer</strong></div>
  6. element.getTextRecursively(); // will return "Welcome back Rudolph Reindeer"
  7. element.getText(); // will return "Welcome back "