config plugin ui organization

  - organizes the configuration settings list into chunks
  - provides a table of contents for the configuration chunks
  - provides one chunk for each plugin with configurable settings
  - provides one chunk for the active template (if it has settings)
  - provides the config file setting as a tool-tip on the setting label
    ex. $conf['start']
  - provides for localization of useful strings
  - generates a "smart" fallback name for plugins and templates
  - plugin and template sections are only shown if they have settings
  - current configuration list is organized into chunks

Note: There are NEW strings to translate into the non-english language files.

darcs-hash:20060510065732-05dcb-398d5c7efa7981f690d97a25a5110b1f39be9f8e.gz

6 files changed, 244 insertions, 49 deletions

diff --git a/lib/plugins/config/admin.php b/lib/plugins/config/admin.php
index 8031b6f27..cae1c3e42 100644
--- a/lib/plugins/config/admin.php
+++ b/lib/plugins/config/admin.php
@@ -97,6 +97,7 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
       if (is_null($this->_config)) { $this->_config = new configuration($this->_file); }
       $this->setupLocale(true);
 
+      $this->_print_config_toc();
       print $this->locale_xhtml('intro');
 
       ptln('<div id="config__manager">');
@@ -109,22 +110,48 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
         ptln('<div class="success">'.$this->getLang('updated').'</div>');
 
       ptln('<form action="'.wl($ID).'" method="post">');
-      ptln('  <table class="inline">');
+      $this->_print_h1('dokuwiki_settings', $this->getLang('_header_dokuwiki'));
 
+      $in_fieldset = false;
+      $first_plugin_fieldset = true;
+      $first_template_fieldset = true;
       foreach($this->_config->setting as $setting) {
-
-        list($label,$input) = $setting->html($this, $this->_error);
-
-        $class = $setting->is_default() ? ' class="default"' : ($setting->is_protected() ? ' class="protected"' : '');
-        $error = $setting->error() ? ' class="error"' : '';
-
-        ptln('    <tr'.$class.'>');
-        ptln('      <td>'.$label.'</td>');
-        ptln('      <td'.$error.'>'.$input.'</td>');
-        ptln('    </tr>');
+        if (is_a($setting, 'setting_fieldset')) {
+          // config setting group
+          if ($in_fieldset) {
+            ptln('  </table>');
+            ptln('  </fieldset>');
+          } else {
+            $in_fieldset = true;
+          }
+          if ($first_plugin_fieldset && substr($setting->_key, 0, 10)=='plugin'.CM_KEYMARKER) {
+            $this->_print_h1('plugin_settings', $this->getLang('_header_plugin'));
+            $first_plugin_fieldset = false;
+          } else if ($first_template_fieldset && substr($setting->_key, 0, 7)=='tpl'.CM_KEYMARKER) {
+            $this->_print_h1('template_settings', $this->getLang('_header_template'));
+            $first_template_fieldset = false;
+          }
+          ptln('  <fieldset name="'.$setting->_key.'" id="'.$setting->_key.'">');
+          ptln('  <legend>'.$setting->prompt($this).'</legend>');
+          ptln('  <table class="inline">');
+        } else {
+          // config settings
+          list($label,$input) = $setting->html($this, $this->_error);
+
+          $class = $setting->is_default() ? ' class="default"' : ($setting->is_protected() ? ' class="protected"' : '');
+          $error = $setting->error() ? ' class="value error"' : ' class="value"';
+
+          ptln('    <tr'.$class.'>');
+          ptln('      <td><a class="nolink" title="$'.$this->_config->_name.'[\''.$setting->_out_key().'\']">'.$label.'</a></td>');
+          ptln('      <td'.$error.'>'.$input.'</td>');
+          ptln('    </tr>');
+        }
       }
 
       ptln('  </table>');
+      if ($in_fieldset) {
+        ptln('  </fieldset>');
+      }
 
       ptln('<p>');
       ptln('  <input type="hidden" name="do"     value="admin" />');
@@ -204,6 +231,12 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
               $this->lang['plugin'.CM_KEYMARKER.$plugin.CM_KEYMARKER.$key] = $value;
             }
           }
+
+          // fill in the plugin name if missing (should exist for plugins with settings)
+          if (!isset($this->lang['plugin'.CM_KEYMARKER.$plugin.CM_KEYMARKER.'plugin_settings_name'])) {
+            $this->lang['plugin'.CM_KEYMARKER.$plugin.CM_KEYMARKER.'plugin_settings_name'] =
+              ucwords(str_replace('_', ' ', $plugin)).' '.$this->getLang('_plugin_sufix');
+          }
         }
         closedir($dh);
       }
