---json
{
    "description": "With the page-explorer component, you can add an explorer like panel that will list your pages in a list or collapsible tree fashion",
    "name": "Page explorer",
    "page_id": "6zpgpwnhbfqk69sjlio95",
    "title": "Page-explorer: adding page navigation easily to your website"
}
---

====== ComboStrap UI - Page Explorer  ======



===== About =====
A ''page-explorer'' is a [[docs:navigation:navigation|navigational component]] that creates a navigation bar in the form of:
  * a ''list'' 
  * or a collapsible ''tree'' (ie clickable levels of folder hierarchy)


This component is mostly used in a [[docs:theme:slot:side_slot|side slot]].

===== Example =====

==== Default List ====

A default ''page-explorer list'' pane can be asked with this minimal markup (the [[docs:styling:dimension|width]] options is cosmetic and can be deleted)

By default, the list will show the pages of the [[:docs:page:system:namespace|namespace]] from the requested page.

<webcode name="DefaultList" >
<code dw>
<page-explorer width="300px"></page-explorer>
</code>
and will look like this where the label for each page is the [[docs:page:name|page name]]
</webcode>




==== Default Tree ====

A ''page-explorer tree'' does not need any template definition. 


<webcode name="DefaultTree" >
  * with a minimal markup (The ''ns'' option is cosmetic and can be deleted, it permits to show two [[:docs:page:level|levels]])
<code dw>
<page-explorer tree ns=":docs:layout"></page-explorer>
</code>
  * a page-explorer tree will look like this:
</webcode>


==== Custom List ====

<webcode name="Default" frameborder=0 >
<code dw>
<page-explorer color="blue" height="250px" width="400" scroll="toggle">
    <parent>[[$path|<icon name="arrow-left-box"/> ... ${h1 | cut("-","2-") | trim()} ]]</parent>
    <page>[[$path|<icon name="file"/> ${h1 | cut("-","2-") | trim()} ]]</page>
</page-explorer>
</code>
where the ''page'' template is composed of:
  * an [[docs:content:icon|icon]]
  * a [[docs:content:link|link]] without [[docs:styling:underline|underline]]
  * and a [[docs:templating:pipeline|pipeline]] to modify the [[docs:page:h1|heading 1]] of the page.
</webcode>

==== Custom Collapsible Tree ====


Example:

<webcode name="Default">
<code dw>
<page-explorer tree ns=":docs:layout">
    <index>[[$path|<icon name="home" color="#0000004d" width="20"/> Overview]]</index>
    <ns>${h1 | cut("-","2-") | trim()}</ns>
    <page>[[$path|<icon name="file" color="#0000004d" width="20"/>  ${h1 | cut("-","2-") | trim()}]]</page>
</page-explorer>
</code>
where the ''page'' template is composed of:
  * an [[docs:content:icon|icon]]
  * a [[docs:content:link|link]]
  * and a [[docs:templating:pipeline|pipeline]] to modify the [[docs:page:h1|heading 1]] of the page.

It produces:
</webcode>


===== Syntax and Templates =====

==== Syntax ====

<code dw>
<page-explorer type ns="namespacePath">
  <page>template</page>
  <namespace>template</namespace>
  <index>template</index>
  <parent>template</parent>
</page-explorer>
</code>
where:
  * The sub-elements define [[#template|templates]] for:
      * ''page'' - a page,
      * ''namespace'' - for a [[:docs:page:system:namespace|namespace]], 
      * ''index'' for a [[:docs:page:system:index|index page]]
      * ''parent'' - for the parent [[:docs:page:system:namespace|namespace]]
  * The page-explorer attributes are:

^ Attribute ^ Default ^ Possible Values ^ Description ^
| [[docs:styling:type|type]] | [[#list|list]] | [[#list|list]] or [[#tree|tree]] | It defines the layout |
| ''ns'' | the rendered page for a [[#list]] \\ the physical page for a [[#tree]] | | It defines the [[:docs:page:system:namespace|namespace]] that should be rendered |


<note>
''page-explorer'', ''index'', ''page'', ''parent'' and ''namespace'' are all [[docs:marki|superset HTML component]].
</note>

==== Templates ====

The templates define the output of each node in the ''list'' or ''tree'' layout:
    * ''page'' defines a  for each page in the namespace
    * ''index'' defines a fragment for the [[:docs:page:system:index|index page of the namespace]]
    * ''namespace'' defines a fragment for each child namespace of the actual namespace 
    *  ''parent'' defines a fragment for the [[:docs:page:system:index|index page]] of the parent namespace of the actual namespace (used only in the [[#list|list layout]])
  

The below image shows you the mapping between the tag and their location in a ''list''  layout.

{{docs:block:page-explorer-list-name-to-ui-region.png|}}

The below image shows you the mapping between the tag and their location in a ''tree'' layout.

{{docs:block:page-explorer-tree-name-to-ui-region.png|}}

<note>
If a sub-element (''index'', ''parent'', ''namespace'') is defined without any template (ie empty content), they are not shown.
</note>

==== Default template ====

  * if the ''page'' tag is is not defined, the below default ''page'' template is used 
<code html>
[[$path|$name]]
</code>
  * if the ''namespace'' tag is not defined, a default namespace template is used
<code html>
<!-- For a list -->
[[$path|<icon name="mdi:folder"/> $name]]
<!-- For a tree -->
$name</pipeline>
</code>
  * if the ''parent'' tag is not defined, a default parent template is used
<code html>
[[$path|<icon name="icons8:level-up"/> $name]]
</code>
  * if the ''home'' tag is is not defined, the ''page'' template is used  


===== Support =====

==== Performance consideration with the tree pane ====
The [[#tree|page-explorer tree]] is recreated when:
  * a primary metadata (title, name, description) is modified ([[docs:cache:slot|primary meta dependency]])
  * a page is added or deleted  ([[docs:cache:slot|page system dependency]])

If your tree has a lot of pages, it may seems slow:
  * while editing
  * or for the first viewer