@myrmidon/paged-data-browsers NPM

Paged Data Browsers

This library provides simple components to display filtered and paged data from some service.

There are currently two components, one for displaying a flat list of data, and another to display hierarchically structured data, combining a tree view with paging.

Also, there is a LRU cache service and a compact pager used in the paged tree component.

Paged List

Paged list support is provided by a single utility class, PagedListStore. This templated class provides logic for:

a filter object of type F;
a list element object of type E.

So you need:

a filter class to represent your elements filter (for F).
an element item class (for E).
a service to fetch data, implementing interface PagedListStoreService<F, E>. In this shell, a local service provides mock data.

Paged Tree

Nodes

A paged tree is based on nodes of type TreeNode or its derived types. This basic tree node contains:

id: a unique numeric ID.
parentId: the ID of the parent, or undefined if it's a root-level node.
y: Y is the node depth, starting from 1. As we often need a single root node (for paging its children), unless we have a small number of root nodes, when your data source does not return a single root node you have the option of using a mock root. In this case, the mock root Y level will be 0 and all the other nodes will descend from it. Anyway you can also have many root level nodes, whose parent ID is undefined; but in this case all these nodes will appear at once without any paging, because paging is governed by the parent node.
x: X is the ordinal number of the node among its siblings. The first child of a given node has X=1, the second has X=2, and so forth.
label: a human-friendly label for the node.
tag: a tag string for virtually categorizing or grouping the node in some way.
hasChildren: true if the node has children, false if it has no children; undefined if this has not yet been determined.

A paged tree node type derives from TreeNode adding two essential components:

a filter for its children. The basic TreeNodeFilter just refers to TreeNode properties, so it just has tag and parent ID. You can derive your own filter from this type.
paging information for its children. This is of type PagingInfo which has page number, page items count, and total items count.

The base type for a paged tree node is thus PagedTreeNode<F>, where F is the type of the filter used for filtering nodes; this adds:

paging: paging information. This is required.
expanded: for expanded/collapsed state.
filter: filter object.

Services

Your data must be provided by a service implementing interface PagedTreeStoreService<F>, where F is the tree node filter type. This requires you to implement a single function, getNodes, which returns a specific page of nodes, applying the specified filter.

This service deals with TreeNode's (or their derivations), returning a specific page of them. It is the store which extends these nodes with paging and filtering data using the PagedTreeNode type. Note that if you want a single root mock node, your implementation of this service must provide it (with Y=0).

The tree logic is then implemented by the PagedTreeStore<E,F>, where E is the element (node) type (a PagedTreeNode<F> or any derived type), and F is the filter type (a TreeNodeFilter or any derived type).

The store is used to load and manage a flat list of nodes. Every tree node in the list is extended with page number, page count and total items, plus expansion-related metadata. Users can expand and collapse nodes, browse through pages of children, and filter them.

The essential store data are:

the flat list of paged nodes (exposed in nodes$). This is populated by using an instance of PagedTreeStoreService<F>, injected in the store constructor together with its options (of type PagedTreeStoreOptions). Among other things, the options specify whether there must be a single mock root node, and the default page size. Once retrieved, pages can be fetched from an internal LRU cache (which is anyway cleared when calling reset).
a list of tree tags (exposed in tags$).
a global filter (exposed in filter$). This gets combined with (overridden by) node-specific filters, when specified. You can set it with setFilter. To set the filter for the children of a specific node use setNodeFilter.
the page size (pageSize), a get/set property, initially set by the options injected in the store constructor. Setting this property resets the store (like calling reset).

To initialize the store, you call reset, which loads root nodes (via its service's getRootNodes) and their direct children. You then expand or collapse nodes, change page, and set the global or node filters as desired.

The main methods are:

reset(): reset the store, loading root node(s) and peeking at their direct children to determine whether they can be expanded.
clear(): clear the whole store, emptying the cache and removing all the nodes.
clearCache(): clears the pages cache.
hasCachedPage(pageNumber, filter): checks whether the specified page is cached.
isEmtpy(): true if the list is empty.
getNodes(): gets all the nodes in the list.
getRootNode(): returns the root node, i.e. the first node in the list (unless this is empty).
getChildren(id): gets the children of the specified node.
expand(id): expand the specified node (if it has children and is collapsed).
expandAll(id): expand all the descendants of the specified node.
collapse(id): collapse the specified node if expanded.
collapseAll(): collpase all the descendants of the specified node.
changePage(parentId, pageNumber): change the page of children nodes of the specified parent node.
setFilter(filter): sets the global filter, resetting the store.
setNodeFilter(id, filter): sets the node-filter for the specified node, resetting its children page number to 1.

The store is a plain class. If you want to persist it in the app, you can wrap it in a service and inject the service into your component. If you don't need this, just implement your data service to provide nodes via getNodes. Otherwise, you can wrap the store like e.g. here using a singleton for a single page of nodes in the demo app:

@Injectable({
  providedIn: 'root',
})
export class PagedTreeBrowserService {
  public store: PagedTreeStore<MockTreeNode, MockTreeFilter>;

  constructor() {
    this.store = new PagedTreeStore<MockTreeNode, MockTreeFilter>(
      new MockPagedTreeStoreService()
    );
  }

  /**
   * Set the mock root node for the paged list store. This is for testing
   * purposes; in a real world scenario, this parameter would hardly change
   * once set.
   * @param on Whether to enable the mock root node.
   */
  public setHasMockRoot(on: boolean): void {
    this.store = new PagedTreeStore<MockTreeNode, MockTreeFilter>(
      new MockPagedTreeStoreService(),
      {
        ...DEFAULT_PAGED_LIST_STORE_OPTIONS,
        hasMockRoot: on,
      } as PagedTreeStoreOptions
    );
  }
}

Node Component

The only piece of UI provided by this library is for displaying a single node of the tree. The component for visualizing each single node of the paged tree is BrowserTreeNodeComponent. This wraps some HTML content providing a toggle button to expand/collapse the node, a paging control for the node's children, and a button to edit the node's filter.

Unless you are satisfied with these essential data, you can then provide the HTML content to display more node's data inside this component, e.g.:

 <pdb-browser-tree-node [node]="node">
   <!-- add your data here... -->
   <your-node-view [node]="node" />
 <pdb-browser-tree-node>

This component API has:

▶️ node (PagedTreeNode) to display.
▶️ paging (PagingInfo): optional paging information about node's children.
▶️ debug (boolean) flag to toggle debug information in the view.
▶️ hideLabel (boolean) flag to hide the node's loc and label. This is useful if you want to provide your own view for the node, between the expansion toggle and the filter edit button. In this case, in your consumer template provide your own view as the content of this component. If instead you are fine with the default loc and label, and just want to add more data to the view, then you can just add your own content to this component's template, without setting this property to true.
▶️ hideLoc (boolean): true to hide the node's location (X and Y).
▶️ hideFilter (boolean): true to hide the node's filter edit button. Do this when you do not want to allow users to apply per-node filters.
▶️ hidePaging (boolean): true to hide the node's paging control unless hovered.
▶️ indentSize (number): the indent size for the node's children.
▶️ rangeWidth (number): the width of the range view. This is a small horizontal bar showing you the location of the page in the set of nodes.
🔥 toggleExpandedRequest (PagedTreeNode): emitted when the user wants to toggle the expanded state of the node.
🔥 changePageRequest (PageChangeRequest): emitted when the user wants to change the page number of the node's children.
🔥 editNodeFilterRequest (PagedTreeNode): emitted when the user wants to edit the node's filter for its children.

You should provide your components for:

the node's filters component. This is used both for global and node-specific filters (in the latter case as a popup).
the tree browser component. This combines:
- a filters component for global filters. This dummy component gets a filter$ and emits filterChange.
- a tree view.