@@ -219,8 +252,91 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
           $this->lang['tpl'.CM_KEYMARKER.$tpl.CM_KEYMARKER.$key] = $value;
         }
       }
+
+      // fill in the template name if missing (should exist for templates with settings)
+      if (!isset($this->lang['tpl'.CM_KEYMARKER.$tpl.CM_KEYMARKER.'template_settings_name'])) {
+        $this->lang['tpl'.CM_KEYMARKER.$tpl.CM_KEYMARKER.'template_settings_name'] =
+          ucwords(str_replace('_', ' ', $tpl)).' '.$this->getLang('_template_sufix');
+      }
       
       return true;
     }
 
+    /**
+    * Generates a two-level table of contents for the config plugin.
+    * Uses inc/parser/xhtml.php#render_TOC to format the output.
+    * Relies on internal data structures in the Doku_Renderer_xhtml class.
+    *
+    * @author Ben Coburn <btcoburn@silicodon.net>
+    */
+    function _print_config_toc() {
+      // gather toc data
+      $toc = array('conf'=>array(), 'plugin'=>array(), 'template'=>null);
+      foreach($this->_config->setting as $setting) {
+        if (is_a($setting, 'setting_fieldset')) {
+          if (substr($setting->_key, 0, 10)=='plugin'.CM_KEYMARKER) {
+            $toc['plugin'][] = $setting;
+          } else if (substr($setting->_key, 0, 7)=='tpl'.CM_KEYMARKER) {
+            $toc['template'] = $setting;
+          } else {
+            $toc['conf'][] = $setting;
+          }
+        }
+      }
+
+      // build toc list
+      $xhtml_toc = array();
+      $xhtml_toc[] = array('hid' => 'configuration_manager',
+          'title' => $this->getLang('_configuration_manager'),
+          'type'  => 'ul',
+          'level' => 1);
+      $xhtml_toc[] = array('hid' => 'dokuwiki_settings',
+          'title' => $this->getLang('_header_dokuwiki'),
+          'type'  => 'ul',
+          'level' => 1);
+      foreach($toc['conf'] as $setting) {
+        $name = $setting->prompt($this);
+        $xhtml_toc[] = array('hid' => $setting->_key,
+            'title' => $name,
+            'type'  => 'ul',
+            'level' => 2);
+      }
+      if (!empty($toc['plugin'])) {
+        $xhtml_toc[] = array('hid' => 'plugin_settings',
+            'title' => $this->getLang('_header_plugin'),
+            'type'  => 'ul',
+            'level' => 1);
+      }
+      foreach($toc['plugin'] as $setting) {
+        $name = $setting->prompt($this);
+        $xhtml_toc[] = array('hid' => $setting->_key,
+            'title' => $name,
+            'type'  => 'ul',
+            'level' => 2);
+      }
+      if (isset($toc['template'])) {
+        $xhtml_toc[] = array('hid' => 'template_settings',
+            'title' => $this->getLang('_header_template'),
+            'type'  => 'ul',
+            'level' => 1);
+        $setting = $toc['template'];
+        $name = $setting->prompt($this);
+        $xhtml_toc[] = array('hid' => $setting->_key,
+            'title' => $name,
+            'type'  => 'ul',
+            'level' => 2);
+      }
+
+      // use the xhtml renderer to make the toc
+      require_once(DOKU_INC.'inc/parser/xhtml.php');
+      $r = new Doku_Renderer_xhtml;
+      $r->toc = $xhtml_toc;
+      print $r->render_TOC();
+    }
+
+    function _print_h1($id, $text) {
+      ptln('<h1><a name="'.$id.'" id="'.$id.'">'.$text.'</a></h1>');
+    }
+
+
 }
diff --git a/lib/plugins/config/lang/en/lang.php b/lib/plugins/config/lang/en/lang.php
index 4e033594a..a19a71d0d 100644
--- a/lib/plugins/config/lang/en/lang.php
+++ b/lib/plugins/config/lang/en/lang.php
@@ -17,6 +17,27 @@ $lang['nochoice']   = '(no other choices available)';
 $lang['locked']     = 'The settings file can not be updated, if this is unintentional, <br />
                        ensure the local settings file name and permissions are correct.';
 
