vb.org Archive - Hack writers: the "Replace with"....

vb.org Archive (https://vborg.vbsupport.ru/index.php)

- General Articles (https://vborg.vbsupport.ru/forumdisplay.php?f=189)

- - Hack writers: the "Replace with".... (https://vborg.vbsupport.ru/showthread.php?t=68028)

Hack writers: the "Replace with"....

Id like to recommend novice as well as more experienced hack writers to avoid whenever possible to have the "replace with" instruction in your readme.
For instance, I am as we speak installing a mod where the author wants me to replace the entire "$globaltemplates" array with something, and the only real modification made is ONE line added to the end.
While this might be useful on an unhacked board, this would not be good on mine since I already got about 4 hacks installed interfering with said variable and its replace instruction.

Of course, most of you experienced hack installers or writerts might say "Bah, any dumass is clever enough to pick out the important bit and add it if theres conflicts!".
Remember, we have newbies among us. Hell we all were newbies once.

So my small tip is:
Unless your hack modifies large parts of ONE single bit of coding (example: the $posts query for the RPG hack), then please use "Add below" or "Add above" :)

Well that was my worthless little tip ;)

we have a known protocol here to make the less changes to the codes as possible, and some are not really into it, and they provide install instructions that give some headaches to newbies... this is right.

you have to ask each coder to change the writing of their codes, because not everyone is able to handle big projects, many are with their first code and are not really informed of such requests from users like you...

;)

Well, quite often you just add a variable to an array, a query, etc.
But especially for newbies, it might be difficult if the instruction says "add xyz to this query: foobar"
Therefore it is easier to give the original line and instruct the user to replace it with a new one, even if this "new line" just addas a variable.

Just my 0,02

<pre-flame preface> :)
This is meant in a good spirit, so no real flames back please.
< />

I have been at this software development thing since 1976. I won't bore you with war stories of the old days though. -g I have dealt with supporting user-extensibility issues on a number of systems, some far larger than vBulletin. Nuf' said.

Professionally speaking, the hack installation conventions we use, well, they suck. One can so easily end up with so much tape, wire, and safety-pins holding the thing together (after installed a bunch of hacks I mean), that the thought of upgrading to a new release sends chills up the admin spine.

Bottom line: Hacks should be supported by an SDK so that, as far as possible, they can survive an upgrade of the base vBulletin. For some types of hacks, this would not be possible, but for most it would be possible. This would require a hack support module in vBulletin, but once such a module were installed, supporting the installation and maintenance of hacks would be much easier.

ps: Even the name hack is wrong imho. The usage of this word implies "not professional" or "not a proper modification".

pps: HTL, although a very fine piece of work, is not the answer.

Cheers, CarCdr

@ KirbyDE:
I see your point, but the way I like to do it is:
"find:
replace [the middle entry of an array]
with [the middle entry of an array + the new stuff]"
(since the order of the array items is often not important)

@Car:
I think this is a great idea and I would really really like to see such a feature included in vB4 (XD) ;)

To give you a flavour of what I am proposing, take a look at this code. Note that it is not meant to suggest syntax per-se, but the flavour of what is being proposed. Nor is it meant to be complete or proper PHP. It is a prototype.

The key is that this file is read by itself, before the inclusion of 'global.php', either though $PHP_SELF or passing the file name to the include though a global.

The use of color here is gratuitous, meant only to highlight VBMOD usage.

Code:

<?php



