Admin Page Registration for 3rd Party Modules

Hi,

How exactly are third party modules supposed to add pages to the Admin, now that support for boxes/extra_boxes has been dropped?

Obviously a call to zen_register_admin_page() can be made but there is no documentation with this new version of Zen Cart about when the appropriate time would be to make that call... which seems like a pretty major omission for the docs! :)

At the minute I'm thinking of simply adding a file which gets loaded by one of the existing auto-loading directories.

But this file would simply call the above function to register a page that can then be accessed by the admin user through the admin menu.

This seems rather wasteful of system resources as this file will autoload every time an admin page is opened.

The solution to that is then to unlink() the auto-loading file once the module's page has been accessed through the menu for the first time, but none of this is a "desirable" way to work.

Any information for a confused third party developer would be greatly received.

Thanks!

All the best..

Conor

Hi Conor

Your mods generally (possibly always) undertake the database installation programmatically. Most mods don't have that level of sophistication and would use SQL inserts such as those discussed in this thread.

For modules such as yours a call to zen_register_admin_page() would be the right way to go. The full call is:

zen_register_admin_page($page_key, $language_key, $main_page, $page_params, $menu_key, $display_on_menu, $sort_order);

where:

• page_key is a unique text id
• language _key is the name of the define for the page name that would previous have been used in the box files (for compatibility with existing language packs)
• main_page is the define starting FILENAME_ used in the box file and code to direct to the admin page
• page_params are whatever parameters are needed for the page (generally relevant only to configuration and modules pages
• menu_key is a foreign key for the admin_menus table
• display_on_menu is a char with value "Y" or "N" depending on whether it's a page visible on the admin menu, or a subpage called by another page
• sort_order is a numeric value indicating how high up the menu the entry would appear, a high value sinks it down

The current release is a beta, and there will be more documentation on this feature following along before the formal release.

I'm suspecting that part of your concern is the chicken and egg problem of not being able to access the page from which you install until after you've installed.

That's a legitimate issue, and one of several where PCI requirements frustrate my developer's sensibilities too.

One possibility might be a standalone installer, i.e. a file uploaded with the mod, to which the admin browses to trigger execution of the SQL, and is then deleted (possibly by the script itself). Not as good as what you do currently, and I'm not sure what the PCI guys would make of it, but alas admin access to pages not yet registered has gone.

Hi,

You're answering lots and lots of posts recently! I hope you're finding time for real life too! :)

kuroi:

I'm suspecting that part of your concern is the chicken and egg problem of not being able to access the page from which you install until after you've installed.

Right you are!

kuroi:

That's a legitimate issue, and one of several where PCI requirements frustrate my developer's sensibilities too.

Anyone who's talked to me about it knows what I think of PCI compliance.. reasonable concept, organised badly.. bureaucratic rubbish.. :) Eventually software will be good but when, oh when, will we all learn? ;-)

kuroi:

One possibility might be a standalone installer, i.e. a file uploaded with the mod, to which the admin browses to trigger execution of the SQL, and is then deleted (possibly by the script itself).

That's essentially what I was saying in my initial post that I see as the only option. A script that simply creates the page links, and code which will delete this wasteful script when the "actual" admin pages are accessed for the first time.

At that point, 1.5.0 would act like previous versions and the auto-installation and upgrade/config checks recent Ceon software employs would then run as normal.

kuroi:

Not as good as what you do currently, and I'm not sure what the PCI guys would make of it, but alas admin access to pages not yet registered has gone.

The "PCI guys" don't appear to have too many brain cells to scrub together so I wouldn't want to involve them and harm their poor heads any further. Any solution which avoids any need to involve them is definitely desired.

Oh well, looks like my initial idea is the only idea then! I believe in making things easy for users when they should be, especially when there are no security repercussions!

Thanks for taking the time to reply. Now go enjoy some of the weekend, life is short! :)

All the best...

Conor

Hi,

conor:

At the minute I'm thinking of simply adding a file which gets loaded by one of the existing auto-loading directories.

But this file would simply call the above function to register a page that can then be accessed by the admin user through the admin menu.

This seems rather wasteful of system resources as this file will autoload every time an admin page is opened.

The solution to that is then to unlink() the auto-loading file once the module's page has been accessed through the menu for the first time, but none of this is a "desirable" way to work.

Given that this seemed ot be the only way to do things, this is how I've implemented this in Ceon URI Mapping v4.0.3.

It works perfectly well but is a strange way to have had to make things work.

Just letting know in case any other developer wants to add a link to the Zen Cart admin...

How to add a menu item to the Zen Cart admin, when users are only copying files across:

Simply create a file that goes in:

admin/includes/auto_loaders

Sample content (minus obligatory comments which should already have been added for good coding standards:)

if (!defined('IS_ADMIN_FLAG')) {
    die('Illegal Access');
} 

$autoLoadConfig[199][] = array(
    'autoType' => 'init_script',
    'loadFile' => 'init_ceon_uri_mapping_config.php'
    );
```Then create a file in 

admin/includes/init_includes

Sample content:

```php
if (!defined('IS_ADMIN_FLAG')) {
    die('Illegal Access');
}

