Building on the TreeGrid improvements in v25, we are introducing the scrollToItem(T) API for TreeGrid. This feature gives TreeGrid users access to the same convenient scrolling capability that Grid already had, eliminating the need for manual index calculations when navigating to specific items. You can try it out with v25.0.0-beta2.
Why scrollToItem?
Previously, scrolling to a specific item in TreeGrid required using scrollToIndex(int...), which meant you had to manually resolve the index of each ancestor item.
Now, with scrollToItem, you can simply pass the item you want to scroll to, and TreeGrid handles the rest. Also, any collapsed ancestors of the target item are expanded before scrolling, unlike scrollToIndex.
// Before: Manual index calculation needed
treeGrid.scrollToIndex(2, 1, 3);
// Now: Just pass the item
treeGrid.scrollToItem(targetItem);
Implementation Requirements
The requirements for scrollToItem vary based on your data provider configuration. Here’s what you need to implement:
For TreeDataProvider
TreeDataProvider works out of the box with no additional implementation required:
TreeDataProvider<Person> dataProvider = new TreeDataProvider<>(treeData,
HierarchyFormat.FLATTENED); // Also works for HierarchyFormat.NESTED
treeGrid.setDataProvider(dataProvider);
Person targetPerson = findPersonById("john-doe");
treeGrid.scrollToItem(targetPerson);
For Custom In-memory HierarchicalDataProviders
For custom in-memory data providers, you need to implement getParent(T):
class CustomDataProvider implements HierarchicalDataProvider<Department, Void> {
@Override
public Department getParent(Department item) {
return departmentService.getParentDepartment(item);
}
@Override
public boolean isInMemory() {
return true;
}
// ...
}
For Other Custom HierarchicalDataProviders
You still need to implement getParent(T). Additionally, you need to implement getItemIndex(T, HierarchicalQuery):
class CustomDataProvider implements HierarchicalDataProvider<Department, Void> {
@Override
public Department getParent(Department item) {
return departmentService.getParentDepartment(item);
}
@Override
public boolean isInMemory() {
return false;
}
@Override
public int getItemIndex(Department item,
HierarchicalQuery<Department, Void> query) {
List<Department> siblings = departmentService
.getChildDepartments(query.getParent());
return siblings.indexOf(item);
}
// ...
}
Error Handling
Unlike scrollToIndex, scrollToItem will throw a NoSuchElementException if the target item does not belong to the tree.
try {
treeGrid.scrollToItem(item);
} catch (NoSuchElementException e) {
Notification.show("Item not found: " + e.getMessage());
}
Also, if your data provider doesn’t implement the required methods, it will throw an UnsupportedOperationException with a message indicating which method needs implementation.
Migration Guide
If you’re upgrading existing TreeGrid implementations:
- Currently using TreeDataProvider: No changes needed -
scrollToItemworks immediately - Currently using a custom HierarchicalDataProvider: Implement the required methods based on the table above
- Currently using scrollToIndex: Consider migrating to
scrollToItemfor cleaner code:
// Old approach
private void navigateToItem(T item) {
List<Integer> indexes = new ArrayList<>();
T current = item;
while (current != null) {
T parent = getParent(current);
int index = getChildIndex(parent, current);
indexes.add(0, index);
current = parent;
}
treeGrid.scrollToIndex(indexes.toArray(new Integer[0]));
}
// New approach
private void navigateToItem(T item) {
treeGrid.scrollToItem(item);
}
Combining with Flat Hierarchy Support
The scrollToItem feature works seamlessly with the new flat hierarchy support in v25. If you’re using HierarchyFormat.FLATTENED for better scrolling performance (as described in this post), scrollToItem will take advantage of the flattened structure.
Looking for Feedback
Give it a try and let us know what you think! We’re particularly interested in hearing about:
- Whether your use cases are well-suited to
scrollToItemand whether it improves your code - Performance with large datasets
- Any edge cases or unexpected behaviors