/**VBMOD:



A special comment that begins with "VBMOD:". When this file is read by the

the mod-support SDK (read by ourselves below actually), it will look in

this comment for information.



The information in this comment is very similar to that supported by HTL.

The principal difference is that all information required to install,

administrate (options, phrases, etc), and run the mod are contained in

a single source file. One simply places this file in the home directory

and we are done.



@title: Index With Options



@status: alpha



@description:

 This mod replaces index.php with a fancier display with more options.



 The user-visible options are:



 (1) Display forums with new posts before forums with no new posts.

 (2) Suppress display of forum descriptions, making the individual forums

 take far less vertical space so that you can see more without scrolling.



 Both options are remembered using cookies.



@version:         1.1



@compatibility:   3.0.0, 3.0.1



@page_options:    navbar, forumjump



@default_action:  list



@usergroups_disallowed:   12,13

@users_disallowed:        131,192

@user_requires:           registration,post_minimum=10



@phrases, group=iwo_phrases:

iwo_display_new_first,     text=Display new forums first

iwo_display_descriptions,  text=Display forum descriptions



@admin_options:

iwo_controls_top,          title=Controls at top,

                           type=yesno,

                           default=1

                           help=Select this option to place the display controls at the top of the page.



@templates:

iwo_short_forumbit,        text=@@Text of template

here, in php-heredoc-like syntax.

@@



*/



// ######################## SET PHP ENVIRONMENT ###########################

error_reporting(E_ALL & ~E_NOTICE);

define('NO_REGISTER_GLOBALS', 1);

define('THIS_SCRIPT', 'iwo_index');



// vB SDK and mod support

require_once('./VBMOD_support.php');



// #################### PRE-CACHE TEMPLATES AND DATA ######################

$phrasegroups = array( blah, blah );

...etc...



// ########################## REQUIRE BACK-END ############################

VBMOD_pre_global();     //read this file and setup variables

require_once('./global.php');

VBMOD_post_global();        // check user access and finish variables



...

some code

...



// Here is a reference to a phrase. This would have been set

// by VBMOD if there is not a custom one installed by

// the administrator using our admin install option. There

// is no need to install anything if the defaults are OK.

$tmp = $vbphrase['iwo_display_new_first'];



// Here is a reference to an option. This would have been

// set by VBMOD if there is not a custom value

// installed by the administrator using our admin install

// option.

if ($vboptions['iwo_controls_top']) {

     some code here;

}



...

and so on

...



// Here is a convenience function made available to mod's.

// This particular example, VBMOD_eval_template, makes code more readable,

// offers some protection against changes to vB release, and has the small

// added advantage of making variables visible to Xref tools like PHPXref.

//

// This template is either available in its default form, which appeared

// earlier in this file, or it is a custom installed version. We just write

// the code as if it is installed.

$collect_bits .= VBMOD_eval_template('iwo_short_forumbit');



...

and so on, until:

...



VBMOD_finish_page();      // navbar, forumjump, etc.

print_output( ... );





// ADMINISTRATION:

//

// And here is something in pretty well every mod...

//

else if ($do === 'VBMOD_admin') {



     - check for administrator privs, change into admin dir,

       fire-up menu to allow for any of:

         (1) install/uninstall one or more options (only if the

             administrator wants to customize the defaults)

         (2) ditto phrases and templates

         (3) run the AdminCP for this mod's options

}



?>

personally whatever coder did instruct u to replace the $globaltemplates variable, i find not very professional since that variable should be updated anytime a template is added to that file>_> but i do understand your concern about the mishaps and differences everyone has in their files. i will try to avoid such instructions in the future;)

Yep I have to agree with CarCdr, documentation in files can make life so much easier. When working on classes now, I document every method with the same syntax. Then I can just use another PHP class, to open the files, extract the documentation, and store the developers API ready for output if I have the necessity too.

This is basically a stolen idea from "Javadoc" or something along those lines I believe :)

Dean,

While there is some documentation that could be extracted from the script header, this is not like JavaDoc. This is not a documentation system. It is not meant to document the mod, or like JavaDoc and systems that preceded it, to document functions, variables, etc. The only thing in common with JavaDoc was my choice of '@'.

The main thrust of the system is functionality, not documentation. What it is meant to do:

