- 1 Introduction and version
- 2 Persistence schemes
- 3 When is a node expanded or collapsed?
- 4 When is a node selected?
- 5 What about separate tabs and windows?
- 6 Known issues
Introduction and version
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.
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:
- 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.
The form-submit issue described above does not apply here when xml load-on-demand is functioning properly.
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.
- 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.
- 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.
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
expandedparameter (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
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
urlextraparameter [*] (the
urlextraparameter 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
urlextraparameter 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
- the effective action is "view" and the node was not defined with the
[*] "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 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.
- 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 18.104.22.168):
- occasionally the bottom border becomes invisible
- occasionally a white gap appears between the ? and the border in the top menu bar