Introduction and version

This is the help page for the treeview component of the Treeview skin. It explains persistence and what the option links (only visible if javascript and cookies are both enabled) in the treeview menu bar achieve.

It corresponds to version 1.5.beta of the combined Hierarchy extension/Treeview skin package. If the version listed beside Hierarchy at Special:Version is different then parts of this reference might be outdated.

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

• pages reached as the direct outcome of submitting a form will not be redisplayed when expanding or collapsing nodes under this scheme, since it would be incorrect to resubmit the form. The actual view will depend on the behaviour of the form - likely possibilities are a fresh input screen or a brief warning message.

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 can be overidden by one of the options presented in the top bar, which have 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.

• pros: Handy to use temporarily when revisiting pages in the browser history, especially when an internet connection is (perhaps temporarily) not available - it avoids the xml downloads as well as any possible error messages due to lack of internet connection. Easy on the browser cache for full pages - avoids redownloading content under different urls. Persistence is supported for all links - i.e. including those in page content.
• cons: Requires a single manual click to perform the synchronisation; the old state is lost if this click is not performed soon enough.

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.

• pros: No "synchronise" clicks required - it's all automated. Easy on the browser cache for full pages - avoids redownloading content under different urls. Persistence is supported for all links - i.e. including those in page content.
• cons: Requires an xml download on each revisit to a page if nodes are expanded, including when revisiting the page in the browser history.

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.

• pros: No "synchronise" clicks required - it's all automated. No 'tvstate' cookie required.
• cons: Unfriendly on the browser cache (and bandwidth) for full pages - content must be redownloaded for each different 'tvstate' url that the page is accessed under. State doesn't persist when page content links are clicked (and in other special cases such as the "Random page" node).

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).

• pros: No "synchronise" clicks required - it's all automated. Easy on the browser cache for full pages - avoids redownloading content under different urls. Avoids any initial synchronising xml downloads. Persistence is supported for all links - i.e. including those in page content.
• cons: The possibility of viewing an old state due to client-side caching.

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.

• pros: Avoids use of the 'tvstate' cookie. Easy on the browser cache for full pages - avoids redownloading content under different urls.
• cons: No persistence of state (this might be a "pro" for some people).

When is a node expanded or collapsed?

All nodes are collapsed by default.

A node is automatically expanded against this default if:

• the node is defined on the config page with the optional expanded parameter (the config page's location defaults to MediaWiki:Treeview; although this location can be overridden through a configuration variable) and the node has not been persisted as manually collapsed; OR
• the node is an ancestor of the selected node(s) - see "When is a node selected?" below or save yourself the reading and comprehension by assuming a common-sense definition; OR
• the node has been persisted as manually expanded as described next.

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:

• the node's id matches the value of the 'nodeid' query parameter (if any) in the url of the current page; OR
• there is no 'nodeid' url query parameter but the node's article title matches the title of the viewed article; AND
  • the effective action is "view" and the node was not defined with the urlextra parameter [*] (the urlextra parameter allows a node to be associated with a specific action such as "edit" or with extra url query parameters along the base article title); OR
  • the node's urlextra parameter matches the additional query parameters of the viewed page's url (and the url has no other additional parameters - "title" and "tvstate" aren't considered to be "additional"), including when it has been "prettified" using MediaWiki's $wgActionPaths array.

[*] "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

• The view of submitted forms is not maintained when the full-page reload scheme is in effect, as described above.
• There are several visual glitches under some versions of the Mozilla Firefox browser (these seem to have been solved by Firefox version 1.5.0.4):
  • occasionally the bottom border becomes invisible
  • occasionally a white gap appears between the ? and the border in the top menu bar