CustomMOD - developer moding help

[Tobias]

Dear SD developers,

this solution is not an actual plugin, but a plugin modification development help which I see as a power- and usefull addition to any SD developer's repository when trying/willing to enhance an existing plugin with phrases, pluginsettings and/or MySQL table changes/additions.

Current version: 1.1.1 (August 23, 2006)

With just ONE line of code in the plugin's "Settings" file you may take care of applying DB upgrades/inserts for the Admin. Displaying a MOD footer to the "Settings" page for the Admin is just one more line, allowing to reapply or uninstall the MOD. CustomMOD is also safe to be cloned with your plugin (SD 2.3.5).

Desired (DB-) changes just need to be coded in a single file, set a version number, upload the file and open the plugin as admin. CustomMOD will detect it's version change and perform your added changes, voíla, you're done.

It's named "CustomMOD" because it's fairly easy for a developer to customize it specificially to his/her "modding" needs.
Note: please use the attached file ONLY as an example: it is a working copy as an example, which I'm using myself. Installation and customization instructions follow below.

What are good reasons and advantages using it?
Well, I originally developed it and use it within my custom modded version of my personal favorite plugin, the Download Manager, which is written by spib (James).
As quite understandably no original "install" script is allowed to be provided, I built CustomMOD as a self-contained framework for versioning all my "upgrades", mostly for SQL operations. Note that "versioning" here has nothing to do file related versioning.

Advantage:
Regardless of what different data I already put into my DB on either XAMPP or on the live webserver: by just maintaining a single file, CustomMOD allows me to add phrases, plugin settings or perform other codeable / DB-related commands (the idea is quite similar to the way plugin installations/upgrades are performed though I didn't look it up in detail).

The actual end-user - being the Subdreamer Admin - will automatically get a confirmation page upon first view of the plugin as admin (after having uploaded a newer CustomMOD file). With a single button click his plugin will be MOD'ed as the MOD developer intended it.
Note: CustomMOD itself does not require/perform any file operations to be functional.

So no more worries about in which database data was added (or changed), just add some lines of code for each new MOD version and let CustomMOD do the installation/upgrade for you.

It's versatile - setting the MOD version# and adding some upgrade codelines is mainly all there is to do - and one candy if odders: it includes additional error checking by using wrapper functions to ease tedious SQL operations.
Examples: adding columns to tables or adding/replacing phrases and plugin settings.
IF you no longer want to do this manually across multiple databases (within phpMyAdmin) - then CustomMOD is surely worth a try.

The mentioned custom-made wrapper functions will by default keep existing values (only optionally replace them) and provide means to add table columns by first checking for their existence. Therefore even repeatedly applying a CustomMOD version won't cause DB errors or corrupt data.

How about seeing it in action? :)
Below are example screens of CustomMOD within my mod'ed Download Manager when opening the plugin as Admin:
http://www.sqr-runner.de/subd/images/custommod1.gif
Assuming one clicked on the "Install MOD NOW" button, the MOD upgrade/installation is performed and an appropiate log is displayed:
http://www.sqr-runner.de/subd/images/custommod2.gif
Especially for the Admin an informational section may be displayed either on the plugin homepage or within the plugins "Display Settings" page (with just little code):
http://www.sqr-runner.de/subd/images/custommod3.gif
Program Notes
CustomMOD is just one file ("plugmod.php") which needs to be copied into the same directory in which your plugin resides. The code is more than 700 lines long, contains 14+ essential functions, is well structured and commented in all areas. This excludes any to-be-made upgrade-steps functions (attached file has examples in it for illustration of their use).

"Reapply MOD" and "Uninstall MOD" buttons, including action processing and -function, are already included (see "Settings" page above); it even does have a security prompt (if JavaScript is on).
The actual uninstall function(s) need to be brought to life with your own code to revert all previously applied changes - CustomMOD is just the workhorse to run it upon click of a button.

Usage details are mostly covered within the attached file, using my MOD upgrade steps for my Download Manager - MOD.

The total time effort for developing, testing and documenting is about 4+ workdays - and it is free for your private and business use, except selling or distribution unless expressedly permitted.

PHP version 4.1.0 or higher is required. Tested with Subdreamer 2.3.5 /PHP 5.1/MySQL 5.0.21/Apache 2 on Sun and XAMPP 1.5.0 - if that interests anybody.

Installation/Usage of CustomMOD

Installation is straight forward (v1.1.1 as of August 23, 2006):
Include your own customized CustomMOD file "plugmod.php" at the top of the plugin's "Settings" file, e.g. "pXX_settings.php" (with XX obviously the pluginid):

include($rootpath . 'plugins/pXX_pluginname/plugmod.php');

In case you added plugin settings: to make these visible to the admin page, just add appropiate "PrintPluginSettings(...)" commands to where the standard plugin settings are displayed (usually a function "DisplaySettings()" or similar). To show an additional button on the main plugin homepage, look for function "CustomMOD_Settings()" in the attached file for further instructions.
To display a special MOD footer section in the "Settings" for the admin (including Reapply and Uninstall buttons), just add this line to the e.g. "DisplaySettings" function of your plugin:

CustomMOD_SettingsAppendix(); // plugmod.php

That is all what is required for CustomMOD to be installed, so now continue to configuration and customization instructions.

CustomMOD Configuration

Notes: using CustomMOD requires for each uncloned plugin a separate, customized copy of the "plugmod.php" file. CustomMOD is also working when being cloned within SD.

The configuration section of CustomMOD is at the top of the file in which only 1 define is required to be set (all defines are described there, too).
These include details about the plugin to be mod'ed (it detects the running pluginid automatically), such as an option to check for a "minimum" version# of the plugin required to be supported by your CustomMOD.

In order to allow any end-user to contact the MOD author of the plugin, there are additional defines which specify e.g. a special forum thread for your MOD, probably a link to your SD user profile and the SD.org forum itself. I think that these should be included as a courtesy to the user of your MOD, but you could set these values empty of course.

Example of a configuration, in this case for the Download Manager, could look like this (only the 2nd value of each define is to be changed):

// MOST IMPORTANT: setting the actual CustomMOD version of this file:
// The first-ever release you'll publish should be "1.0.0"!
if(!defined("CustomMOD_VERSION"))
{
define("CustomMOD_VERSION", '1.0.0'); // format x.x.x always
}

// Minimum version of the plugin to be supported (any: "1.0.0"):
if(!defined("CustomMOD_PLUGINMINVERSION"))
{
define("CustomMOD_PLUGINMINVERSION", '1.4.2');
}


Customizing CustomMOD and Adding upgrade steps
The core upgrade functionality is function "CustomMOD_DoUpgrade". Within this, by using a switch command, all versions have a branch with the upgrade steps needed, each being a single function call (for "1.0.0", "1.0.1" etc.).

The file already includes functions for version "0.0.0" (which is "Installation" and HAS to be there) as well as dummy functions for versions "1.0.1" and "1.0.2" for further illustratations. I tend to add any new version function at the bottom of the file (in front of the special "action" section, though) to keep it sorted a little.

For the sake of conformity I'd also advise to name each upgrade "step" function (with code to apply changes from one version to the next) like this:

CustomMOD_versionXXX()
with XXX being 102 meaning version 1.0.2 etc.

Inside the function "CustomMOD_version100()" are pretty extensive comments on what I'm doing for the Download Manager (creating a new table, adding phrases and settings). Please note especially the use of the custom made SQL wrappers instead of hard-coding any INSERT statements (which would pretty much defeat the whole purpose of CustomMOD).

Finishing notes...
If you'll try out CustomMOD eventually, please be so kind to provide feedback on what I could have done better (especially if there are bugs :rolleyes: ). There are still some ideas for further development down the road and I'm open for suggestions and ideas.

Thanks to all great people here for providing help, assistance & professional insight when I needed it, you guys know who you are... and all others just enjoy SD! :)

Enjoy,
Tobias

------------------------------------------------------------------------------------
Edits:
2006-08-17: v1.0.1
- simplified installation
2006-08-18: v1.0.2
- "Reinstall" button added; new wrapper functions
2006-08-22: v1.1.0
- "Uninstall" button code added for illustration.
- Pluginid is now automatically detected (it's set during runtime by SD anyway), so there's one step less for configuration.
- Tested and works with the "Clone Plugin" process of SD 2.3.5
2006-08-23: v1.1.1
- bugfix for removing table columns (duplicate prefix)
- renamed "Reinstall" to "Reapply" as it was not clear enough
- added prompt to the "Reapply" button to avoid mistaken clicks
- file now includes example code for full uninstallation of the MOD
- some code cleanups

Mass Media Pro Plugin - Live Demo : Mass Media Pro (http://www.sddepot.com/mass_media/)
My SDDepot Blog (http://www.sddepot.com/community/blog/tobias/) - SDDepot - Skins and Plugins (http://www.sddepot.com/)

[Usurper]

This sounds pretty neat, and I can't believe nobody's replied to this.

[thomas]

I guess because it is a lot of work to do

[robert_p_skold]

It's not alot of work. However the example file is set with several mod upgrades. Perhaps a simpler example would yeild better results. It's really an ingenious idea, enginous modding. :D

One option to add would be replacing the actaul settings and main plugin file for the plugin itself. This way those files could be altered also.
This code manages all the db functions. ie all the changes, adding field and tables but, it does not accomidate changing of the main files them selves. If we used this to change the db and add settings to our plugin we would have to add those new settings to the plugins settings file in the approprite spot we wanted them displayed. If we then uninstalled the mod the settings file would still hold references to these settings and try to display them, resulting in errors or missing data. A work around for this would be to save the previous pxx_settings.php and pxx_main.php files. and replace the modded ones with the original ones when the mod is un-installed. It's good, real good but, still requires some options I feel. I would use it myself to provide custom solutions if it was as simple as clicking uninstall to revert to the previous un moded version.

Forgive me if I'm wrong. I only read the code and did not actually install it.

With kind regards,

Robert

[Tobias]

It's not alot of work. However the example file is set with several mod upgrades. Perhaps a simpler example would yeild better results. It's really an ingenious idea, enginous modding. :D


Thanks for the feedback, Robert.

From how I see it, the additional "plugmod.php" is to be an addition to existing plugin files, not a replacement. As such it's the developers' responsibility to advise the user to make a backup of existing files before uploading.
With SD there - architecturally speaking - is no other way to avoid replacing at least one file, i.e. either you adapt the install.php or the pxxx_settings.php file. Either way you have to plug it in somewhere.

Thomas' comment of being a lot of work is somewhat understandable: reading my comments and taking a closer look at the provided source - which has a lot of examples - is surely taking some minutes. Basically the "plugmod.php" works as a "install.php" but with more capabilities.
Once you add version-specific "upgrade" function, just include a similar "uninstall" function to revert these changes. Once you uninstall the CustomMOD itself, the original DB status should be the same as before.
Indeed, at this point there is manual action required to restore the original file. But that would be easy to put into the "uninstall" function as well.
Any plugin author here on SD.org should be having no problem getting that done. :D


One option to add would be replacing the actaul settings and main plugin file for the plugin itself. This way those files could be altered also.

Well, this could be done, but only works with specific target file versions. I rather provide a fully working version of a settings file rather than patching any "unknown" file version.


This code manages all the db functions. ie all the changes, adding field and tables but, it does not accomidate changing of the main files them selves. If we used this to change the db and add settings to our plugin we would have to add those new settings to the plugins settings file in the approprite spot we wanted them displayed.

As an example take the DLM MOD I published: you won't be able to patch the original file to accomodate the changes I put in it: many code changes/optimizations and additional functionality. Again, a full replacement of the settings file was my intention to write/use the CustomMOD.


I would use it myself to provide custom solutions if it was as simple as clicking uninstall to revert to the previous un moded version.

As shortly mentioned above, I see this to be the task of the "uploader" of the files (creating/restoring backed up files). :)

I'd be happy to chat about further enhancements to it and maybe find additional generic approaches, just let me know.

Cheers,
Tobias

[robert_p_skold]

With the light you shed it does make perfect sense. Back up files should always be made.

I do think a simpler demo file would result in feedback/use. It's a very good tool. :)

[crashnet47]

With the light you shed it does make perfect sense. Back up files should always be made.

I do think a simpler demo file would result in feedback/use. It's a very good tool. :)

Condev, I agree with robert here on this one. Would it be possible to provide an example of the plugmod.php for an initial release and then a few comments for adding to it for future releases? I think what's happening right now is everyone is overwhelmed by the file itself and not to sure what to delete without messing it up.

Thanks Condev...this is a fantastic tool. :)

[crashnet47]

I'm not sure if anyone else has used Condev's CustomMOD, but I wanted to mention that I have successfully used his mod (with a minor tweak from Condev for a tiny error I didn't catch :) ) to provide a modification for the Image Gallery.

Awesome tool...thanks for making it Condev! :D

[robert_p_skold]

Cool File. I used it here (http://www.subdreamermods.com/forum/showthread.php?p=4079#post4079).

[abcohen]

bump bump bump