Help:Treeview skin:Treeview

Introduction and version

This is the help page for the treeview component of the Treeview skin. It explains persistence and what the option links (disabled since version 1.6.4 beta, and before that only visible if javascript and cookies are both enabled - they were disabled because they were distracting and user-unfriendly without serving a significant purpose: there was no need to ever change the default of "auto") in the treeview menu bar achieve.

It corresponds to version 1.6.7 beta, unchanged since 1.6.6 beta. If the version listed beside Hierarchy at Special:Version on your wiki does not match that then parts of this reference might be inapplicable.

Persistence schemes

The treeview allows for persistence of its expanded and collapsed state across page views. This is handled in different ways depending on the browser capabilities and/or selected option:

Non-javascript: links

If the browser does not support javascript, or if it is disabled, then persistence is only supported when clicking on links in the treeview (or navigation bar) itself - i.e. not for links within page content. Persistence is achieved here by appending a 'tvstate' parameter to each link's url. Expanding and collapsing nodes requires a full page download. This is the typical scenario for text-only browsers (amongst others) such as lynx. Menu-bar options are not displayed because there are none to choose between.

Known issues

Javascript without cookies: links and on-demand-load

If javascript is enabled in the browser but cookies are disabled, then persistence is handled as above except that expanding and collapsing nodes does not require a full page download unless the xml object used for on-demand-loads of treeview branches isn't supported by the browser. Menu-bar options are not displayed because there are none to choose between.

The form-submit issue described above does not apply here when xml load-on-demand is functioning properly.

Javascript and cookies: selectable, defaulting to "auto"

If both javascript and cookies are enabled in the browser, then the persistence scheme is optional, defaulting to "auto". This scheme could until version 1.6.4 beta be overidden by one of the options presented in the top bar, which had the following semantics:

Menu-bar option links
man.

Manually synchronise - i.e. as for "auto" except that the treeview isn't updated until (unless) this link is clicked. Click on this link to perform a synchronisation, as well as to set this option. Synchronisations are only possible immediately after a page has been loaded and prior to any nodes being expanded or collapsed or other option links being clicked; the cookie is reset to the visible treeview state (or in some cases deleted) subsequent to either of those occurences.

auto [''default'']

Automatically synchronise the treeview on page load. Each time a page is loaded, the treeview display state is synchronised to the state stored in the 'tvstate' cookie, using a single small xml load to update any missing nodes. The javascript then removes the 'tvstate' parameter from link urls so that each page is accessed through a single url only, making things easier on the browser cache.

links

Do not store state in a cookie: instead use the url 'tvstate' query appendage scheme described above in "Javascript without cookies: links and on-demand-load". Clicking on this option will delete the contents of the treeview state cookie; clicking on "man.", "auto" or "server" will reset the cookie to the visible treeview state.

server [only available if logged in]

(Not recommended due to the described caching glitch) As for the default "auto" except that the synchronisation of the displayed treeview state to the cookie is performed on the server instead of in the client browser. This works fine if you have turned off client-side (browser) caching either on the wiki or in your browser. If not, it's likely that you'll return to a page that was browser-cached after being generated against a different treeview cookie state and wonder why the state isn't what you expected. If this does happen, the state can be corrected by clicking on "man." immediately after page load (and then clicking "server" again if that option should remain selected).

off

Do not persist treeview state across page views - i.e. use neither a cookie nor a url tvstate parameter. Clicking on this option will delete the contents of the treeview state cookie; clicking on "manual", "auto" or "server" will reset the cookie to the visible treeview state; clicking on "links" will (re)insert the visible treeview state to treeview and navbar urls as a 'tvstate' query parameter.

When is a node expanded or collapsed?

All nodes are collapsed by default.

A node is automatically expanded against this default if:

When is a node persisted as expanded or collapsed?

A node is persisted as expanded if it has been manually expanded. In addition, the following logic applies:

If an auto-expanded node is subsequently collapsed, it will persist as collapsed, with one qualification: if it was originally expanded solely due to being an ancestor of the selected node(s), and if the page changes and the node is again an ancestor of the new selected node(s), the node will again be expanded.

A node that was auto-expanded due solely to being an ancestor of the selected node(s) will revert to its default collapsed state if the page changes and the node is no longer an ancestor of the selected node(s), with one qualification: if a descendant node(s) of any such auto-expanded node is manually expanded or collapsed, even if that descendant node(s) is subsequently manually reverted to its original state, the auto-expanded node will be persisted as expanded unless it is manually collapsed.

When is a node selected?

Selected nodes are those that match the current page, or that are configured as if they did. There might be multiple selected nodes because a page can appear in multiple places in the treeview and because multiple nodes might be configured as selected for any page view. All ancestors of a selected node are automatically expanded so that the selected node is visible. Selected nodes are by default styled in italics with a different background colour, and their ancestors are by default simply italicised.

A node will never be selected if was configured with selected(never).

Otherwise, a node is selected if it was configured with selected, or if it was configured with selected(<conditions>) and the <conditions> are met for the current page.

Otherwise (i.e. when it has no selected parameter [*]), a node is selected with respect to the current page if:

[*] "parameter" as used here refers to the whitespace-separated parameters of node definitions on the Treeview configuration page, as opposed to the &-separated query parameters of a url.

What about separate tabs and windows?

The treeviews in each separate tab/window will naturally maintain independent states when url links are being used instead of cookies - i.e. when javascript and/or cookies are disabled or not supported by the browser, or when the "links" option has been selected.

The results might be unpredictable when using cookies. This is because the state cookie is shared between all tabs/windows and because separate tabs and windows were not a design consideration.

Known issues