Fix: AtoM Sidebar Tree Infinite Scroll Bug

by Alex Johnson 43 views

Are you experiencing the frustrating issue of the AtoM sidebar tree repeating sibling records, leading to infinite scrolling? This article delves into the root cause of this problem, offering a comprehensive explanation and a potential solution. This bug, which primarily affects AtoM versions 2.9.1 and 2.9.2, can significantly hinder user experience, making navigation and content discovery a real headache. We'll explore the technical aspects, pinpoint the problematic code sections, and discuss a fix that can restore the sidebar tree to its intended functionality.

Understanding the Sidebar Tree Issue in AtoM

The AtoM (Access to Memory) platform is a powerful tool for archival description and access. Its sidebar tree is a crucial component, providing a hierarchical view of records for easy navigation. However, a bug in versions 2.9.1 and 2.9.2 can cause the sidebar tree to repeat the same sibling records, leading to a frustrating infinite scrolling experience. This issue manifests when expanding hierarchy branches containing more than eight records. The initial view displays the first eight records, followed by a '{X} more...' link. Clicking this link or scrolling down triggers a call to the AtoM URL, specifically targeting the treeView endpoint. The problem arises when this endpoint returns a set of records that includes duplicates, causing the cycle to repeat endlessly.

To illustrate, consider a scenario where the API call returns seven records: the first four siblings, followed by a repetition of the first three. This pattern continues with subsequent requests, effectively trapping the user in an infinite loop. This behavior is exclusive to the sidebar tree; the full-width tree and list views display records correctly, highlighting the localized nature of the bug. Understanding the specific steps to reproduce this behavior and the affected components is crucial for implementing an effective solution.

Current Behavior: Steps to Reproduce

The repetition bug isn't consistently triggered, making it somewhat elusive. However, it commonly appears when expanding hierarchical branches containing more than eight records in the sidebar tree. Here's a breakdown of the steps to reproduce the behavior:

  1. Navigate to a collection or series within your AtoM instance that contains more than eight sibling records.
  2. Expand the hierarchical branch in the sidebar tree.
  3. The first eight records will be displayed, followed by a '{X} more...' link.
  4. Click the '{X} more...' link or scroll downwards within the tree.
  5. This action triggers a call to the AtoM URL endpoint: _{atom url}/{slug}/informationobject/treeView?show=nextSiblings&resourceId={id}_.
  6. The API call may return a set of records containing duplicates, typically including the first few siblings from the set.
  7. Subsequent requests to fetch 'nextSiblings' will continue to return the same repeating set of records, leading to infinite scrolling.

For example, a broken _nextSiblings_ request might return the following set:

  • Item K/PP149/2/2/10 - Papers, 1959-1966
  • Item K/PP149/2/2/11 - Transcripts, 1960-1963
  • Item K/PP149/2/2/12 - Transcripts of interviews, 1960-1963, with patients with surnames A-C
  • Item K/PP149/2/2/13 - Transcripts of interviews, 1960-1963, with patients with surnames D-F
  • Item K/PP149/2/2/10 - Papers, 1959-1966 (repeated)
  • Item K/PP149/2/2/11 - Transcripts, 1960-1963 (repeated)
  • Item K/PP149/2/2/12 - Transcripts of interviews, 1960-1963, with patients with surnames A-C (repeated)

This repetition effectively breaks the pagination and creates the infinite scrolling loop.

Expected Behavior: Seamless Pagination

The expected behavior of the sidebar tree is to return the next 'N' sibling records without any repetition. When a user clicks the '{X} more...' link or scrolls down, the system should fetch the subsequent set of records and append them to the existing list. Each request to _{atom url}/{slug}/informationobject/treeView?show=nextSiblings&resourceId={id}_ should seamlessly retrieve the next batch of siblings, ensuring a smooth and intuitive browsing experience. The sidebar tree should accurately reflect the hierarchical structure of the archival material, allowing users to navigate through records without encountering duplicate entries or infinite loops.

Root Cause Analysis: Diving into the Code

To understand why this repetition occurs, we need to examine the code responsible for fetching and displaying the sibling records. The investigation points to a specific helper method within the AtoM codebase: QubitInformationObject::getTreeViewChildren(). This method, located at https://github.com/artefactual/atom/blob/f7f5a638e5cd7b040de4f3e0da8fa47ccb117553/lib/model/QubitInformationObject.php#L2309, appears to be the source of the problem.

Specifically, the issue lies in the fact that this method doesn't account for any offset or 'start' parameters when fetching siblings. The caller, found at https://github.com/artefactual/atom/blob/f7f5a638e5cd7b040de4f3e0da8fa47ccb117553/apps/qubit/modules/informationobject/actions/treeViewComponent.class.php#L20, simply passes the current resource ID to getTreeViewChildren(). This triggers a fresh query that always retrieves the very first child of that resource. Subsequently, it fetches the 'next' siblings from that starting point. Since there's no mechanism to track the current position in the list or specify an offset, each fetch essentially begins from the same initial child.

This lack of offset or 'current child' parameter is the core reason why pagination fails. The system continuously anchors to the first record, causing the 'next N' list to repeatedly include the earliest rows. This behavior effectively breaks the intended pagination logic, leading to the observed repetition and infinite scrolling.

Proposed Solution: Implementing Pagination Offset

The solution to this repetition problem lies in modifying the QubitInformationObject::getTreeViewChildren() method to incorporate pagination offset. This involves introducing a mechanism to track the current position in the list of siblings and fetch the next set of records based on that offset. Here's a conceptual outline of the proposed solution:

  1. Introduce Offset Parameter: Modify the getTreeViewChildren() method to accept an optional offset parameter. This parameter will indicate the starting point for fetching the next set of siblings.
  2. Update Query: Adjust the database query within getTreeViewChildren() to use the offset parameter to limit the result set and retrieve only the records starting from the specified offset.
  3. Pass Current Child: In the calling function (treeViewComponent.class.php), determine the ID of the last displayed record (the 'current child') and pass it as the offset parameter to getTreeViewChildren() when fetching the next set of siblings.
  4. Store Current Position: Implement a mechanism to store the current position in the list of siblings, possibly using session variables or a similar approach. This will ensure that the correct offset is used for subsequent requests.

By implementing these changes, the getTreeViewChildren() method will be able to fetch the correct set of sibling records for each pagination request. The offset parameter will ensure that the query starts from the appropriate position in the list, preventing the repetition of records and resolving the infinite scrolling issue.

This solution ensures that each request for 'nextSiblings' retrieves a unique set of records, providing a smooth and accurate browsing experience for users navigating the AtoM sidebar tree. Addressing this bug is crucial for maintaining the usability and effectiveness of the AtoM platform as a tool for archival description and access.

Conclusion

The infinite scrolling bug in the AtoM sidebar tree, caused by repeated sibling records, is a significant usability issue in versions 2.9.1 and 2.9.2. By understanding the steps to reproduce the issue, analyzing the code, and implementing a solution involving pagination offset, we can restore the intended functionality of the sidebar tree. This fix ensures a smooth and efficient navigation experience for users, allowing them to effectively explore and access archival materials within the AtoM platform.

For more information on AtoM and its features, please visit the Artefactual Systems website.