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

[Revan]

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 ;)

[nexialys]

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...

;)

[Andreas]

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 €

[CarCdr]

<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

[Revan]

@ 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) ;)

[CarCdr]

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.
<?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
}

?>

[AN-net]

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;)

[Dean C]

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 :)

[CarCdr]

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:
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.)
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.
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.
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.

[CarCdr]

Related discussion:
https://vborg.vbsupport.ru/showthread.php?p=541980#post541980

[dwh]

Hear Hear! I've been silently thinking the same thing for a long time.I love vbulletin, but their thought on making life easy for the hackersis, well, let's say insufficient. I don't want to criticize thembecause they do so much right, but vb3 was even worse than vb2. The bitsystem made it less extendable.

[Zachery]

Hear Hear! I've been silently thinking the same thing for a long time.I love vbulletin, but their thought on making life easy for the hackersis, well, let's say insufficient. I don't want to criticize thembecause they do so much right, but vb3 was even worse than vb2. The bitsystem made it less extendable.
why are we didding up age old threads

[dwh]

1. You are determining age by date on the thread, which I didn't even look at. It was on page 2 of Modification Hints and Tips which isn't that old in my book.
2. I only just read it now.
3. Why not? Is the thread no longer relevant?

[Zachery]

I suppose it still is, however the HTL had its day and was never overly in favor, a new system the HIS has come into exsistance and is not widely used but is gaining favor.

[dwh]

I didn't know that. I probably wouldn't use any external system,neither as a hack writer or one who uses it. Why invest in somethingthat won't be integrated into vbulletin? This idea would only havevalidity imho if it was built into vbulletin. Or at the very leastactively acknowledged by the developers and built around, along withsanction and cooperation by vb.org. For example, specs by/sanctioned byvb.org, and all hacks to be accepted need to be compatible.

[faqcorner]

you know, just tell them to put it in comments would be better too :)