if (function_exists('zen_register_admin_page')) {
    if (!zen_page_key_exists('ceon_uri_mapping_config')) {
        // Add the link to the Ceon URI Mapping Config Utility
        zen_register_admin_page('ceon_uri_mapping_config', 'BOX_CEON_URI_MAPPING',
            'FILENAME_CEON_URI_MAPPING_CONFIG', '', 'modules', 'Y', 40);
    }
}

// Now that the menu item has been created/registered, can stop the wasteful process of having
// this script run again by removing it from the auto-loader array
@unlink(DIR_FS_ADMIN . DIR_WS_INCLUDES . 'auto_loaders/config.ceon_uri_mapping_config.php');

Obviously adjust as desired for your own software!

All the best...

Conor
ceon

I was just searching for a solution to this exact problem. Thanks so much for the detailed instructions!

As an alternative, one could just as easily put the suggested init_includes code into a file in the /admin/includes/extra_functions/ folder, and skip the auto_loaders file.

Hi,

DrByte:

As an alternative, one could just as easily put the suggested init_includes code into a file in the /admin/includes/extra_functions/ folder, and skip the auto_loaders file.

I tried that but it doesn't work as the registration function doesn't exist at the time the file in the extra_functions folder loads.

My solution as outlined above appears to be the best way to have a module add options to the admin menus upon initial installation of the module.

Hope that helps other developers here!

All the best...

Conor
ceon

That'll be fixed in the next 1.5 update (changed the breakpoint for admin_access function file being loaded from 70 to 35).

DrByte:

As an alternative, one could just as easily put the suggested init_includes code into a file in the /admin/includes/extra_functions/ folder, and skip the auto_loaders file.
conor:

I tried that but it doesn't work as the registration function doesn't exist at the time the file in the extra_functions folder loads.
Fixed in latest beta update: http://www.zen-cart.com/forum/showthread.php?p=1065366#post1065366

Is there any documentation yet on how to properly add 3-party plug-ins?

I'd like to be able to add a plug-in to the tools menu, and then an option under the configuration menu for settings.

I have used Conor's method (above) to get the main plug-in script to show under the tools menu, but am scratching my head on how to get the configuration settings page to show.

I can do it manually with the Admin Page Registration with these values:

Page Key: Easy Populate 4
Page Name: BOX_TOOLS_EASYPOPULATE_4
Page Filename: FILENAME_CONFIGURATION
Page Parameters: gID=32 (I look this up in phpMyAdmin)
Menu: Configuration
display: checked
sort order: 99

Any advice on how to do this automatically would be great.
Thanks!

PS: Hey Dr. Byte! Any chance you could update your Backup MYSQL Plugin to be 1.5 compatible?

Hi Chadd,

Hope all is well!

chadderuski:

how to get the configuration settings page to show.

I can do it manually with the Admin Page Registration with these values:

Page Key: Easy Populate 4
Page Name: BOX_TOOLS_EASYPOPULATE_4
Page Filename: FILENAME_CONFIGURATION
Page Parameters: gID=32 (I look this up in phpMyAdmin)
Menu: Configuration
display: checked
sort order: 99

Any advice on how to do this automatically would be great.

In Ceon URI Mapping I implement the following code:

// Make sure configuration group can be displayed in admin menu
                if (function_exists('zen_register_admin_page')) {
                        if (!zen_page_key_exists('ceon_uri_mapping_config_group')) {
                                // Add the link to the Ceon URI Mapping Config Utility to the admin menu
                                zen_register_admin_page('ceon_uri_mapping_config_group',
                                        'BOX_CEON_URI_MAPPING_CONFIG_GROUP', 'FILENAME_CONFIGURATION',
                                        'gID=' . $configuration_group_id, 'configuration', 'Y',
                                        $configuration_group_id);
                                
                                $messageStack->add('Configuration group added to admin menu.', 'success');
                        }
                }
```The value for the $configuration_group_id variable is either generated or looked up right before this call.

Adjusting that for your settings would result in the following code:

```php
// Make sure configuration group can be displayed in admin menu
                if (function_exists('zen_register_admin_page')) {
                        if (!zen_page_key_exists('easy_populate_4')) {
                                // Add the link to the Easy Populate 4 to the admin menu
                                zen_register_admin_page('easy_populate_4',
                                        'BOX_TOOLS_EASYPOPULATE_4', 'FILENAME_CONFIGURATION',
                                        'gID=' . $configuration_group_id, 'configuration', 'Y',
                                        $configuration_group_id);
                                
                                $messageStack->add('Configuration group added to admin menu.', 'success');
                        }
                }
```You'd have to look up the configuration group beforehand and the messageStack notification is obviously optional but I've left it in here as I think that kind of feedback's nice for the user.

Example code for looking up configuration group ID:

```php
$check_config_group_exists_sql = "
                        SELECT
                                configuration_group_id
                        FROM
                                " . TABLE_CONFIGURATION_GROUP . "
                        WHERE
                                configuration_group_title = 'Ceon URI Mapping (SEO)';";
                
                $check_config_group_exists_result = $db->Execute($check_config_group_exists_sql);
                
                if (!$check_config_group_exists_result->EOF) {
                        $configuration_group_id =
                                $check_config_group_exists_result->fields['configuration_group_id'];
                }
```Hope that helps!

All the best...

Conor
[ceon](http://dev.ceon.net)

It's not entirely clear what you're wanting here. If it's a way to take older add-ons that know nothing about the new security features and somehow have then automatically integrated with it, then that's not going to happen.

Responsibility for integrating add-ons into the Admin rests with the add-on's author. Most will probably add a line to the SQL executed in sql patch facility. A smaller number, such as Conor, may offer automated php-based installation using the new page registration function. The specific steps needed should be explained by each mod's installation instructions.

Older, unsupported mods present a different problem. For this the page registration page has been supplied. Explanation as to how to use it is displayed on the page itself and it seem that you've done a fine job of using it. But this is just a fallback, and you will still need to ensure that the older mod's you're using don't reintroduce the sorts of vulnerabilities that the Zen Cart have gone to great lengths to close for version 1.5.

Hi Conor!

Thanks for the additional info and code! I'll dig into it and we'll see how successful I am at implementing it! I'm sure other developers will also find this useful.

Hey Kuroi! --->> BTW, really like the Avatar! Very Cool! Is that new?

No, I'm not just trying to patch 'incompatible' code to work with 1.5. I have been working on an update to the Easy Populate mod for some time. It currently self detects if the configuration variables are installed and allows the user to install from within the script. You can also uninstall from within the script rather than running sql patches. Of course, this may change, and I still need to review the code to ensure it meets all the new requirements. But at this point I want to ensure the mod is easy to install for myself and others.

I have looked, but have not found any documentation on 3rd-party integration of modules. If there is, please link...

A smaller number, such as Conor, may offer automated php-based installation using the new page registration function.

From Conor's work and Dr. Byte's statement above, I figured automated installation with the page registration function would become more the standard than just running sql patches. As it was stated in an earlier thread, this function may be removed from the admin, so I assume it would only then be available programmatically.

I'm sure the whole issue of 3rd party mods will bloom into more than just "compatible" (i.e. it works) vs being verified as secure and following all the proper guidelines for just that. Much excitement still ahead! :p

-cj

From what I can gather, the ability in v1.5, to install a 3rd party add-on through an SQL patch AND have the mod display in Admin>Configuration will be addressed in the final release.

Is there a way to 'simply' edit an existing .sql file to do this in the interim? I'm developing a 1.50 RC2 site and cannot get mods to show in Admin>Config..., although can navigate to them by gID

simon1066:

From what I can gather, the ability in v1.5, to install a 3rd party add-on through an SQL patch AND have the mod display in Admin>Configuration will be addressed in the final release.

Is there a way to 'simply' edit an existing .sql file to do this in the interim? I'm developing a 1.50 RC2 site and cannot get mods to show in Admin>Config..., although can navigate to them by gID

I have just used DrByte's http://www.zen-cart.com/forum/showpost.php?p=1070478&postcount=10 and conor's init_includes example on my update to Monthly Sales Tax Summary v1.4 and it works fine.

Skip

Thanks, Skip. I'll check this out

Cheers

Simon

With Skip's post having prompted me to re-read the previous posts in this thread, I now understand a bit more. I'll have to delve a bit deeper before installing SQL patches of older mods that might not be as secure as v1.50 requires.

Like many, I guess, this seems a bit of a round about way to install some database changes but those are the hoops PCI makes you jump through :-)

What about having a separate directory for the install files that was cleaned out after every run. What I am thinking of is a almost clone of the init_includes system but at the end of the process the directory is always cleared of files. So that any file placed in that folder would only be executed the one time.

(Or perhaps it would be better to have a directory for install files. Then create an 'available installs' admin page that scanned that folder and presented any available files along with an 'install' button. Then the user could choose to install and the file would be deleted at the end of the process. All the module developer would need to do is put a file in the install directory and it would appear in the 'Available Installs' page. )

I just think that it would at least standardise the installation process. Anyone have any thoughts?

Security risks in having a directory that contains files that are executed in this way?

Of course, once I am thinking about that I start thinking that:
-- a module's files should be uploaded in a separate directory at root level, say /module-image-handler/
-- a file should be uploaded to the new init_install directory when it is run it moves the files from /module-image-handler/ to their correct positions copying any overwritten files back to /module-image-handler/overridden/ using a nice set of functions supplied by the core.
-- it then runs any sql statements
-- it then zips /module-image-handler/ as a recoverable record of the installation
-- it then writes data to a new table in the database with install details (and perhaps details of all over-written files so that in future a new mod could check them for compatibility)

Of course, if there are big changes planned for Zen 2.0 then this is not worth the time. However it might be worth creating a init_install functionality to step around the chicken and egg situation that exists at the moment?

As I say just thoughts.

niccol:

Of course, if there are big changes planned for Zen 2.0 then this is not worth the time.
Indeed there are big changes planned - a complete plugin architecture is in the works.
But that's an entirely separate topic.