Allow of single source install. Put the file in the main forum directory -- that's it.
The single source supports:
1. The script itself, if the mod is indeed a script that is run by users, such as forum/display_stats.php. (Some mod's do not actually run a script -- they just change something about vB or install new options/templates, etc.)
2. Common page operations like building a navbar and forum_jump. In this simple example, they were listed in "@page_options". Fact is, why have every mod that needs it include code for such things. If vBulletin changes anything regarding navbar or forum_jump, all the mod's would have to be fixed.
3. Optional install. The admin would install only if the default options, phrases, and templates required changing. Install would support installation of only those pieces that the admin wants to change. Without the install, the defaults delivered in the single file are used.
4. SDK functionality and independence through the "VBMOD_" functions. On a new release of vBulletin, the SDK would be checked for incompatibilities and updated. Site the world over would simply upload the new "VBMOD" package before the install the new vBulletin. This is much better than having to update all their mod's. (Sure, they may still have some mod's that require updating, but by using an SDK, they are better protected from vBulletin changes.)

For all mod's that require a new user script, phrases ($vbphrase), admin-side options ($vboptions), and mod-specific templates, the admin would not have anything to do other than copy the file to the forum home directory.

The more difficult aspects not yet supported in what I am proposing, are supporting changes to vB-delivered PHP code or vb-delivered templates, but we'll get to that discussion later. :) Let's start this discussion with what is more easily done.

Cheers

ps: For anyone worried about the script having to read the script header (the big comment at teh beginning) everytime it is run, it would be easy enough to use a cache and only read the file only if it has been modified.

X vBulletin 3.8.12 by vBS Debug Information
Template Usage: (1)ad_footer_end (1)ad_footer_start (1)ad_header_end (1)ad_header_logo (1)ad_navbar_below (1)bbcode_code_printable (1)footer (1)gobutton (1)header (1)headinclude (6)option (1)pagenav (1)pagenav_curpage (1)pagenav_pagelink (1)post_thanks_navbar_search (1)printthread (10)printthreadbit (1)spacer_close (1)spacer_open Phrase Groups Available: global postbit showthread	Included Files: ./printthread.php ./global.php ./includes/init.php ./includes/class_core.php ./includes/config.php ./includes/functions.php ./includes/class_hook.php ./includes/modsystem_functions.php ./includes/class_bbcode_alt.php ./includes/class_bbcode.php ./includes/functions_bigthree.php Hooks Called: init_startup init_startup_session_setup_start init_startup_session_setup_complete cache_permissions fetch_threadinfo_query fetch_threadinfo fetch_foruminfo style_fetch cache_templates global_start parse_templates global_setup_complete printthread_start pagenav_page pagenav_complete bbcode_fetch_tags bbcode_create bbcode_parse_start bbcode_parse_complete_precache bbcode_parse_complete printthread_post printthread_complete
Messages:

Phrase Groups Available:

X vBulletin 3.8.12 by vBS Debug Information
Page Generation 0.01295 seconds Memory Usage 1,780KB Queries Executed 10 (?)
More Information
Template Usage: (1)ad_footer_end (1)ad_footer_start (1)ad_header_end (1)ad_header_logo (1)ad_navbar_below (1)bbcode_code_printable (1)footer (1)gobutton (1)header (1)headinclude (6)option (1)pagenav (1)pagenav_curpage (1)pagenav_pagelink (1)post_thanks_navbar_search (1)printthread (10)printthreadbit (1)spacer_close (1)spacer_open Phrase Groups Available: global postbit showthread	Included Files: ./printthread.php ./global.php ./includes/init.php ./includes/class_core.php ./includes/config.php ./includes/functions.php ./includes/class_hook.php ./includes/modsystem_functions.php ./includes/class_bbcode_alt.php ./includes/class_bbcode.php ./includes/functions_bigthree.php Hooks Called: init_startup init_startup_session_setup_start init_startup_session_setup_complete cache_permissions fetch_threadinfo_query fetch_threadinfo fetch_foruminfo style_fetch cache_templates global_start parse_templates global_setup_complete printthread_start pagenav_page pagenav_complete bbcode_fetch_tags bbcode_create bbcode_parse_start bbcode_parse_complete_precache bbcode_parse_complete printthread_post printthread_complete
Messages: