1
iunderwood
XOOPS Admin Help System Improvements

Crew,

Since i've been moving a couple of my modules to the new Admin GUI, I cannot help but notice how lacking the help interface is for things other than the System module. This is something that we really should change since there are a number of modules that can be quite verbose as far as what quality help content could be.

To that end, I propose extending the help system from a module developer's perspective by making a new array available called "Help Section" implemented something like this:

$i=0;
$modversion['helpsection'][$i]['name'] = "Page 1";
$modversion['helpsection'][$i]['link'] = "page=help";
$i++;
$modversion['helpsection'][$i]['name'] = "Page 2";
$modversion['helpsection'][$i]['link'] = "page=help2";


The trick is in the implementation, as help.pho handles four help classifications:
* mid > 0, system
* mid > 0, non-system
* general, system
* genera, non-system

The first segment I've changed is mid > 0, non-system:

if ( $module->getVar('dirname''e') == 'system' ) {
...
    } else {
/* Original Help Code
        $help = $module->toArray();
        //$help['name'] = $module->getVar('dirname', 's');
        $help['link'] = 'help.php?mid=' . $mid . '&' . $module->getInfo('help');
        $xoopsTpl->append_by_ref( 'help', $help );
        unset($help);
*/

// New Code Start
        
$list_help = array();
        
$listed_mods[0] = $module->toArray();

        
$helplist $module->getInfo('helpsection');
        
$j=0;
        foreach (
$helplist as $helpitem) {
            if ( (
$helpitem['name'] != '') && ($helpitem['link'] != '') ) {
                
$list_help[$j]['name'] = $helpitem['name'];
                
$list_help[$j]['link'] = 'help.php?mid=' $mid '&' $helpitem['link'];
                
$j++;
            }
        }
        unset (
$helplist);
        
$listed_mods[0]['help_page'] = $list_help;
        
$xoopsTpl->assign('list_mods',$listed_mods);

        if (( 
$module->getInfo('help') != '' ) && ($j == 0)){
            
$help['name'] = $module->getInfo('name');
            
$help['link'] = 'help.php?mid=' $mid '&' $module->getInfo('help');
        }
        
$k=0;
// New Code Stop


The second change is general help, non-system.

if ( $module->getVar('dirname''e') == 'system' ) {
...
        } else {
/*
            if ( $module->getInfo('help') != '' ) {
                $list_help[$j]['name'] = $module->getVar('dirname', 's');
                $list_help[$j]['link'] = 'help.php?mid=' . $module->getVar('mid', 'e') . '&' . $module->getInfo('help');
            }
*/

// New Code Start
            
$helplist $module->getInfo('helpsection');

            foreach (
$helplist as $page) {
                if ( (
$page['name'] != '') && ($page['link'] != '') ) {
                    
$list_help[$j]['name'] = $page['name'];
                    
$list_help[$j]['link'] = 'help.php?mid=' $module->getVar('mid''e') . '&' $page['link'];
                    
$j++;
                    
$k++;
                }
            }
            unset (
$helplist);

            if (( 
$module->getInfo('help') != '' ) && ($k == 0)){
                
$list_help[$j]['name'] = $module->getInfo('name');
                
$list_help[$j]['link'] = 'help.php?mid=' $module->getVar('mid''e') . '&' $module->getInfo('help');
            }
            
$k=0;
// New Code Stop
        
}


The code could probably use a little optimization, but it does make it possible for modules to have more than one single page.

Additionally, if the system module could be updated to support this in the main section instead of each little subsection, the code for this piece of the admin puzzle could be significantly shorter.

2
iunderwood
Re: XOOPS Admin Help System Improvements

There were a few assumptions and errors I wanted to clear up. Here's the diff between my patched file, and the one with the XOOPS 2.5.6 distribution:

33d32
// If $mid > 0, we're in a module's help section.
42d40
<     // Special handling for the System Module
43a42

44a44

46a47

48a50

49a52

60,61d62

<     
// Handling for all other modules.
63,83c64,67
<         $list_help = array();
<         
$listed_mods[0] = $module->toArray();
<         
$helplist $module->getInfo('helpsection');
<         
$j=0;
<         if (
is_array($helplist)) {
<             foreach (
$helplist as $helpitem) {
<                 if ( (
$helpitem['name'] != '') && ($helpitem['link'] != '') ) {
<                     
$list_help[$j]['name'] = $helpitem['name'];
<                     
$list_help[$j]['link'] = 'help.php?mid=' $mid '&amp;' $helpitem['link'];
<                     
$j++;
<                 }
<             }
<             
$listed_mods[0]['help_page'] = $list_help;
<             
$xoopsTpl->assign('list_mods',$listed_mods);
<         }
<         unset (
$helplist);
<         if (( 
$module->getInfo('help') != '' ) && ($j == 0)) {
<             
$help['name'] = $module->getInfo('name');
<             
$help['link'] = 'help.php?mid=' $mid '&amp;' $module->getInfo('help');
<             
$xoopsTpl->append_by_ref'help'$help);
<         }
---
>         
$help $module->toArray();
>         
//$help['name'] = $module->getVar('dirname', 's');
>         $help['link'] = 'help.php?mid=' $mid '&amp;' $module->getInfo('help');
>         
$xoopsTpl->append_by_ref'help'$help );
88c72

