Query Parameters
Query parameters allow you to pass additional data through URLs, using the format ?key1=value1&key2=value2
. While route parameters are used to pass required data within the URL path, query parameters provide a flexible mechanism for passing optional or additional data. They're especially useful when filtering content, sorting, or handling multiple values for the same key.
Query parameters overview
Query parameters in webforJ follow the typical URL convention: key-value pairs separated by =
and concatenated with &
. They're appended to the URL after a ?
and provide a flexible way to pass optional data, such as filtering or sorting preferences.
For example:
/products?category=electronics&sort=price
Retrieving query parameters
Query parameters are accessed through the ParametersBag
object. To retrieve query parameters, use the getQueryParameters()
method of the Location
object.
Here’s how you can retrieve query parameters from a URL in a view:
@Route(value = "products")
public class ProductView extends Composite<Div> implements DidEnterObserver {
@Override
public void onDidEnter(DidEnterEvent event, ParametersBag parameters) {
ParametersBag queryParameters = event.getLocation().getQueryParameters();
String category = queryParameters.get("category").orElse("all");
String sort = queryParameters.get("sort").orElse("default");
console().log("Category: " + category);
console().log("Sort: " + sort);
}
}
In this example:
- The
onDidEnter
method retrieves query parameters from theLocation
object provided by theDidEnterEvent
. - The
ParametersBag
allows you to retrieve specific query parameters usingget()
, which returns anOptional<String>
. You can specify a default value usingorElse()
if the parameter isn't present.
ParametersBag
gettersThe ParametersBag
provides several getter variations to help with casting the value of query parameters to specific types and filtering them. The following is the complete list of available getters:
get(String key)
: Retrieves the value of the parameter as aString
.getAlpha(String key)
: Returns only alphabetic characters from the parameter value.getAlnum(String key)
: Returns only alphanumeric characters from the parameter value.getDigits(String key)
: Returns only the numeric digits from the parameter value.getInt(String key)
: Parses and returns the parameter value as anInteger
.getFloat(String key)
: Parses and returns the parameter value as aFloat
.getDouble(String key)
: Parses and returns the parameter value as aDouble
.getBoolean(String key)
: Parses and returns the parameter value as aBoolean
.
These methods help you ensure the values are formatted and cast correctly, avoiding the need for manual parsing or validation.
Handling multiple values for a query parameter
Sometimes a query parameter might have multiple values for the same key, like in the following example:
/products?category=electronics,appliances&sort=price
The ParametersBag
provides a method to handle this by retrieving values as a list:
@Route(value = "products")
public class ProductView extends Composite<Div> implements DidEnterObserver {
@Override
public void onDidEnter(DidEnterEvent event, ParametersBag parameters) {
ParametersBag queryParameters = event.getLocation().getQueryParameters();
List<String> categories = queryParameters.getList("category").orElse(List.of("all"));
String sort = queryParameters.get("sort").orElse("default");
console().log("Categories: " + categories);
console().log("Sort: " + sort);
}
}
In this example:
getList("category")
retrieves all values associated with thecategory
key, returning them as a list.
By default, the getList()
method uses a comma (,
) as the delimiter. You can customize the delimiter by passing a different character or a regular expression as second parameter to the getList(String key, String regex)
method.
Use cases for query parameters
- Filtering content: Query parameters are often used to apply filters, like categories or search keywords.
- Sorting data: You can pass sorting preferences via query parameters, such as sorting by price, rating, or date.
- Handling optional parameters: When you need to pass data that isn't part of the required route structure, query parameters offer flexibility.
- Passing multiple values: Query parameters allow you to send multiple values for a single key, which is useful when users select multiple options, like product categories or filters.