A way to navigate into a structure composed with some depth. For instance a system of files & folders. The instances of your structure can be of any type and don't have to match any interface. However, there is a quick setup step to make it work.
The only real setup phase consists of providing a DataRadar. You must so provide an object that implements the interface DataRadar. It mainly describes how to find parents and children from any data.
During initialization, the Explorer will create the root. It's not completely true but for now, consider the root as the first level in your tree structure and that is composed of all items that do not have a parent. You can (and should if possible) provide that list of items as param 'rootItems' of the constructor of Explorer. However, if you do not have that list, you can also provide a complete list of all items in the Explorer. In that case, that list will be filtered to find root items. Read the part about root for more information.
Exploration: Selection of an element managed by the Explorer. There are several ways to explore with an instance of Explorer. Each way will generate a new Report that we will describe later. It will also modify the current selection of the Explorer. You can have access to the current selection with the property 'path'.
Levels are just numbers to identify a depth. The root, for instance, is at level 0.
A Stage can be described as a set of items in the Explorer that are at the same Level, the same depth, and that have the same parent. There is never more than 1 Stage by Level. Stages are so often replaced by another.
You will use Level to explore but will never manipulate Stages directly that are private resources for the Explorer.
The root is a specific Stage. It's at Level 0 and will never be replaced. We saw earlier that the root was composed of items that do not have any parent. That is not always true. This is generally the expected pattern and in that case, you must pass to Explorer.constructor() the list of those items that do not have a parent or the list of all your items and the Explorer will filter them for you, looking for those items. However, you can also provide a list of arbitrary items as 'rootItems'. You do not have to provide the real root items. That's mainly useful if you want to create an Explorer for a limited part of your tree structure.
It's the more declarative way to select your data but also the less optimized one. That method will allow you to select any data (that is managed by the Explorer).
While it's the less optimized way to select in an Explorer, if you can use easily another of the provided ways to select the data, do it.
Edit the selection at a specific level of depth. Notice that it will clear selections that are deeper to the level affected.
Set the selection regarding the current selection. moveForward(1) will so select the next element while moveBackward(1) will select the previous one. The pattern of those methods will be affected by the value of the property 'looping' :
Explorers allow 'looping'. That feature will define what happens when we use moveForward or moveBackward and reach an extremity (the absolute last or first item). When looping is set to true, the next element that will be selected will be the one at the opposite extremity. When it's set to false, the selection will stop at the extremity.
When you select an item in your Explorer if that Item has some children, a Stage under it will be created. This is what CascadingSelection means. That feature can be removed or limited by setting the property 'cascadingDepthLimit'. You can also define with the property selectionMode what will happen to new Stages generated by the CascadingSelection pattern :
By default, the Explorer doesn't have a 'cascadingDepthLimit' (the value is Infinity). So when the CascadingSelection pattern occurs, the final selections can be deep. You can limit that by defining a 'cascadingDepthLimit'. If set, new Stages will be generated only if the Level of the new Stage to create is lower than the limitation.
Notice that this limitation is only to limit CascadingSelection. If that limit is at 2 and you use the method setLevelSelectedData with the parameter 'level' at 3, a third Stage will be created! So the depth of your Explorer will be 3. However, while 3 is higher than 2, calling that method will not generate any additional Stage from the CascadingSelection pattern.
By default, the exploration uses the mode "EXTREMITY". That means that every Stages of the Explorer has an item selected. Most of the time, the default item selected is the first one, but it also can be the last one if the last exploration action done was a moveBackward. In that case, we expect Stages created by CascadingSelection to have as default selection the last item.
You can prevent that "default selection pattern" by setting selectionMode to "NONE". In that case, Stages will not have any selection until one is defined.
Any exploration generates a Report. You can subscribe to new Reports with the property 'selection$' that provides a rxjs.BehaviorSubject. A report informs about which Levels have been changed, added and removed.
A Level is considered as changed if its selection has been changed.
A Level is considered as added if the Stage at this Level has been created during the exploration. Notice that if there was another Stage at this Level before the Exploration, the Report will still consider that the Level has been added: During the Exploration, it has been removed and added and so it will be listed in 'addedLevels'.
A Level is considered 'removed' if the Stage at this Level has been removed during the exploration. Notice that if another Stage has been added at that same Level during the Exploration, the Report will still consider that the Level has been removed: During the Exploration, it has been removed and added and so it will be listed in 'removedLevels'.
When one of the extremities is reached (the first element or the last one), the next moves required in that direction will be skipped.