---
>     
93c77
<         } else {
---
>         }else{
99a84
>         
101,108c86,96
<      } else {
<         if ( 
file_existsXOOPS_ROOT_PATH '/modules/' $module->getVar('dirname''e') . '/language/' $xoopsConfig['language'] . '/help/module_index.html' ) ) {
<             
$helpcontent $xoopsTpl->fetchXOOPS_ROOT_PATH '/modules/' $module->getVar('dirname''e') . '/language/' $xoopsConfig['language'] . '/help/module_index.html' );
<         } else {
<             
$helpcontent $module->getInfo('description');
<             
$helpcontent '<div id="non-modhelp">' $helpcontent '</div>';
<         }
<        
$xoopsTpl->assign('helpcontent'$helpcontent);
---
>         
>      } else { 
>             if ( 
file_existsXOOPS_ROOT_PATH '/modules/' $module->getVar('dirname''e') . '/language/' $xoopsConfig['language'] . '/help/module_index.html' ) ) {
>                     
$helpcontent $xoopsTpl->fetchXOOPS_ROOT_PATH '/modules/' $module->getVar('dirname''e') . '/language/' $xoopsConfig['language'] . '/help/module_index.html' );
>                 }else{
>                     
$helpcontent $module->getInfo('description');
>                     
$helpcontent '<div id="non-modhelp">' $helpcontent '</div>';
>                 } 
>                 
>            
$xoopsTpl->assign('helpcontent'$helpcontent);    
>            
110,111c98

// This section is called if we're in the general help area.
---
>      
114d100

119d104

137d121
<         // Special handling for the System module
139a124

141a127

143a130

144a132

154,155d141

<            
// Handling for all other modules
157,175c143,144
<             $helplist $module->getInfo('helpsection');
<             
$k=0;

<             
// Only build the list if one has been defined.
<             if (is_array($helplist)) {
<                 foreach (
$helplist as $helpitem) {
<                     if ( (
$helpitem['name'] != '') && ($helpitem['link'] != '') ) {
<                         
$list_help[$j]['name'] = $helpitem['name'];
<                         
$list_help[$j]['link'] = 'help.php?mid=' $module->getVar('mid''e') . '&amp;' $helpitem['link'];
<                         
$j++;
<                         
$k++;
<                     }
<                 }
<             }
<             unset(
$helplist);

<             
// If there is no help section ($k=0), and a lone help parameter has been defined.
<             if (( $module->getInfo('help') != '' ) && ($k == 0)) {
<                 
$list_help[$j]['name'] = $module->getInfo('name');
---
>             if ( 
$module->getInfo('help') != '' ) {
>                 
$list_help[$j]['name'] = $module->getVar('dirname''s');
179d147

190c158

---
>     
192,196c160,164
<         $helpcontent $xoopsTpl->fetchXOOPS_ROOT_PATH '/modules/system/language/' $xoopsConfig['language'] . '/help/help_center.html' );
<     } else {
<         
$helpcontent '<div id="non-modhelp">' _MD_CPANEL_HELPCENTER '</div>';
<     }

