Improve help plugin with some options to display contents according to the current task/step

plugins/help/config.inc.php.dist

@@ -1,5 +1,30 @@
 <?php
 
 // Help content iframe source
-// $rcmail_config['help_source'] = 'http://trac.roundcube.net/wiki';
+// %l will be replaced by the language code resolved using the 'help_language_map' option
-$rcmail_config['help_source'] = '';
+$rcmail_config['help_source'] = 'http://roundcube.net/doc/help/0.9/%l/';
+
+// Map task/action combinations to deep-links
+// Use '<task>/<action>' or only '<task>' strings as keys
+// The values will be appended to the 'help_source' URL
+$rcmail_config['help_index_map'] = array(
+    'login' => 'login.html',
+    'mail'  => 'mail/index.html',
+    'mail/compose' => 'mail/compose.html',
+);
+
+// Map to translate Roundcube language codes into help document languages
+// The '*' entry will be used as default
+$rcmail_config['help_language_map'] = array('*' => 'en_US');
+
+// Enter an absolute URL to a page displaying information about this webmail
+// Alternatively, create a HTML file under <this-plugin-dir>/content/about.html
+$rcmail_config['help_about_url'] = null;
+
+// Enter an absolute URL to a page displaying information about this webmail
+// Alternatively, put your license text to <this-plugin-dir>/content/license.html
+$rcmail_config['help_license_url'] = null;
+
+// Determine whether to open the help in a new window
+$rcmail_config['help_open_extwin'] = false;
+

plugins/help/content/about.html

@@ -1,27 +0,0 @@
-<div id="helpabout" class="readtext">
-<h2 align="center">Copyright &copy; 2005-2012, The Roundcube Dev Team</h2>
-
-<p>
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License (with exceptions
-for skins &amp; plugins) as published by the Free Software Foundation,
-either version 3 of the License, or (at your option) any later version.
-</p>
-<p>
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
-GNU General Public License for more details.
-</p>
-<p>
-You should have received a copy of the GNU General Public License
-along with this program. If not, see <a href="http://www.gnu.org/licenses/">www.gnu.org/licenses</a>.
-</p>
-
-<p>
-For more details about licensing and the expections for skins and plugins
-see <a href="http://roundcube.net/license">roundcube.net/license</a>.
-</p>
-
-<p><br/>Website: <a href="http://roundcube.net">roundcube.net</a></p>
-</div>

plugins/help/help.js

@@ -0,0 +1,25 @@
+/*
+ * Help plugin client script
+ * @version 1.4
+ */
+
+// hook into switch-task event to open the help window
+if (window.rcmail) {
+    rcmail.addEventListener('beforeswitch-task', function(prop) {
+        // catch clicks to help task button
+        if (prop == 'help') {
+            if (rcmail.task == 'help')  // we're already there
+                return false;
+
+            var url = rcmail.url('help/index', { _rel: rcmail.task + (rcmail.env.action ? '/'+rcmail.env.action : '') });
+            if (rcmail.env.help_open_extwin) {
+                rcmail.open_window(url, false, false);
+            }
+            else {
+                rcmail.redirect(url, false);
+            }
+
+            return false;
+      }
+  });
+}

plugins/help/help.php

