Peter M. Groen / knowledgetree

Commit 6ce10527595d01335a1dd3ed77c460d956482792

Authored by Brad Shuttleworth
1 parent f3292ff3

new help environment. 


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

219 Bytes