+/* --- Config Setting Headers --- */
+$lang['_configuration_manager'] = 'Configuration Manager'; //same as heading in intro.txt
+$lang['_header_dokuwiki'] = 'DokuWiki Settings';
+$lang['_header_plugin'] = 'Plugin Settings';
+$lang['_header_template'] = 'Template Settings';
+
+/* --- Config Setting Groups --- */
+$lang['_basic'] = 'Basic Settings';
+$lang['_display'] = 'Display Settings';
+$lang['_authentication'] = 'Authentication Settings';
+$lang['_anti_spam'] = 'Anti-Spam Settings';
+$lang['_editing'] = 'Editing Settings';
+$lang['_links'] = 'Link Settings';
+$lang['_advanced'] = 'Advanced Settings';
+$lang['_network'] = 'Network Settings';
+// The settings group name for plugins and templates can be set with
+// plugin_settings_name and template_settings_name respectively. If one
+// of these lang properties is not set, the group name will be generated
+// from the plugin or template name and the localized suffix.
+$lang['_plugin_sufix'] = 'Plugin Settings';
+$lang['_template_sufix'] = 'Template Settings';
 
 /* -------------------- Config Options --------------------------- */
 
@@ -49,8 +70,8 @@ $lang['refshow']     = 'Number of media references to show';
 $lang['allowdebug']  = 'Allow debug <b>disable if not needed!</b>';
 
 $lang['usewordblock']= 'Block spam based on wordlist';
-$lang['indexdelay']  = 'Time delay before indexing';
-$lang['relnofollow'] = 'Use rel="nofollow"';
+$lang['indexdelay']  = 'Time delay before indexing (sec)';
+$lang['relnofollow'] = 'Use rel="nofollow" on external links';
 $lang['mailguard']   = 'Obfuscate email addresses';
 
 /* Authentication Options */
@@ -102,10 +123,10 @@ $lang['proxy____host'] = 'Proxy servername';
 $lang['proxy____port'] = 'Proxy port';
 $lang['proxy____user'] = 'Proxy user name';
 $lang['proxy____pass'] = 'Proxy password';
-$lang['proxy____ssl']  = 'use ssl to connect to Proxy';
+$lang['proxy____ssl']  = 'Use ssl to connect to Proxy';
 
 /* Safemode Hack */
-$lang['safemodehack'] = 'enable safemode hack';
+$lang['safemodehack'] = 'Enable safemode hack';
 $lang['ftp____host'] = 'FTP server for safemode hack';
 $lang['ftp____port'] = 'FTP port for safemode hack';
 $lang['ftp____user'] = 'FTP user name for safemode hack';
