====== settingstree Plugin ====== ---- plugin ---- description: DokuWiki helper and admin for setting up settings based on NS/page hierarchy to a plugin author : János Fekete email : jan@fjan.eu type : helper lastupdate : 2015-08-10 compatible : Hrun depends : config, explorertree, memcache conflicts : similar : config, acl tags : admin embed settings config admin hierarchy downloadurl: https://github.com/fajan/settingstree/archive/master.zip bugtracker : https://github.com/fajan/settingstree/issues sourcerepo : https://github.com/fajan/settingstree donationurl: screenshot_img : https://raw.githubusercontent.com/fajan/settingstree/master/example-screenshot.png ---- **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. ===== Installation ===== The plugin depends on [[plugin:explorertree]] and [[plugin:config]]. It also uses [[plugin: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 [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually. ===== Overview ===== 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: {{https://raw.githubusercontent.com/fajan/settingstree/master/example-screenshot-explain.png}} 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/.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: - config value: (in config plugin) - default value - local value (overrides default) - protected value (overrides default or local) - root namespace: - default: effective value from config - value protection: if config has protected value - local: value (overrides config's effective value) -> can not set if protected. - set protection (descendant levels will see current level's effective value as protected) - child namespace/page: - default: effective value from parent - value protection: if any level above (including config) has protected value - local: value (overrides parent's effective value) -> can not set if protected. - 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. ===== Embed ===== Example: class admin_plugin_ 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//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('', $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('',$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 '

'.$this->getLang('admin_set_options').'

'.NL; if (!($e = $this->init_settingstree())){ echo "something's wrong..."; return; } echo $e->showAdmin('',':'); // 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; } } ===== Configuration and Settings ===== The plugin uses the same settings meta, defaults and lang structure as config manager plugin. ===== Development ===== 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. === Change Log === * **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 === Known Bugs and Issues === 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. === ToDo/Wish List === ... ===== Discussion =====