This README describes the features of, installation of, and issues associated with the Treeview skin for MediaWiki. The CHANGELOG file in the Hierarchy extension's directory describes externally visible changes relevant to upgraders. == Disclaimers == The Treeview skin is released as a beta. There might be minor bugs in it although it should be fairly stable. See also the "Limitations" and "Performance and scalability" sections. == Brief description == The Treeview skin supports arbitrary-depth "contexts" in wiki article titles using colons as separators in the same way that slashes are used as a directory separator in many filesystems. It adds: * a treeview of those contexts as a hierarchy expandable/collapsable through javascript load-on-demand falling back to full-page reload; customisable through the MediaWiki:Treeview article. Category hierarchies can also be loaded into the treeview. * the ability to specify remappings for displayed title names in the MediaWiki:Treeview config page to deal with MediaWiki's underscore conversion where it's unwanted e.g. for articles describing standardised programming variables that have underscores in their name. * a navigation bar based on the hierarchy for easier browsing. * a few controls to assist with diagnosing caching and parsing problems, visible at Special:Hierarchy. Further description of the skin's features is in the help files in Treeview/help_articles, and the file describing its client-side javascript functionality, Treeview/README.treeview_javascript. == Compatibility, requirements and recommendations == * MediaWiki 1.18.* or later. Untested on 1.17.* but might work. * A cache manager for best results (see "Performance and scalability" below). If a cache manager is enabled then per-user translations of treeview strings are disabled (see "Limitations" below). * The Hierarchy extension - packaged with this skin but installed in a separate directory as described in the next section. The skin is heavily and deliberately, for compatibility, based on MonoBook. == Installation == * Copy the 'MonoBook' directory (as already existing in your MediaWiki's 'skins' directory) to a directory titled 'Treeview', and then copy the files from this archive's 'Treeview' directory into that directory, overwriting files as necessary. * Install/upgrade the Hierarchy extension by copying the contents of this archive's 'extensions/Hierarchy' directory subtree to 'extensions/Hierarchy' in the MediaWiki root. * To LocalSettings.php, add the following lines, edited to your requirements, taking note of the comments, and being careful that $wgGroupPermissions is not being overwritten later in the file by a pre-existing full-array assignment (these variables are described under "Variables and settings"): require_once "$IP/extensions/Hierarchy/SpecialHierarchy.php"; require_once "$IP/skins/Treeview/Treeview.php"; # Customise these permissions as required; they are described beside the # $wgGroupPermissions entry under "Variables and settings" in README.Treeview. $wgGroupPermissions['sysop']['rebuildtreeview' ] = true; $wgGroupPermissions['sysop']['parsetreeview' ] = true; $wgGroupPermissions['sysop']['treeviewcachestatus'] = true; # Optionally set Treeview as the default skin ($wgDefaultSkin is probably # already set elsewhere in the file). $wgDefaultSkin = 'treeview'; # Not required if $wgCachePages and $wgUseFileCache are both false. # path/to/file is a file that the web-server has read/write permission on. $wgCacheEpochTouchFile = "/path/to/file"; # Uncomment this if $wgUseDatabaseMessages is false but an editable # configuration at the default configuration message page is required. The # default configuration is the 'Treeview' message for the $wgLanguageCode # language code in the file extensions/Hierarchy/Hierarchy.i18n.php #$wgHierarchyPage = 'MediaWiki:Treeview'; # Database additions are required prior to (optionally) uncommenting this, as # described in its entry under "Variables and settings" in README.Treeview. #$wgStoreTreeviewNodeIdsInDB = true * Optionally, review the "Variables and settings" section to see if anything applies. * Optionally, to have the custom node icons that this configuration references displayed, upload the images in the Treeview/icons_for_upload directory to the wiki using Special:Upload or a batch upload tool (see the README in that directory). * Optionally, edit the new MediaWiki:Treeview configuration article to suit site requirements. CAUTION: If database messages are not being used - i.e. if $wgUseDatabaseMessages is set false - then $wgHierarchyPage must be set for edits to take effect i.e for the default page location uncomment the line added to LocalSettings.php above: $wgHierarchyPage = 'MediaWiki:Treeview'; The $wgHierarchyPage setting's description below has more information. * Optionally but recommended, create the help articles based on the files in the directory: Treeview/help_articles. The suggested title of the article for the imported file Help.Treeview_skin.Treeview.wiki is 'Help:Treeview skin:Treeview', and the suggested title of the article for the imported file Help.Treeview_skin.Syntax.wiki is 'Help:Treeview skin:Syntax'. Optionally edit or translate these files first, but be aware that a later release might meaningfully change their supplied content files. == Variables and settings == This alphabetical list describes all global variables that apply to this skin and that can be set in LocalSettings.php - each of these is specific to the Treeview skin and/or Hierarchy extension unless otherwise stated. Item symbols have these meanings: + a mandatory setting. * a significant or likely to be useful setting, but not mandatory - a lower-level or less likely to be useful setting. - $wgAllowRelNext (boolean; default: true) Whether to add rel="next" to navigation links where appropriate - this might prompt browsers to precache pages, hitting the wiki server more often than is necessary. The extra traffic can be avoided by setting this variable to false. + $wgCacheEpochTouchFile (string; REQUIRED - no default - the extension will abort and display a diagnostic if this variable is unset when client and/or file caching is enabled) The path to a file whose last-modified time is set and consulted by the Hierarchy extension to ensure that file/client-cache invalidations can be performed - a dynamic version of $wgCacheEpoch. The web-server must have read/write permission on that file. This setting is necessary only if both client ($wgCachePages) and file ($wgUseFileCache) caching are enabled. Those two variables are defined by MediaWiki core; most (all?) MediaWiki releases set $wgCachePages to true in DefaultSettings.php. The way to set appropriate permissions on such a file varies by operating system. On a UNIX or similar system (Linux, *BSD, Solaris, etc), ask your system administrator to create the file with permissions set to 550 and with user and group ownership set to the user and group that the webserver is running under (typically both are 'apache'), and located e.g. at yourmediawikiroot/cache_epoch_touchfile. Then for the same example, add to LocalSettings.php: $wgCacheEpochTouchFile = 'yourmediawikiroot/cache_epoch_touchfile'; As a last resort, or while your admin is otherwise occupied, simply adding to LocalSettings.php: $wgCacheEpochTouchFile = '/tmp/mediawiki_treeview_cache_epoch_touchfile'; will probably work under a UNIX system. - $wgCookiePath (not Treeview-specific - set by MediaWiki core in DefaultSettings.php - probable default value is '/') The root path of this site against which to store skin/treeview state cookies in browsers. If multiple wikis are hosted on the same domain, this can be set to a different top-level directory for each, e.g. '/mediawiki1' and '/mediawiki2', but beware rewrite rules - e.g. don't set $wgCookiePath to $wgScriptPath (which at time of writing itself defaults to '/mediawiki') if '/mediawiki' is being converted by a webserver rewrite rule to '/wiki' and $wgArticlePath is set to '/wiki/$1', because then the treeview javascript will be storing cookies at /mediawiki and not finding them when new pages are loaded under /wiki. * $wgGroupPermissions (array; no default settings are applied i.e. maximally restrictive permissions; this is a MediaWiki-core array - be careful not to overwrite the value of any previously set members) This structure can be used to set access to the Treeview/Hierarchy actions for viewing parse diagnostics, rebuilding the treeview and viewing its cache status. A tab is added to the page actions when viewing the configuration page (or its stand-in) for each action for which the corresponding right is active. The actions are also accessible at Special:Hierarchy. So e.g. to allow anyone to view the configuration's parse diagnostics, to allow only logged-in users to view the treeview's cache status, and to allow only bureaucrats to rebuild the treeview in cache, add these lines to LocalSettings.php in an appropriate location: $wgGroupPermissions['*' ]['parsetreeview' ] = true; $wgGroupPermissions['user' ]['treeviewcachestatus'] = true; $wgGroupPermissions['bureaucrat']['rebuildtreeview' ] = true; * $wgHierarchyPage (string; default: none - if this variable is unset then the 'Treeview' message is used rather than an article - the practical effect of this is described in the square brackets below) [IMPORTANT: If $wgUseDatabaseMessages is set false, then it is mandatory to set (in LocalSettings.php) $wgHierarchyPage to 'MediaWiki:Treeview' prior to editing that article (so that changes take effect), and to leave $wgHierarchyPage unset prior to any edits if the 'MediaWiki:Treeview' article does not already exist (so that the default configuration is used). Note: $wgUseDatabaseMessages is a MediaWiki-core variable whose default value in most (all?) MediaWiki versions is true, so typically this paragraph does not apply.] The name of the page from which the treeview's configuration is sourced. The page needn't be in the 'MediaWiki' namespace but it should be a content page - i.e. pages in the Special and Image namespaces are invalid. This page is to the Treeview skin what the 'Sidebar' message (accessible as the 'MediaWiki:Sidebar' article when $wgUseDatabaseMessages is true) is to the Monobook skin. Side-note: the original source of this configuration text is the 'Treeview' message in the $messages[$wgLanguageCode] array in the extensions/Hierarchy/Hierarchy.i18n.php file, where $wgLanguageCode represents the value of the identically named MediaWiki-core variable that specifies the wiki's user-interface language e.g. 'en' for English. - $wgShowCopyrightIcon (boolean; default: true) Whether to show the copyright icon in the footer. - $wgShowPoweredByIcon (boolean; default: true) Whether to show the powered-by icon in the footer. * $wgStoreTreeviewNodeIdsInDB (boolean; default: unset i.e. false) Whether to store treeview node ids in a database table, created as described beside "TABLE CREATION" below. This ensures that the same id is used for a node between treeview rebuilds when the referenced article originally was non-existent and later is created (node-ids normally include the numeric article-id as a component when the article exists). This can help to avoid minor load-on-demand glitches when the article is created (triggering a treeview rebuild) and the node is expanded in a treeview on a previously opened page. When $wgStoreTreeviewNodeIdsInDB is false, the likely outcome is an error message displayed in the branch indicating that the node no longer exists and prompting for a re-sync. When true, the node will simply expand as usual. TABLE CREATION: Create the database table within the $wgDBname database using the SQL in Hierarchy/treeview_tables.sql after replacing the symbol /*$wgDBprefix*/ in that file with the value (possibly empty) of $wgDBprefix as set (or not set i.e. empty) in LocalSettings.php. - $wgTreeviewHelpPage: (string; default: 'Help:Treeview skin:Treeview') The page that the question mark in the treeview menu bar links to. [Note: the treeview menu bar has been disabled as it was too arcane, so this setting no longer has any purpose] - $wgTreeviewIconHeight (integer; default: 13) The expected height in pixels of the icons used in the treeview. - $wgTreeviewIconWidth (integer; default: 13) The expected width in pixels of the icons used in the treeview. == Limitations == 1. Not scalable; optimal performance requires a cache manager (see "Performance and scalability" below). 2. If a cache manager is enabled then the treeview code disables per-user translations of treeview strings - i.e. if $wgLanguageCode is set to 'nl' (Dutch) and a user sets his/her language preference to 'en' (English), then treeview node titles and tooltips will be displayed in Dutch regardless. == Other languages == Customised text for other languages may be added to the Hierarchy.i18n.php file of the Hierarchy extension; simply copy the $messages['en'] array from: $messages['en'] = array( to the close of that array: ); i.e. just prior to the Dutch entry, $messages['nl']. Paste what you've copied to the end of the file (but before the ?>), edit the 'en' to the code for your language, and then edit the translations. If you do this, I'd love it if you sent me a copy so I can include it in the next release. == Performance and scalability == The treeview component of the skin was designed for optimal performance when a caching plugin for MediaWiki is present, typically this means Memcached. This is a two step process: first install the caching solution external to MediaWiki, and then configure it within MediaWiki. Both of these steps are fairly straightforward - for the latter, consult the MediaWiki documentation on $wgMainCacheType and its related settings such as $wgUseMemCached and $wgMemCachedServers. Be aware that limitation #2 above applies though. Performance may be unacceptably slow without caching. This is because the entire treeview will be rebuilt on each page view, without being able to avoid this on the next view by retrieving it from the cache and only updating nodes that have changed. It would be possible to improve performance for a no-cache setup, but the maintainer does not have plans to do so for the skin in its current incarnation. The Treeview skin is probably best suited to small-medium sized sites with low-moderate traffic. It probably won't scale well unless: * the number of nodes in the treeview is restricted, and/or * the wiki is infrequently edited and is infrequently changed in ways that otherwise trigger a treeview rebuild (see below under "Triggering a treeview rebuild"). If the number of nodes is not simultaneously restricted though, PHP memory requirements might then become significant. Some representative data: for a treeview with 252 nodes, the cached object size was 286667 bytes, which could be reduced to 20319 bytes with compression. === Performance priorities === When designing the skin and after assuming the presence of a cache, priority was then assigned from highest to lowest to the speed of: 1. on-demand xml loads of nodes through Special:Hierarchy when anonymous 2 on-demand xml loads of nodes through Special:Hierarchy when logged-in AND page views when anonymous 3. page views when logged in 4. all other - mostly page edits == Triggering a treeview rebuild == To trigger a cache invalidation and a complete rebuild of the treeview, which will also invalidate all page entries in the file and client caches if either of those caches is enabled, do one of the following: * Follow the 'Rebuild treeview' link on the Special:Hierarchy page, or when it appears as a tab when viewing the configuration page/stand-in page, or otherwise supply an action=rebuildtreeview url query parameter when accessing that page. Requirements: the 'rebuildtreeview' right. * Save the article with the title specified by the $wgHierarchyPage setting - by default this is 'MediaWiki:Treeview'. There is no need to make changes to the article before saving it, although in earlier MediaWiki versions this page itself will not be rebuilt unless changes are made or it is later purged. Requirements: $wgHierarchyPage is set and/or $wgUseDatabaseMessages is true; the right to edit or create new pages in the MediaWiki or other applicable namespace. * Save a new article Requirements: the right to create new pages. * Move an article Requirements: the 'move' right. * Delete an article Requirements: the 'delete' right. * Undelete an article Requirements: the 'undelete' right. * Edit a message upon which the treeview depends Requirements: $wgUseDatabaseMessages is true; the right to edit pages in the MediaWiki namespace. * Upload an image used as a treeview icon. Requirements: the 'upload' right. == Contributions and patches == Contributions and patches are welcome so long as they're coded neatly and are licenced as GPL2 and also grant permission to the skin's maintainer to separately licence the patch under a scheme of the skin maintainer's choice (it would be acceptable for the patch author to require that s/he be listed in the credits of any released code that incorporates the patch, or parts of it, under a new licence). Contributed code might be reformatted to match the style of the rest of the treeview code. == Public distribution and versioning == The extension is released as a beta. Distribution should occur as a set of related files rather than individually, because any two separate files from different releases may be incompatible. == Licence == The public licence covering the entirety of the Hierarchy extension and the Treeview skin - code and documentation - is the General Public Licence 2 (GPL2): http://www.gnu.org/copyleft/gpl.html. This is required for the code because it extends MediaWiki which is under that licence. Other licencing terms might be provided to well-intentioned inquirers. == Latest version == The latest version of this code can be found at: .