diff --git a/lib/plugins/config/settings/config.class.php b/lib/plugins/config/settings/config.class.php
index e51f65814..a8665c6ea 100644
--- a/lib/plugins/config/settings/config.class.php
+++ b/lib/plugins/config/settings/config.class.php
@@ -222,7 +222,11 @@ if (!class_exists('configuration')) {
           if (@file_exists(DOKU_PLUGIN.$plugin.$file)){
             $meta = array();
             @include(DOKU_PLUGIN.$plugin.$file);
+            if (!empty($meta)) {
+              $metadata['plugin'.CM_KEYMARKER.$plugin.CM_KEYMARKER.'plugin_settings_name'] = array('fieldset');
+            }
             foreach ($meta as $key => $value){
+              if ($value[0]=='fieldset') { continue; } //plugins only get one fieldset
               $metadata['plugin'.CM_KEYMARKER.$plugin.CM_KEYMARKER.$key] = $value;
             }
           }
@@ -234,7 +238,11 @@ if (!class_exists('configuration')) {
       if (@file_exists(DOKU_TPLINC.$file)){
         $meta = array();
         @include(DOKU_TPLINC.$file);
+        if (!empty($meta)) {
+          $metadata['tpl'.CM_KEYMARKER.$tpl.CM_KEYMARKER.'template_settings_name'] = array('fieldset');
+        }
         foreach ($meta as $key => $value){
+          if ($value[0]=='fieldset') { continue; } //template only gets one fieldset
           $metadata['tpl'.CM_KEYMARKER.$tpl.CM_KEYMARKER.$key] = $value;
         }
       }
diff --git a/lib/plugins/config/settings/config.metadata.php b/lib/plugins/config/settings/config.metadata.php
index 60f32b312..73132aaea 100644
--- a/lib/plugins/config/settings/config.metadata.php
+++ b/lib/plugins/config/settings/config.metadata.php
@@ -21,6 +21,8 @@
  *   'password'     - password input, minimal input validation, setting output plain text in quotes
  *   'dirchoice'    - as multichoice, selection choices based on folders found at location specified in _dir
  *                    parameter (required)
+ *   'fieldset'     - used to group configuration settings, but is not itself a setting. To make this clear in
+ *                    the language files the keys for this type should start with '_'.
  *
  *  Single Setting
  *  --------------
@@ -66,24 +68,24 @@ $file['protected'] = "DOKU_CONF.'local.protected.php'";  // optional
 // - any settings not mentioned will come after the last setting listed and
 //   will use the default class with no parameters
 
+$meta['_basic']   = array('fieldset');
 $meta['title']    = array('string');
 $meta['start']    = array('string');
-$meta['savedir']  = array('savedir');
 $meta['lang']     = array('dirchoice','_dir' => DOKU_INC.'inc/lang/');
 $meta['template'] = array('dirchoice','_dir' => DOKU_INC.'lib/tpl/');
-
-$meta['dmode']    = array('numeric','_pattern' => '/0[0-7]{3}/');  // only accept octal representation
-$meta['fmode']    = array('numeric','_pattern' => '/0[0-7]{3}/');  // only accept octal representation
+$meta['savedir']  = array('savedir');
 $meta['basedir']  = array('string');
 $meta['baseurl']  = array('string');
+$meta['dmode']    = array('numeric','_pattern' => '/0[0-7]{3}/');  // only accept octal representation
+$meta['fmode']    = array('numeric','_pattern' => '/0[0-7]{3}/');  // only accept octal representation
+$meta['allowdebug']  = array('onoff');
 
-$meta['fullpath']    = array('onoff');
+$meta['_display']    = array('fieldset');
 $meta['recent']      = array('numeric');
 $meta['breadcrumbs'] = array('numeric');
 $meta['youarehere']  = array('onoff');
+$meta['fullpath']    = array('onoff');
 $meta['typography']  = array('onoff');
-$meta['htmlok']      = array('onoff');
-$meta['phpok']       = array('onoff');
 $meta['dformat']     = array('string');
 $meta['signature']   = array('string');
 $meta['toptoclevel'] = array('multichoice','_choices' => array(1,2,3,4,5));   // 5 toc levels
@@ -94,13 +96,8 @@ $meta['deaccent']    = array('multichoice','_choices' => array(0,1,2));
 $meta['useheading']  = array('onoff');
 $meta['refcheck']    = array('onoff');
 $meta['refshow']     = array('numeric');
-$meta['allowdebug']  = array('onoff');
-
-$meta['usewordblock']= array('onoff');
-$meta['indexdelay']  = array('numeric');
-$meta['relnofollow'] = array('onoff');
-$meta['mailguard']   = array('multichoice','_choices' => array('visible','hex','none'));
 
+$meta['_authentication'] = array('fieldset');
 $meta['useacl']      = array('onoff');
 $meta['openregister']= array('onoff');
 $meta['autopasswd']  = array('onoff');
@@ -111,43 +108,54 @@ $meta['defaultgroup']= array('string');
 $meta['superuser']   = array('string');
 $meta['profileconfirm'] = array('onoff');
 
+$meta['_anti_spam']  = array('fieldset');
+$meta['usewordblock']= array('onoff');
+$meta['relnofollow'] = array('onoff');
+$meta['indexdelay']  = array('numeric');
+$meta['mailguard']   = array('multichoice','_choices' => array('visible','hex','none'));
+
+$meta['_editing']    = array('fieldset');
+$meta['usedraft']    = array('onoff');
+$meta['spellchecker']= array('onoff');
+$meta['htmlok']      = array('onoff');
+$meta['phpok']       = array('onoff');
+$meta['notify']      = array('email');
+$meta['subscribers'] = array('onoff');
+$meta['purgeonadd']  = array('onoff');
+$meta['locktime']    = array('numeric');
+$meta['cachetime']   = array('numeric');
+
+$meta['_links']    = array('fieldset');
+$meta['target____wiki']      = array('string');
+$meta['target____interwiki'] = array('string');
+$meta['target____extern']    = array('string');
+$meta['target____media']     = array('string');
+$meta['target____windows']   = array('string');
+
+$meta['_advanced']   = array('fieldset');
 $meta['userewrite']  = array('multichoice','_choices' => array(0,1,2));
 $meta['useslash']    = array('onoff');
-$meta['usedraft']    = array('onoff');
 $meta['sepchar']     = array('sepchar');
 $meta['canonical']   = array('onoff');
 $meta['autoplural']  = array('onoff');
 $meta['usegzip']     = array('onoff');
-$meta['cachetime']   = array('numeric');
-$meta['purgeonadd']  = array('onoff');
-$meta['locktime']    = array('numeric');
-$meta['notify']      = array('email');
 $meta['mailfrom']    = array('email');
 $meta['gdlib']       = array('multichoice','_choices' => array(0,1,2));
 $meta['im_convert']  = array('im_convert');
-$meta['spellchecker']= array('onoff');
-$meta['subscribers'] = array('onoff');
 $meta['compress']    = array('onoff');
 $meta['hidepages']   = array('string');
 $meta['send404']     = array('onoff');
 $meta['sitemap']     = array('numeric');
-
 $meta['rss_type']    = array('multichoice','_choices' => array('rss','rss1','rss2','atom'));
 $meta['rss_linkto']  = array('multichoice','_choices' => array('diff','page','rev','current'));
 $meta['rss_update']  = array('numeric');
 
-$meta['target____wiki']      = array('string');
-$meta['target____interwiki'] = array('string');
-$meta['target____extern']    = array('string');
-$meta['target____media']     = array('string');
-$meta['target____windows']   = array('string');
-
+$meta['_network']    = array('fieldset');
 $meta['proxy____host'] = array('string','_pattern' => '#^[a-z0-9\-\.+]+?#i');
 $meta['proxy____port'] = array('numeric');
 $meta['proxy____user'] = array('string');
 $meta['proxy____pass'] = array('password');
 $meta['proxy____ssl']  = array('onoff');
-
 $meta['safemodehack'] = array('onoff');
 $meta['ftp____host']  = array('string','_pattern' => '#^[a-z0-9\-\.+]+?#i');
 $meta['ftp____port']  = array('numeric');
diff --git a/lib/plugins/config/settings/extra.class.php b/lib/plugins/config/settings/extra.class.php
index 0aafd2400..715acb53b 100644
--- a/lib/plugins/config/settings/extra.class.php
+++ b/lib/plugins/config/settings/extra.class.php
@@ -78,3 +78,9 @@ if (!class_exists('setting_im_convert')) {
     }
   }
 }
