new help environment.

git-svn-id: https://kt-dms.svn.sourceforge.net/svnroot/kt-dms/trunk@4575 c91229c3-7414-0410-bfa2-8a42b809f60b

new help environment.
git-svn-id: https://kt-dms.svn.sourceforge.net/svnroot/kt-dms/trunk@4575 c91229c3-7414-0410-bfa2-8a42b809f60b
Brad Shuttleworth
1 parent f3292ff3
Showing 16 changed files with 290 additions and 55 deletions
browse.php
help.php
index.html
lib/dispatcher.inc.php
lib/help/help.inc.php
lib/help/helpreplacement.inc.php
lib/templating/kt3template.inc.php
plugins/ktcore/admin/manageHelp.php
resources/css/kt-framing.css
sql/mysql/install/structure.sql
sql/mysql/upgrade/2.99.7/help_replacement.sql
templates/kt3/standard_page.smarty
templates/ktcore/help_with_edit.smarty
templates/ktcore/manage_help.smarty
templates/ktcore/manage_help_item.smarty
thirdparty/icon-theme/16x16/apps/help-browser.png
@@ -51,6 +51,7 @@ class BrowseDispatcher extends KTStandardDispatcher {
     var $browse_mode = null;
     var $query = null;
     var $resultURL;
+    var $sHelpPage = 'ktcore/browse/browse.html';
     function BrowseDispatcher() {
         $this->aBreadcrumbs = array(
+<?php
+
+// main library routines and defaults
+require_once("config/dmsDefaults.php");
+require_once(KT_LIB_DIR . "/templating/templating.inc.php");
+require_once(KT_LIB_DIR . "/templating/kt3template.inc.php");
+require_once(KT_LIB_DIR . "/dispatcher.inc.php");
+require_once(KT_LIB_DIR . "/util/ktutil.inc");
+
+require_once(KT_LIB_DIR . "/security/Permission.inc");
+
+require_once(KT_LIB_DIR . "/help/helpreplacement.inc.php");
+require_once(KT_LIB_DIR . "/help/help.inc.php");
+
+/*
+ *  KT3 Help functionality.
+ *
+ * The KT3 help works slightly differently to the previous versions of KT.
+ * This page takes subpath-info, and uses that to resolve the help documentation
+ * as appropriate.
+ *
+ * This documentation should be placed into KT_DIR/kthelp/COMPONENT_NAME/LANG/...
+ * Currently images and html files are the ONLY supported types.
+ *
+ * Within these directories, local addressing is _relative_ as expected.  
+ *
+ * File names _should not be changed_ from their reference values when translating,
+ * since files are referred to WITHOUT the lang-code (e.g. EN, IT).
+ */
+
+
+class HelpDispatcher extends KTStandardDispatcher {
+
+    var $sSection = "dashboard";
+    var $bIsReplacement = false;
+
+    function is_replacement() { return $this->bIsReplacement; }
+
+    function do_main() {
+        $pathinfo = KTUtil::arrayGet($_SERVER, 'PATH_INFO');
+        if (empty($pathinfo)) {
+            $this->oPage->setTitle(_('No help page specified.'));
+            $this->oPage->addError(_('No help page specified.'));
+            return '&nbsp;';
+        }
+        
+        $can_edit = Permission::userIsSystemAdministrator($_SESSION['userID']);
+               
+        $help_path = KTHelp::getHelpSubPath($pathinfo);
+        if ($help_path == false) {
+            $this->oPage->setTitle(_('Invalid help location specified.'));
+            $this->oPage->addError(_('Invalid help location specified.'));
+            return '&nbsp';
+        }
+        
+        // We now check for substitute help files.  try to generate an error.
+        $oReplacementHelp = KTHelpReplacement::getByName($help_path);
+        
+        // OK.  we know its an image, or html.
+        if (KTHelp::isImageFile($help_path)) {
+            KTHelp::outputHelpImage($help_path);
+        } else {
+            // not an image, so:
+            $aHelpInfo = KTHelp::getHelpFromFile($pathinfo);
+        }
+        
+        
+        // NORMAL users never see edit-option.
+        if (!$can_edit) {
+            if (!PEAR::isError($oReplacementHelp)) {
+                $this->oPage->setTitle($oReplacementHelp->getTitle());
+                return $oReplacementHelp->getDescription();
+            } elseif ($aHelpInfo != false) {
+                $this->oPage->setTitle($aHelpInfo['title']);
+                return $aHelpInfo['body'];
+            } else {
+                $this->oPage->setTitle(_('Invalid help location specified.'));
+                $this->oPage->addError(_('Invalid help location specified.'));
+                return '&nbsp';
+            }
+        } 
+        
+        if (!PEAR::isError($oReplacementHelp)) {
+            $aHelpInfo['title'] = $oReplacementHelp->getTitle();
+            $aHelpInfo['body'] = $oReplacementHelp->getDescription();
+        }
+        // we now _can_ edit.
+        
+        $this->oPage->setTitle($aHelpInfo['title']);
+        
+        $oTemplating = new KTTemplating;
+        $oTemplate = $oTemplating->loadTemplate("ktcore/help_with_edit");
+        $aTemplateData = array(
+              "context" => $this,
+              "help_body" => $aHelpInfo['body'],
+              "target_name" => $_SERVER['PATH_INFO'],
+        );
+        return $oTemplate->render($aTemplateData);
+    }
+
+}
+
+$oDispatcher = new HelpDispatcher();
+$oDispatcher->dispatch();
+
+?>
+
@@ -2,4 +2,7 @@
 <head>
 <meta http-equiv="refresh" content="0; url=control.php"/>
 </head>
+<body>
+You should automatically be redirected to the <a href="control.php">login / dashboard page</a>.
+</body>
 </html>
@@ -123,6 +123,7 @@ class KTStandardDispatcher extends KTDispatcher {
     var $aBreadcrumbs = array();
     var $sSection = false;
     var $oPage = false;
+	var $sHelpPage = null;
     function KTStandardDispatcher() {
         global $main;
@@ -190,6 +191,7 @@ class KTStandardDispatcher extends KTDispatcher {
         $this->oPage->setBreadcrumbs($this->aBreadcrumbs);
         $this->oPage->setPageContents($data);
         $this->oPage->setUser($this->oUser);
+		$this->oPage->setHelp($this->sHelpPage);
 		// handle errors that were set using KTErrorMessage.
 		$errors = KTUtil::arrayGet($_SESSION, 'KTErrorMessage', array());
 <?php
+/* help has changed significantly.  see /help.php */
+
+require_once(KT_LIB_DIR . "/database/dbutil.inc");
+
 class KTHelp {
-    function getHelpStringForSection($sSection) {
-        global $default;
-        $sQuery = "SELECT hlp.help_info AS helpinfo FROM
-            $default->help_table AS hlp WHERE hlp.fSection = ?";
-        $aParams = array($sSection);
-        $sHelpFile = DBUtil::getOneResultKey(array($sQuery, $aParams), 'helpinfo');
-        if (PEAR::isError($sHelpFile)) {
-            return $sHelpFile;
-        }
-        $sQuery = "SELECT hlprp.description AS contents FROM
-            $default->help_replacement_table AS hlprp WHERE
-            hlprp.name = ?";
-        $aParams = array($sHelpFile);
-        $sHelpContents = DBUtil::getOneResultKey(array($sQuery,
-                    $aParams), 'contents');
-        if (PEAR::isError($sHelpContents)) {
-            return $sHelpContents;
+
+    function getHelpSubPath($sHelpFile) {
+        if (empty($sHelpFile)) { return false; }
+        $path_segments = explode("/", $sHelpFile);
+        // cannot be empty, must contain at _least_ 1 item.
+        if (empty($path_segments[0])) {
+            $path_segments = array_slice($path_segments,1);
         }
-        if (!(is_null($sHelpContents) || trim($sHelpContents) === "")) {
-            return $sHelpContents;
+        
+        if (empty($path_segments) or (count($path_segments) < 2)) {
+            return false;             // FIXME use PEAR::Error
         }
-        return file_get_contents("$default->uiDirectory/help/" .  $sHelpFile);
+        
+        // we now assume that path_segments[0] is the module
+        // path_segments[1..] is the subpath.  we need to insert the LANG
+        
+        $lang_code = 'EN'; // FIXME extract the lang from the environ (?)
+        
+        $final_path = array(null,'kthelp', $path_segments[0]);
+        $final_path[] = $lang_code;
+        $final_path = array_merge($final_path, array_slice($path_segments, 1));
+        
+        $help_path = implode('/',$final_path);
+        
+        return $help_path;
     }
     function getHelpFromFile($sHelpFile) {
-        global $default;
-        return file_get_contents("$default->uiDirectory/help/" .  $sHelpFile);
+        if (empty($sHelpFile)) { return false; }
+        $help_path = KTHelp::getHelpSubPath($sHelpFile);
+        
+        $fspath = KT_DIR . $help_path;      // FIXME use OS.path_sep equivalent?
+        
+        if (!file_exists($fspath)) {
+            return false;
+        } 
+        
+        if (KTHelp::isImageFile($help_path)) {
+            return false; // can't - not what users expect.
+        }
+        
+        // now we ASSUME its html:  we'll fail anyway if we aren't.
+        $handle = fopen($fspath, "r");
+        $contents = fread($handle, filesize($fspath));
+        fclose($handle);
+            
+        $info = KTHelp::_parseHTML($contents);
+            
+        $body = KTUtil::arrayGet($info,'body');
+        if (empty($body)) {
+            return false;
+        } 
+        
+        $info['name'] = $help_path; // set so we can save into db if needed.
+        
+        return $info;
+    }
+
+    // world's simplest (and possibly worst) regex-split.
+    function _parseHTML($sHTML) {
+        $title_array = preg_split('#</?title>#',$sHTML,-1,PREG_SPLIT_NO_EMPTY);
+        $body_array = preg_split('#</?body>#',$sHTML,-1,PREG_SPLIT_NO_EMPTY);
+        
+        $res = array();
+        if (count($title_array) > 2) {
+            $res['title'] = $title_array[1];
+        }
+        
+        if (count($body_array) > 2) {
+            $res['body'] = $body_array[1];
+        }
+        
+        //var_dump($body_array);
+        return $res;
     }
+    
+    function isImageFile($sHelpPath) {
+        // from pluginutil.inc.php
+        $fspath = KT_DIR . $sHelpPath;
+        
+        $pi = pathinfo($fspath);
+        $mime_type = "";
+        $sExtension = KTUtil::arrayGet($pi, 'extension');
+        if (!empty($sExtension)) {
+            $mime_type = DBUtil::getOneResultKey(array("SELECT mimetypes FROM " . KTUtil::getTableName('mimetypes') . " WHERE LOWER(filetypes) = ?", $sExtension), "mimetypes");
+        }
+        
+        if (($mime_type == 'image/png') || ($mime_type == 'image/gif') || ($mime_type == 'image/jpeg')) {
+        
+        }
+        
+        return false;
+    }
+    
+    function outputHelpImage($sHelpPath) {
+        $fspath = KT_DIR . $sHelpPath;
+    
+    
+        header("Content-Type: $mime_type");
+        header("Content-Length: " . filesize($fspath));
+        readfile($fspath);   // does this output it?!
+        exit(0);
+    }
+
 }
 ?>
@@ -9,11 +9,13 @@ class KTHelpReplacement extends KTEntity {
     var $sName;
     /** replacement string */
     var $sDescription;
+    var $sTitle;
     var $_aFieldToSelect = array(
         "iId" => "id",
         "sName" => "name",
         "sDescription" => "description",
+        "sTitle" => 'title',
     );
     var $_bUsePearError = true;
@@ -21,9 +23,11 @@ class KTHelpReplacement extends KTEntity {
     function getID() { return $this->iId; }
     function getName() { return $this->sName; }
     function getDescription() { return $this->sDescription; }
+    function getTitle() { return $this->sTitle; }
     function setID($iId) { $this->iId = $iId; }
     function setName($sName) { $this->sName = $sName; }
     function setDescription($sDescription) { $this->sDescription = $sDescription; }
+    function setTitle($sTitle) { $this->sTitle= $sTitle; }
     function _table () {
         global $default;
@@ -33,6 +33,7 @@ class KTPage {
     var $breadcrumbSection = false;
 	var $menu = null;
 	var $userMenu = null;
+	var $helpPage = null;
     /** the "component".  Used to set the page header (see documentation for explanation). */
     var $componentLabel = 'Browse Collections';
@@ -262,6 +263,17 @@ class KTPage {
 		return $aTuple;
     }
+    function setHelp($sHelpPage) {
+		$this->helpPage = $sHelpPage;
+	}
+	
+	function getHelpURL() {
+	    if (empty($this->helpPage)) { 
+		    return null;
+		}
+		
+		return '/help.php/' . $this->helpPage; // FIXME handle auto-url
+	}
 }
 /* set $main - this is used by the rest of the system. */
@@ -19,14 +19,14 @@ class ManageHelpDispatcher extends KTAdminDispatcher {
     function getData() {
         $this->aBreadcrumbs[] = array('action' => 'manageHelp', 'name' => _('Help Administration'));
         $this->oPage->setBreadcrumbDetails(_('select a section'));
-    
+        $this->oPage->setTitle(_('Help Administration'));
         $oTemplating = new KTTemplating;
         $aHelpReplacements =& KTHelpReplacement::getList();
-        $aHelps =& KTHelpEntity::getList();
+        //$aHelps =& KTHelpEntity::getList();
         $oTemplate = $oTemplating->loadTemplate("ktcore/manage_help");
         $aTemplateData = array(
             "context" => &$this,
-            "helps" => $aHelps,
+            //"helps" => $aHelps,
             "helpreplacements" => $aHelpReplacements,
         );
@@ -35,6 +35,7 @@ class ManageHelpDispatcher extends KTAdminDispatcher {
     function getReplacementItemData($oHelpReplacement) {
         $this->aBreadcrumbs[] = array('action' => 'manageHelp', 'name' => _('Help Administration'));
+        $this->oPage->setTitle(_('Editing: ') . $oHelpReplacement->getTitle());
         $oTemplating = new KTTemplating;
         $oTemplate = $oTemplating->loadTemplate("ktcore/manage_help_item");
         $aTemplateData = array(
@@ -80,6 +81,13 @@ class ManageHelpDispatcher extends KTAdminDispatcher {
             return $this->errorRedirectToMain(_("No description given"));
         }
         $oHelpReplacement->setDescription($description);
+        
+        $title = KTUtil::arrayGet($_REQUEST, 'title');
+        if (empty($title)) {
+            return $this->errorRedirectToMain(_("No title given"));
+        }
+        $oHelpReplacement->setTitle($title);
+        
         $res = $oHelpReplacement->update();
         if (PEAR::isError($res)) {
             return $this->errorRedirectToMain(_("Error updating item"));
@@ -89,21 +97,29 @@ class ManageHelpDispatcher extends KTAdminDispatcher {
     function do_customise() {
         $name = KTUtil::arrayGet($_REQUEST, 'name');
+        $name = KTHelp::getHelpSubPath($name);
         $oHelpReplacement = KTHelpReplacement::getByName($name);
         // XXX: Check against "already exists"
         if (!PEAR::isError($oHelpReplacement)) {
             // Already exists...
-            return $this->redirectTo('editReplacement', 'id=' .  $oHelpReplacement->getId());
+            return $this->errorRedirectTo('editReplacement', _('Replacement already exists.'),'id=' .  $oHelpReplacement->getId());
+        }
+        $info = KTHelp::getHelpFromFile($name);
+        if ($info === false) { 
+            $info = array('name' => $name);
+            $info['title'] = _('New Help File');
+            $info['body'] = _('New Help File');
         }
-        $description = KTHelp::getHelpFromFile($name);
         $oHelpReplacement = KTHelpReplacement::createFromArray(array(
-            'name' => $name,
-            'description' => $description,
+            'name' => $info['name'],
+            'description' => $info['body'],
+            'title' => $info['title'],
         ));
+        
         if (PEAR::isError($oHelpReplacement)) {
             return $this->errorRedirectToMain(_("Unable to create replacement"));
         }
-        return $this->successRedirectTo('editReplacement', 'id=' .  $oHelpReplacement->getId());
+        return $this->successRedirectTo('editReplacement', _('Created replacement.'), 'id=' .  $oHelpReplacement->getId());
     }
 }
@@ -611,6 +611,21 @@ The text will be hidden for screen view.  The generic fahrner-ish approach comes
     width: 16px;
     cursor: pointer;
 }
+
+.ktHelp { 
+    background: transparent url(../../thirdparty/icon-theme/16x16/apps/help-browser.png) top left no-repeat;
+    float: right;
+    display: block;
+    text-decoration: none;
+    overflow: hidden;
+    border: 0 !important;
+    padding: 0;
+    padding-top: 16px;
+    height: 0px !important;
+    height /**/: 16px;
+    width: 16px;
+    cursor: pointer;
+}
 /* FIXME when available icon-naming-conformant sets have better coverage, make these more accurate. */
 .ktAction.ktDelete { background: transparent url(../../thirdparty/icon-theme/16x16/mimetypes/x-directory-trash.png) top left no-repeat; }
@@ -719,7 +719,8 @@ CREATE TABLE `help` (
 CREATE TABLE `help_replacement` (
   `id` int(11) NOT NULL default '0',
-  `name` varchar(100) NOT NULL default '',
+  `name` varchar(255) NOT NULL default '',
+  `title` varchar(255) NOT NULL default '',
   `description` text NOT NULL,
   PRIMARY KEY  (`id`)
 ) TYPE=InnoDB ;
+ALTER TABLE help_replacement CHANGE name name VARCHAR(255) NOT NULL default '';
+ALTER TABLE help_replacement ADD title VARCHAR(255) NOT NULL default '';
 \ No newline at end of file
@@ -118,7 +118,9 @@
 </div>
 <div id="content">
-<h1 class="{$page->componentClass}"><span class="fahrner">{$page->componentLabel}</span></h1>
+<h1 class="{$page->componentClass}"><span class="fahrner">{$page->componentLabel}</span>
+{if ($page->getHelpURL() != null)} <a class="ktHelp" href="{$rootUrl}{$page->getHelpURL()}">Help</a> {/if}
+</h1>
 <!-- any status / error messages get added here. -->
 {if (!empty($page->errStack))}
+<p><a href="{$rootUrl}/admin.php/misc/helpmanagement?action=customise&name={$target_name}">Edit this help page.</a></p>
+{if (!$help_body)}
+<div class="ktError"><p>No content specified for this help file yet. <strong>Edit it first.</strong></p></div>
+{else}
+{$help_body}
+{/if}
 \ No newline at end of file
 <h2>Current help assignments</h2>
-<table class="listing">
-<thead>
-<tr>
-<th>Section</th>
-<th>Filename</th>
-<th>Customise</th>
-</tr>
-</thead>
-{foreach item=oHelpEntity from=$helps }
-<tr class="{cycle values="odd,even"}">
-<td> { $oHelpEntity->sSection } </td>
-<td class="descriptiveText"> { $oHelpEntity->sFilename } </td>
-<td>
-{ assign var="replacement" value=$oHelpEntity->checkReplacement() }
-{ if $replacement }
-<a href="{$smarty.server.PHP_SELF}?action=editReplacement&id={$replacement->getId()}">Edit</a>
-{ else }
-<a href="{$smarty.server.PHP_SELF}?action=customise&name={$oHelpEntity->getFilename()}">Customise</a>
-{ /if }
-</td>
-</tr>
-{ /foreach }
-</table>
+<p class="descriptiveText">{i18n}To customise a help file, please visit that file 
+via the help system, and click on <strong>customise this help file</strong>.{/i18n}</p>
 { if $helpreplacements }
 <h2>Existing customised help pages</h2>
@@ -45,5 +24,9 @@
 </tr>
 { /foreach }
 </table>
+
+{else}
+<div class="ktInfo"><p>No Help files have to customised.</p></div>
+
 { /if }
@@ -12,6 +12,7 @@ tinyMCE.init({
 <form method="POST" action="{$smarty.server.PHP_SELF}">
 <input type="hidden" name="id" value="{$help->iId}">
 <input type="hidden" name="action" value="updateReplacement">
+<input type="text" name="title" value="{$help->sTitle|escape}" /><br /><br />
 <textarea cols="60" rows="20" name="description">{$help->sDescription|escape}</textarea>
 <input type="submit" name="submit" value="Update">
 </form>