title | order | layout |
---|---|---|
Element Properties and Attributes |
1 |
page |
The Element API contains methods to update and query parts of an element.
You can use the Element API to change property and attribute values for server-side elements.
Note
|
By default, values updated in the browser are not sent to the server. See Retrieving User Input for how to transfer data to the server. |
Attributes are used mainly for the initial configuration of elements.
Attribute values are always stored as strings.
Example: Setting attributes for the nameField
element.
Element nameField = ElementFactory.createInput();
nameField.setAttribute("id", "nameField");
nameField.setAttribute("placeholder", "John Doe");
nameField.setAttribute("autofocus", "");
Example: The same example as above expressed as HTML.
<input id="nameField" placeholder="John Doe" autofocus>
You can also retrieve and manipulate attributes after they have been set.
Example: Retrieving and changing attributes in the nameField
element.
// "John Doe"
String placeholder = nameField
.getAttribute("placeholder");
// true
nameField.hasAttribute("autofocus");
nameField.removeAttribute("autofocus");
// ["id", "placeholder"]
nameField.getAttributeNames().toArray();
Properties are used mainly to dynamically change the settings of an element after it has been initialized.
Any JavaScript value can be used as a property value in the browser.
You can use different variations of the setProperty
method to set a property value as a String
, boolean
, double
or JsonValue
.
Example: Setting a property value as a double
.
Element element = ElementFactory.createInput();
element.setProperty("value", "42.2");
Similarly, you can use different variations of the getProperty
method to retrieve the value of a property as a String
, boolean
, double
or JsonValue
.
If you retrieve the value of a property as a different type to that as which it was set, JavaScript type coercion rules are used to convert the value. For example, a property set as a non-empty String
results as true
if fetched as a boolean
.
Example: Converting retrieved value types.
// true, since any non-empty string is
// true in JavaScript
boolean helloBoolean =
element.getProperty("value", true);
// 42, string is parsed to a JS number and
// truncated to an int
int helloInt = element.getProperty("value", 0);
Be cautious when using attributes and properties:
-
In many cases it is possible to use either an attribute or property with the same name for the same effect, and both work fine.
-
However, in certain cases:
-
Only one or the other works, or
-
The attribute is considered only when the element is initialized, and the property is effective after initialization.
-
You should always check the specific documentation for the element you’re using to find out whether a feature should be configured using a property or an attribute.
You can set an element’s textContent
property using the setText
method. This removes all children of the element and replaces them with a single text node with the given value.
The ElementFactory
interface provides helpers that you can use to create an element with a given text content.
Example: Using the createSpan
and createDiv
helper methods with the setText
method.
// <div>Hello world</div>
Element element = ElementFactory
.createDiv("Hello world");
// <div>Hello world<span></span></div>
element.appendChild(ElementFactory.createSpan());
// <div>Replacement text</div>
element.setText("Replacement text");
To retrieve the text of an element, you can use the:
-
getText
method to return the text in the element itself. Text in child elements is ignored. -
getTextRecursively
method to return the text of the entire element tree, by recursively concatenating the text from all child elements.
Example: Using the getText
and getTextRecursively
methods.
element.setText("Welcome back ");
Element name = ElementFactory
.createStrong("Rudolph Reindeer");
// <div>Welcome back <strong>Rudolph
// Reindeer</strong></div>
element.appendChild(name);
// will return "Welcome back Rudolph Reindeer"
element.getTextRecursively();
// will return "Welcome back "
element.getText();