+
+if (!class_exists('setting_fieldset')) {
+  class setting_fieldset extends setting_string {
+      //do-nothing class used to detect the 'fieldset' type.
+  }
+}
diff --git a/lib/plugins/config/style.css b/lib/plugins/config/style.css
index aab7fac10..4c72a69cd 100644
--- a/lib/plugins/config/style.css
+++ b/lib/plugins/config/style.css
@@ -1,18 +1,43 @@
 /* plugin:configmanager */
-#config__manager {margin: 1em;}
 #config__manager div.success,
 #config__manager div.error,
 #config__manager div.info {
   background-position: 0.5em;
   padding: 0.5em;
-  text-align:center
+  text-align:center;
+}
+
+#config__manager fieldset {
+  margin: 1em;
+  width: auto;
+  margin-bottom: 2em;
+  background-color: __medium__;
+}
+#config__manager legend {
+    font-size: 1.25em;
 }
 
 #config__manager form { }
-#config__manager table {margin: 1em 0;}
-#config__manager td input.edit {width: 30em;}
+#config__manager table {
+    margin: 0.5em;
+    width: 100%;
+}
+
+#config__manager fieldset td {
+    text-align: left;
+}
+#config__manager fieldset td.value {
+    /* fixed data column width */
+    width: 30em;
+}
+#config__manager td input.edit {
+    width: 30em;
+}
 #config__manager td select.edit { }
-#config__manager td textarea.edit {width: 27.5em; height: 4em;}
+#config__manager td textarea.edit {
+    width: 27.5em;
+    height: 4em;
+}
 
 #config__manager tr.default .input,
 #config__manager tr.default input,
@@ -28,6 +53,17 @@
   background-color: #ffcccc;
 }
 
-#config__manager td.error  {background-color: red;}
+#config__manager td.error  { background-color: red; }
+
+#config__manager a.nolink { text-decoration: none; }
+#config__manager a.nolink,
+#config__manager a.nolink:link,
+#config__manager a.nolink:visited,
+#config__manager a.nolink:hover {
+    color: __black__;
+}
+#config__manager a.nolink:active {
+    color: __dark__;
+}
 
 /* end plugin:configmanager */