Extension talk:Treeview5.php

This talk page pertains specifically to the development of this extension. For more general discussion about bugs and usage etc, please refer to the mediawiki.org talk page at MW:Extension talk:Tree view

Treeview5.1 is a new approach to the core recursive bullet-list code which doesn't require any voodoo, and should be compatible with all MediaWiki versions including 1.12.

Parameters

• root: The content of the root node. Later this will also affect how sub-trees work
• id: A tree must be given an identifier if you want it's state to be persistent
• openlevels: not implemented in 5.x yet

Livelets

The new tree doesn't currently work when included via AJAX because the code in the response is not executed. The livelets code should be updated to execute script tags within responses.

How it works

The initial problem was how to write a parser-function which could generate a tree which could be composed of other transcluded tree's (i.e. parser-functions which are recursively executed forming a larger whole structure together). This seemed impossible since there are no MediaWiki properties available in the environment which reveal the current depth that the parser-function expansion is operating at.

But after thinking about the problem more closely, it turns out that the tree can be constructed without depth information by converting each tree row into a new format containing depth and tree id information which is protected from wiki-parsing. This information can then be converted into tree JavaScript after the parser has finished in the ParserAfterTidy hook.

Here is the wikitext of an example tree which includes two transcluded tree's

*[[toplevel]]
**bar
***baz
*foo
**[[Bar]]
***{{:Foo}}
**[[Baz]]
***{{:Bar}}

The expandTree method (the #tree parser-function hook) then converts all the matched rows into the following general structure:

1{uniq}-{id}-{depth}-{item}-2{uniq}

Where uniq is a unique string representing treeview's in general, id is a unique string representing the current tree, depth is the depth of the current row with respect to the current tree root, and item is the wikitext within the current row. Each row is converted to the new structured format by the private formatRow method. The information is "protected" from the parser merely by the fact that it contains no markup characters, but this could be made more robust later.

Notes about the format used

• If the same article is transcluded more than once it may not get processed again after the first time. This caching effect occurs at an internal level within the parser and is not affected by globals or parser properties. This means that information relating to specific items or sub-tree's could be repeated across transcluded instances of the same article within one or more trees in the page. This is not a problem in the case of the tree-id because only id's of root trees will be used in the final rendered tree.
• There a potential problem which hasn't been tested yet, with a sub-tree being transcluded twice in consecutive nodes. The tree id is also used to determine when a new tree is starting (by checking if id has changed), so the repeated id problem arising from multiple adjacent transclusion would prevent the loop from knowing about the transition from one of the similar sub-trees to the next.
• The actual pattern used in the current version is slightly different than the one shown here due to subsequent bug fixes. For example, the dashes used to separate the fields in the formatted rows have been changed to \x7F's. The examples shown are easier to read than the new ones, so they've been left as is. They still demonstrate the process used to render the tree in the current version.

After the resulting formatted-row structure has been fully parsed by the wiki parser, the content portions will have been converted into HTML and the information portions remain unchanged. Below is the HTML source of the above example after parsing and printed at the start of the renderTree method (the ParserAfterTidy hook).

1tv47cb2fd61165f-47cb2fd6dadf4-0-<a href="/wiki/index.php?title=Toplevl&action=edit" class="new" title="Toplevl">toplevl</a>-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6dadf4-1-bar-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6dadf4-2-baz-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6dadf4-0-foo-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6dadf4-1-<a href="/Bar" title="Bar">Bar</a>-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6dadf4-2-1tv47cb2fd61165f-47cb2fd6da03a-0-<a href="/Foo" title="Foo">Foo</a>-2tv47cb2fd61165f-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6da03a-1-bar-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6da03a-2-baz-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6da03a-0-foo-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6da03a-1-biz-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6da03a-2-1tv47cb2fd61165f-47cb2fd6d9c40-0-<a href="/Bar" title="Bar">bar</a>-2tv47cb2fd61165f-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6d9c40-1-baz2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6d9c40-2-biz2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6da03a-1-<a href="/wiki/index.php?title=Baz&action=edit" class="new" title="Baz">Baz</a>-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6dadf4-1-<a href="/wiki/index.php?title=Baz&action=edit" class="new" title="Baz">Baz</a>-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6dadf4-2-1tv47cb2fd61165f-47cb2fd6d9c40-0-<a href="/Bar" title="Bar">bar</a>-2tv47cb2fd61165f-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6d9c40-1-baz-2tv47cb2fd61165f
1tv47cb2fd61165f-47cb2fd6d9c40-2-biz2tv47cb2fd61165f

The following regular expression is used to create an array, $matches, each item of which contains a list of (,$id,$depth,,$icon,$item) extracted from the formatted rows in the page.

{{{1}}}

Following this extraction of row information into $matches is a loop that builds a new list called $rows which contains more detailed information than $matches, and adjusts the depth values to account for transcluded sub-tree's. The $rows array is a list of ($id,$depth,$icon,$item,$start). $id is the id of each root-tree (sub-tree's are not distinct from their root trees in the final rendered trees), $start is a boolean indicating whether or not the row is the first in a new root tree.

The main dTree JavaScript can then be constructed by looping through the $rows list and converting ordered depth-based information to the parent/child format required by dTree. The indexes of each row within the $rows array are used as id's for the individual dTree nodes.

Adjusting depth to account for sub-tree transclusion

The depth item in the $matches array is directly derived from the number of asterisks defined at the beginning of the row's wikitext. In the $rows array, the depth item has been adjusted to account for the depth of the tree at the point the sub-tree is transcluded, so that it can continue within-ward naturally. This adjustment is done by using the $depths array to associate each tree id with the current depth at each row where a new tree-id is encountered. The depths from $matches are added to the associated $depths values and stored in $rows.

Root tree's and sub-tree's

One of the difficulties with this extension has been in assessing from within a parser-function whether or not it's at the root level in terms of transclusion-depth. The new version doesn't require voodoo to determine this, it instead does the following pattern match on all the formatted rows in the page after wiki-parsing is complete (in the ParserAfterTidy hook).

{{{1}}}

This results in an array called $subs[1] which contains all the tree id's which are not transcluded. It does this by checking which rows have a preceding minus symbol, since top level ones will all be preceded by a p tag or a line start (see the example output of formatted rows above). An id is at root level if it is not in the $subs[1] array. This way is not as robust as it could be, and is also more computationally intensive than it could be.

Todo

• Need to get inline images working - for simplicity it would be nice to hook into the img directory that comes with dDree
• Implement (or remove) openlevels arg as treeview maintains persistence now
  • I think it should still have openlevels since that's a default like on sidebar should never start completely closed
• Allow rootless trees
• Get roots working properly for transcluded subtrees - looks like dtree must have at least one root node to work

See also

• dTree (javascript based)
• Slipstream wp-Dtree (php based)