Compatible with DokuWiki

Hrun

• Download
• Report bugs

DokuWiki helper and admin for setting up settings based on NS/page hierarchy to a plugin

Last updated on

2015-08-10

Provides

Helper

Repository

Source

Requires

config, explorertree, memcache

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Similar to acl, config

Tagged with admin, config, embed, hierarchy, settings

By János Fekete

• memcache
• explorertree

This plugin is currently in RC! Current version is in testing, with a few limitations (only the common settings types are tested/implemented, no special cases yet). Stable version should be out after some more testing.

The plugin depends on explorertree and config. It also uses memcache if installed.

This plugin requires a html5 browser to work! If you need to use the admin pages via commandline- or pre-html5 browsers (e.g. lynx or ie7), do not use plugins which depends on this one.

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

This plugin is for plugin authors, to simply embed an admin page allowing to set settings (aka. plugin configs) based on namespace hierarchy of the wiki.

Demo based on dw2pdf:

The helper can be included to your plugin's admin page, and it displays an area as see in the screenshot. The area have 3 parts:

• explorertree (top left) to select page/NS,
• settings (right, main area) to edit settings,
• and a hierarchical view for a setting value (middle/bottom left) to overview where and how it was changed.

The settings are borrowed from config, with a bit of update to the interface and functionalities:

• ajax based interface (hence html5 browser with enabled javascript is required)
• you can override settings by namespace or page which applies to current and descendant pages/NS-es
• you can set protection to settings which applies to all descendant pages/NS-es or before-action config popups.
• uses (memcached) hierarchy for each plugin stored in DW/data/settingstree/<pluginname><type>.json as json.
  • settings are manually editable there with a json editor, but be sure remove cached value.
• settings meta, default values are stored with a “version” (timestamp) so if you update the plugin's config meta/defaults, they will be applied.
  • example code checks/sets version by the timestamp of the latest file modification time of the plugin's conf/metadata.php, conf/default.php and conf/extend.php
• settings in the admin may overlap settings in config:
  • plugins's configs (what you see in config manager) can be included as is
    • with optionally ignoring a some
  • plugins's configs can be extended.
• settings extend config in order:
  1. config value: (in config plugin)
     1. default value
     2. local value (overrides default)
     3. protected value (overrides default or local)
  2. root namespace:
     1. default: effective value from config
     2. value protection: if config has protected value
     3. local: value (overrides config's effective value) → can not set if protected.
     4. set protection (descendant levels will see current level's effective value as protected)
  3. child namespace/page:
     1. default: effective value from parent
     2. value protection: if any level above (including config) has protected value
     3. local: value (overrides parent's effective value) → can not set if protected.
     4. set protection (descendant levels will see current level's effective value as protected)
• if a value is set/local on (config→root→level1→level2) and config, root or level1 became protected, the local value of level2 is kept but ignored, and the protected value is the effective.
  • after removing the protection level2 local value is effective again.
  • see example on screenshot (on test1 → “Value is set to A4 but ignored”)
• You can not leave a level if there is changed but unsaved values:
  • You need to either save or cancel changes
  • all unsaved but changed values are highlighted with wheat cell background.

Example:

class admin_plugin_<yourplugin> extends DokuWiki_Admin_Plugin {
	private $settings_helper = null;
	private $settings_registered = false;
	function get_settings_helper(){
		if (!$this->settings_helper){
			$this->settings_helper = plugin_load('helper','settingstree');
		}
		return $this->settings_helper;
	}
	function init_settingstree(){
		if (!($e = $this->get_settings_helper())) return;
		if ($this->settings_registered) return $e;
		$confdir = DOKU_INC.'lib/plugins/<yourplugin>/conf/';
		// check if the already stored version is the same as the current one we offer, and reregister options if the settingstree version is older.
		if ($e->checkSettingsVersion('<yourplugin>',			
			$ver = max(			
				// we're comparing the registered settings versus the configuration files' last change.
				// metadata may have an extra '_ignore_for_settingstree' =>true, in which case it won't be configurable by settingstree
				filemtime($confdir.'metadata.php'),
				filemtime($confdir.'default.php'),
				// extends.php have exactly the same syntax as default.php + metadata.php (in the same file), but these settings are only configurable by settingstree plugin and not by config.
				@filemtime($confdir.'extends.php')
			))){
			$meta = array();
			$conf = array();
			include($confdir.'metadata.php');
			include($confdir.'default.php');
			if (file_exists($confdir.'extends.php')) {include($confdir.'extends.php');}	// this file may not exist
			$e->registerSettings('<yourplugin>',$ver,$meta,$conf);	// (re)register settings for this plugin..
		}
		$this->settings_registered = true;
		return $e;
	}
 
	function __construct(){
		$this->init_settingstree();
    }
	function handle() {
		// changes are handled with ajax, so nothing to do here.
    }
	function html(){
        echo '<h1>'.$this->getLang('admin_set_options').'</h1>'.NL;
		if (!($e = $this->init_settingstree())){
			echo "something's wrong..."; return;
		}
		echo $e->showAdmin('<yourplugin>',':'); // yeah... that's it. we embedded it to our admin. YAAY!!
	}
    function forAdminOnly() {	// for only superusers (true) or also for managers (false)?
        return $this->getConf('admin_only_setoptions');
    }
	function getMenuText($language) {
        return $this->getLang('admin_set_options');
    }
    function getMenuSort() {
        return 100;
    }
}

The plugin uses the same settings meta, defaults and lang structure as config manager plugin.

Current status:

• feature freeze, prepare to stable
  • unplanned, but required feature before stable: “export-config”, which will be merged in a week.
  • “export-config” feature added, returning to feature freeze.
• documentation needs to be extended added here.
• admin interface is done.
• export-modal interface is done.
• helper methods added
  • helper methods currently only documented by getMethod (see methods parameters there)
• test for all setting types.

• 2015-07-20
  • Beta / demo release
• 2015-07-22
  • minor fixes.
    • script / gui cosmetic fixes.
  • testing/RC release
• 2015-07-23
  • disable caching if it's emulated
  • trigger error on unmet dependency
  • clean up commented out codes
• 2015-07-27
  • removed explorertree's js callbacks, instead listening to explorertree's events (this to preparation for export-config feature)
  • added id to explorertree, but currently hardcoded.
  • removed global functions, now instead listening to events:
    • settingstree_selectlevel → listen to explorertree's tree_selected event instead
    • settingstree_show_in_hierarchy → listen to show_in_hierarchy event on root instead.
  • exploded settingslevel-'s and settingswrapper-'s showHtml method to smaller parts (in preparation for export-config feature)
• 2015-07-29
  • added 'export-config' feature:
    • display modal to set temporary settings override. can be used for changing configuration temorarly for a process (such as exporting, hence the name)
    • export-modal has much more similar interface to config plugin, as area is wider and protection checkbox is not present.
    • added ``_ignore_for_export`` meta option to hide settings from export-config modal.
  • fixed: if invalid value prevented save, all changed values remain changed
  • fixed: in update info, “updated from '[default value]'” now displays the effective value and displays '(default value)' behind it.
  • fixed: lost event when selecting root after initialization.
• 2015-07-30
  • minor fixes.
• 2015-07-30
  • fix: modal placement and size on low resolution devices

I currently don't have much time to test with all possible setting-type, and browsers… The current release (07-29) works with Chrome, FF, and IE10.

…