@@ -1,9 +1,10 @@
 <?php
 
 /**
- * Help Plugin
+ * Roundcube Help Plugin
  *
  * @author Aleksander 'A.L.E.C' Machniak
+ * @author Thomas Bruederli <thomas@roundcube.net>
  * @license GNU GPLv3+
  *
  * Configuration (see config.inc.php.dist)
@@ -21,6 +22,7 @@ class help extends rcube_plugin
 
     function init()
     {
+        $this->load_config();
         $this->add_texts('localization/', false);
 
         // register task
@@ -31,6 +33,8 @@ class help extends rcube_plugin
         $this->register_action('about', array($this, 'action'));
         $this->register_action('license', array($this, 'action'));
 
+        $rcmail = rcmail::get_instance();
+
         // add taskbar button
         $this->add_button(array(
             'command'    => 'help',
@@ -40,6 +44,9 @@ class help extends rcube_plugin
             'label'      => 'help.help',
         ), 'taskbar');
 
+        $this->include_script('help.js');
+        $rcmail->output->set_env('help_open_extwin', $rcmail->config->get('help_open_extwin', false), true);
+
         // add style for taskbar button (must be here) and Help UI
         $skin_path = $this->local_skin_path();
         if (is_file($this->home . "/$skin_path/help.css")) {
@@ -51,8 +58,6 @@ class help extends rcube_plugin
     {
         $rcmail = rcmail::get_instance();
 
-        $this->load_config();
-
         // register UI objects
         $rcmail->output->add_handlers(array(
             'helpcontent' => array($this, 'content'),
@@ -72,16 +77,39 @@ class help extends rcube_plugin
     {
         $rcmail = rcmail::get_instance();
 
-        if ($rcmail->action == 'about') {
+        switch ($rcmail->action) {
+            case 'about':
+                if (is_readable($this->home . '/content/about.html')) {
                     return @file_get_contents($this->home . '/content/about.html');
                 }
-        else if ($rcmail->action == 'license') {
+                $src = $rcmail->config->get('help_about_url', $rcmail->url(array('_task' => 'settings', '_action' => 'about')));
+                break;
+
+            case 'license':
+                if (is_readable($this->home . '/content/license.html')) {
                     return @file_get_contents($this->home . '/content/license.html');
                 }
+                $src = $rcmail->config->get('help_license_url', 'http://www.gnu.org/licenses/gpl-3.0-standalone.html');
+                break;
+
+            default:
+                $src = $rcmail->config->get('help_source');
+
+                // resolve task/action for depp linking
+                $index_map = $rcmail->config->get('help_index_map', array());
+                $rel = $_REQUEST['_rel'];
+                list($task,$action) = explode('/', $rel);
+                if ($add = $index_map[$rel])
+                    $src .= $add;
+                else if ($add = $index_map[$task])
+                    $src .= $add;
+                break;
+        }
 
         // default content: iframe
-        if ($src = $rcmail->config->get('help_source'))
+        if (!empty($src)) {
-            $attrib['src'] = $src;
+            $attrib['src'] = $this->resolve_language($src);
+        }
 
         if (empty($attrib['id']))
             $attrib['id'] = 'rcmailhelpcontent';
@@ -91,4 +119,13 @@ class help extends rcube_plugin
         return $rcmail->output->frame($attrib);
     }
 
+
+    private function resolve_language($path)
+    {
+        // resolve language placeholder
+        $rcmail = rcmail::get_instance();
+        $langmap = $rcmail->config->get('help_language_map', array('*' => 'en_US'));
+        $lang = !empty($langmap[$_SESSION['language']]) ? $langmap[$_SESSION['language']] : $langmap['*'];
+        return str_replace('%l', $lang, $path);
+    }
 }

plugins/help/localization/de_DE.inc

@@ -18,7 +18,7 @@
 
 $labels = array();
 $labels['help'] = 'Hilfe';
-$labels['about'] = 'Über';
+$labels['about'] = 'Über';
 $labels['license'] = 'Lizenz';
 
 ?>

plugins/help/package.xml

@@ -5,7 +5,7 @@
     http://pear.php.net/dtd/package-2.0.xsd">
 	<name>help</name>
 	<channel>pear.roundcube.net</channel>
-	<summary>Help for Roundcube</summary>
+	<summary>Online Help for Roundcube</summary>
 	<description>Plugin adds a new item (Help) in taskbar.</description>
 	<lead>
 		<name>Aleksander Machniak</name>
@@ -13,10 +13,10 @@
 		<email>alec@alec.pl</email>
 		<active>yes</active>
 	</lead>
-	<date>2012-11-11</date>
+	<date>2013-07-03</date>
 	<version>
-		<release>1.3</release>
+		<release>1.4</release>
-		<api>1.2</api>
+		<api>1.4</api>
 	</version>
 	<stability>
 		<release>stable</release>
@@ -31,7 +31,6 @@
 				<tasks:replace from="@package_version@" to="version" type="package-info"/>
 			</file>
 			<file name="config.inc.php.dist" role="data"></file>
-			<file name="content/about.html" role="data"></file>
 			<file name="content/license.html" role="data"></file>
 			<file name="localization/bs_BA.inc" role="data"></file>
 			<file name="localization/ca_ES.inc" role="data"></file>

plugins/help/skins/classic/templates/help.html

@@ -15,15 +15,15 @@ function help_init_settings_tabs()
 }
 </script>
 </head>
-<body>
+<roundcube:if condition="env:extwin" /><body class="extwin"><roundcube:else /><body><roundcube:endif />
 
 <roundcube:include file="/includes/taskbar.html" />
 <roundcube:include file="/includes/header.html" />
 
 <div id="tabsbar">
 <span id="helptabdefault" class="tablink"><roundcube:button name="helpdefault" href="?_task=help" type="link" label="help.help" title="help.help" /></span>
-<span id="helptababout" class="tablink"><roundcube:button name="helpabout" href="?_task=help&_action=about" type="link" label="help.about" title="help.about" class="tablink" /></span>
+<span id="helptababout" class="tablink"><roundcube:button name="helpabout" href="?_task=help&amp;_action=about" type="link" label="help.about" title="help.about" class="tablink" /></span>
-<span id="helptablicense" class="tablink"><roundcube:button name="helplicense" href="?_task=help&_action=license" type="link" label="help.license" title="help.license" class="tablink" /></span>
+<span id="helptablicense" class="tablink"><roundcube:button name="helplicense" href="?_task=help&amp;_action=license" type="link" label="help.license" title="help.license" class="tablink" /></span>
 <roundcube:container name="helptabs" id="helptabsbar" />
 <script type="text/javascript"> if (window.rcmail) rcmail.add_onload(help_init_settings_tabs);</script>
 </div>

plugins/help/skins/larry/templates/help.html

@@ -4,7 +4,7 @@
 <title><roundcube:object name="pagetitle" /></title>
 <roundcube:include file="/includes/links.html" />
 </head>
-<body>
+<roundcube:if condition="env:extwin" /><body class="extwin"><roundcube:else /><body><roundcube:endif />
 
 <roundcube:include file="/includes/header.html" />