---
>             
$helpcontent $xoopsTpl->fetchXOOPS_ROOT_PATH '/modules/system/language/' $xoopsConfig['language'] . '/help/help_center.html' );
>         }else{
>             
$helpcontent '<div id="non-modhelp">' _MD_CPANEL_HELPCENTER '</div>';
>         }
>         
198a167
xoops_cp_footer();
200c169
xoops_cp_footer();
 
No newline at end of file
---
?>
 No newline at end of file


And here's the full file if anyone is interested:

<?php
/**
 * System help page
 *
 * You may not change or alter any portion of this comment or credits
 * of supporting developers from this source code or any supporting source code
 * which is considered copyrighted (c) material of the original comment or credit authors.
 * 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.
 *
 * @copyright   The XOOPS Project http://sourceforge.net/projects/xoops/
 * @license     GNU GPL 2 (http://www.gnu.org/licenses/old-licenses/gpl-2.0.html)
 * @author      Andricq Nicolas (AKA MusS)
 * @version     $Id: help.php 9320 2012-04-14 16:32:46Z beckmi $
 */

// Include header
include 'header.php';

$page system_CleanVars $_REQUEST'page''''string' );
$mid system_CleanVars $_REQUEST'mid'0'int' );

// Define main template
$xoopsOption['template_main'] = 'system_help.html';
xoops_cp_header();
// Define Stylesheet
$xoTheme->addStylesheetXOOPS_URL '/modules/system/css/admin.css' );
$xoTheme->addStylesheetXOOPS_URL '/modules/system/css/help.css' );
// Define Breadcrumb and tips
$xoBreadCrumb->addLink_AM_SYSTEM_HELP'help.php' );

// If $mid > 0, we're in a module's help section.
if ( $mid ) {
    
$module_handler =& xoops_gethandler('module');
    
$module $module_handler->get($mid);

    
$xoBreadCrumb->addLink$module->getVar('name'), 'help.php?mid=' $module->getVar('mid''s') );
    
$xoBreadCrumb->addLinksystem_adminVersion$page'name' ) );
    
$xoBreadCrumb->render();

    
// Special handling for the System Module
    
if ( $module->getVar('dirname''e') == 'system' ) {
        
xoops_load('xoopslists');
        
$admin_dir XOOPS_ROOT_PATH '/modules/system/admin';
        
$dirlist XoopsLists::getDirListAsArray($admin_dir);
        foreach(
$dirlist as $directory) {
            if ( 
file_exists$admin_dir '/' $directory '/xoops_version.php' ) ) {
                require 
$admin_dir '/' $directory '/xoops_version.php';
                if (
$modversion['help']) {
                    
$help['name'] = system_adminVersion$directory'name' );
                    
$help['link'] = 'help.php?mid=' $mid '&amp;' system_adminVersion$directory'help' );;
                    
$xoopsTpl->append_by_ref'help'$help );
                    unset(
$help);
                }
                unset(
$modversion);
            }
        }
        unset(
$dirlist);

    
// Handling for all other modules.
    
} else {
        
$list_help = array();
        
$listed_mods[0] = $module->toArray();
        
$helplist $module->getInfo('helpsection');
        
$j=0;
        if (
is_array($helplist)) {
            foreach (
$helplist as $helpitem) {
                if ( (
$helpitem['name'] != '') && ($helpitem['link'] != '') ) {
                    
$list_help[$j]['name'] = $helpitem['name'];
                    
$list_help[$j]['link'] = 'help.php?mid=' $mid '&amp;' $helpitem['link'];
                    
$j++;
                }
            }
            
$listed_mods[0]['help_page'] = $list_help;
            
$xoopsTpl->assign('list_mods',$listed_mods);
        }
        unset (
$helplist);
        if (( 
$module->getInfo('help') != '' ) && ($j == 0)) {
            
$help['name'] = $module->getInfo('name');
            
$help['link'] = 'help.php?mid=' $mid '&amp;' $module->getInfo('help');
            
$xoopsTpl->append_by_ref'help'$help);
        }
        unset(
$help);
    }

    
$xoopsTpl->assign'modname'$module->getVar('name') );

    if ( 
$page != '' ) {
        
// Call template
        
if ( file_existsXOOPS_ROOT_PATH '/modules/' $module->getVar('dirname''e') . '/language/' $xoopsConfig['language'] . '/help/' $page '.html' ) ) {
            
$helpcontent $xoopsTpl->fetchXOOPS_ROOT_PATH '/modules/' $module->getVar('dirname''e') . '/language/' $xoopsConfig['language'] . '/help/' $page '.html' );
        } else {
            if ( 
file_existsXOOPS_ROOT_PATH '/modules/' $module->getVar('dirname''e') . '/language/english/help/' $page '.html' ) ) {
                
$helpcontent $xoopsTpl->fetch(XOOPS_ROOT_PATH.'/modules/' $module->getVar('dirname''e') . '/language/english/help/' $page '.html');
            } else {
                
$xoopsTpl->assign('load_error'1);
            }
        }
        
$xoopsTpl->assign('helpcontent'$helpcontent);
     } else {
        if ( 
file_existsXOOPS_ROOT_PATH '/modules/' $module->getVar('dirname''e') . '/language/' $xoopsConfig['language'] . '/help/module_index.html' ) ) {
            
$helpcontent $xoopsTpl->fetchXOOPS_ROOT_PATH '/modules/' $module->getVar('dirname''e') . '/language/' $xoopsConfig['language'] . '/help/module_index.html' );
        } else {
            
$helpcontent $module->getInfo('description');
            
$helpcontent '<div id="non-modhelp">' $helpcontent '</div>';
        }
       
$xoopsTpl->assign('helpcontent'$helpcontent);
     }

// This section is called if we're in the general help area.
} else {
    
$xoBreadCrumb->render();

    
// Get Module Handler
    
$module_handler =& xoops_gethandler('module');
    
$criteria = new CriteriaCompo();
    
$criteria->setOrder('weight');

    
// Get all installed modules
    
$installed_mods $module_handler->getObjects$criteria );
    
$listed_mods = array();
    
$i 0;
    
$j 0;
    foreach ( 
$installed_mods as $module ) {
        
$list_help = array();
        
$listed_mods[$i] = $module->toArray();
        
$listed_mods[$i]['image']       = $module->getInfo('image');
        
$listed_mods[$i]['adminindex']  = $module->getInfo('adminindex');
        
$listed_mods[$i]['version']     = round$module->getVar('version') / 100);
        
$listed_mods[$i]['last_update'] = formatTimestamp$module->getVar('last_update'), 'm' );
        
$listed_mods[$i]['author']      = $module->getInfo('author');
        
$listed_mods[$i]['credits']     = $module->getInfo('credits');
        
$listed_mods[$i]['license']     = $module->getInfo('license');
        
$listed_mods[$i]['description'] = $module->getInfo('description');

        
// Special handling for the System module
        
if ( $module->getVar('dirname''e') == 'system' ) {
            
xoops_load('xoopslists');
            
$admin_dir XOOPS_ROOT_PATH '/modules/system/admin';
            
$dirlist XoopsLists::getDirListAsArray($admin_dir);
            foreach(
$dirlist as $directory) {
                if ( 
file_exists$admin_dir '/' $directory '/xoops_version.php' ) ) {
                    require 
$admin_dir '/' $directory '/xoops_version.php';
                    if (
$modversion['help']) {
                        
$list_help[$j]['name'] = system_adminVersion$directory'name' );
                        
$list_help[$j]['link'] = 'help.php?mid=' $module->getVar('mid''e') . '&amp;' system_adminVersion$directory'help' );
                    }
                    unset(
$modversion);
                    
$j++;
                }
            }
            unset(
$dirlist);

           
// Handling for all other modules
        
} else {
            
$helplist $module->getInfo('helpsection');
            
$k=0;

            
// Only build the list if one has been defined.
            
if (is_array($helplist)) {
                foreach (
$helplist as $helpitem) {
                    if ( (
$helpitem['name'] != '') && ($helpitem['link'] != '') ) {
                        
$list_help[$j]['name'] = $helpitem['name'];
                        
$list_help[$j]['link'] = 'help.php?mid=' $module->getVar('mid''e') . '&amp;' $helpitem['link'];
                        
$j++;
                        
$k++;
                    }
                }
            }
            unset(
$helplist);

            
// If there is no help section ($k=0), and a lone help parameter has been defined.
            
if (( $module->getInfo('help') != '' ) && ($k == 0)) {
                
$list_help[$j]['name'] = $module->getInfo('name');
                
$list_help[$j]['link'] = 'help.php?mid=' $module->getVar('mid''e') . '&amp;' $module->getInfo('help');
            }
        }

        
$listed_mods[$i]['help_page'] = $list_help;
        if ( 
$module->getInfo('help') == '' ) {
            unset(
$listed_mods[$i]);
        }
        unset(
$list_help);
        unset(
$module);
        
$i++;
        
$j++;
    }
    
$xoopsTpl->assign('list_mods'$listed_mods);

    if ( 
file_existsXOOPS_ROOT_PATH '/modules/system/language/' $xoopsConfig['language'] . '/help/help_center.html' ) ) {
        
$helpcontent $xoopsTpl->fetchXOOPS_ROOT_PATH '/modules/system/language/' $xoopsConfig['language'] . '/help/help_center.html' );
    } else {
        
$helpcontent '<div id="non-modhelp">' _MD_CPANEL_HELPCENTER '</div>';
    }

    
$xoopsTpl->assign('helpcontent'$helpcontent);
}

3
redheadedrod
Re: XOOPS Admin Help System Improvements

Due to the fact that 2.5.x has a feature lock in place the only thing that can be added are bug fixes and security fixes. This is something that will need to be addressed in 2.6.0 unless it can be added to just the admin class which isn't really core but is included with the core.

4
iunderwood
Re: XOOPS Admin Help System Improvements

I had not considered a feature lock in place for 2.5.x, though it is a largely sensible practice.

Looking at the differences in help.php between 2.5.6 and 2.6.0-alpha2, the implementation of the enhancement as I've described looks like it should carry over from one version to the other without too much difficulty.

However, I figured I could offer a solution to the problem instead of just whining about it. :)

5
Mamba
Re: XOOPS Admin Help System Improvements
  • 2013/6/16 16:34

  • Mamba

  • Moderator

  • Posts: 11366

  • Since: 2004/4/23


Quote:
However, I figured I could offer a solution to the problem instead of just whining about it. :)

And we would LOVE every user/developer to do just that: offer a suggestion and provide a code that could accomplish it!

Please log it as "feature request" on SourceForge, so we can keep track of it...
Support XOOPS => DONATE
Use 2.5.10 | Docs | Modules | Bugs

6
Mamba
Re: XOOPS Admin Help System Improvements
  • 2013/9/9 2:32

  • Mamba

  • Moderator

  • Posts: 11366

  • Since: 2004/4/23


Ian, once again thank you so much for your contribution.

This was an excellent idea, and it has been now committed to XOOPS 2.5.7 and thanks to Richard, also to XOOPS 2.6.0
Support XOOPS => DONATE
Use 2.5.10 | Docs | Modules | Bugs

Login

Who's Online

202 user(s) are online (114 user(s) are browsing Support Forums)


Members: 0


Guests: 202


more...

Donat-O-Meter

Stats
Goal: $100.00
Due Date: Mar 31
Gross Amount: $0.00
Net Balance: $0.00
Left to go: $100.00
Make donations with PayPal!

Latest GitHub Commits