The FIND command is the most import of any command. By properly formatting FINDs your MOD will have a better chance of installing even if many MODs have already been installed.
The least you need to know:
- Keep FINDs limited to their minimum uniqueness
- Choose text that is likely to not be modified by other MODs
- In lang files, search only for the $lang array keys and exclude the values
- FIND once and operate many
- FINDs are whitespace indifferent
Uniqueness
Golden Rule #1: Keep FINDs limited to their minimum uniqueness. Rather than quoting entire blocks of core phpBB code letter for letter, isolate just those parts that make the line(s) unique. The more MODs that have been previously installed, the less likely you are to FIND an exact match for what you are seeking. Limiting to just the minimum uniqueness greatly increases the odds that you will have a successful FIND.
Instead of having a monstrousity like this....
Code: Select all
#
#-----[ FIND ]------------------------------------------
#
$sql = "UPDATE " . USERS_TABLE . "
SET " . $username_sql . $passwd_sql . "user_email = '" . str_replace("\'", "''", $email) ."', user_icq = '" . str_replace("\'", "''", $icq) . "', user_website = '" . str_replace("\'", "''", $website) . "', user_occ = '" . str_replace("\'", "''", $occupation) . "', user_from = '" . str_replace("\'", "''", $location) . "', user_interests = '" . str_replace("\'", "''", $interests) . "', user_sig = '" . str_replace("\'", "''", $signature) . "', user_sig_bbcode_uid = '$signature_bbcode_uid', user_viewemail = $viewemail, user_aim = '" . str_replace("\'", "''", str_replace(' ', '+', $aim)) . "', user_yim = '" . str_replace("\'", "''", $yim) . "', user_msnm = '" . str_replace("\'", "''", $msn) . "', user_attachsig = $attachsig, user_allowsmile = $allowsmilies, user_allowhtml = $allowhtml, user_allowbbcode = $allowbbcode, user_allow_viewonline = $allowviewonline, user_notify = $notifyreply, user_notify_pm = $notifypm, user_popup_pm = $popuppm, user_timezone = $user_timezone, user_dateformat = '" . str_replace("\'", "''", $user_dateformat) . "', user_lang = '" . str_replace("\'", "''", $user_lang) . "', user_style = $user_style, user_active = $user_active, user_actkey = '" . str_replace("\'", "''", $user_actkey) . "'" . $avatar_sql . "
WHERE user_id = $user_id";
Code: Select all
#
#-----[ FIND ]------------------------------------------
#
# NOTE: the origial text is like:
# $sql = "UPDATE " . USERS_TABLE . "
# SET " . $username_sql ... [ follow by much more ]
# WHERE user_id = $user_id";
#
$sql = "UPDATE " . USERS_TABLE
user_sig_bbcode_uid = '$signature_bbcode_uid',
WHERE
Other Hints
There are a few things to optimize your FINDs. Choose text that is likely to not be modified by other MODs. As many lines as needed may appear in the FIND block. Any length of any portion of a line may be used, and it is not necessary to use the beginning of the line. When dealing with TPL files it is a good idea to key on the template variables (ie. {L_TITLE}) as these are less likely to be modified and are also likely to appear in non-subSilver TPL files.
A FIND must proceed an IN-LINE FIND (not immedaiately though), however it is not necessary that the IN-LINE FIND fragment be present in the FIND. The point is that the FIND need only focus on the unique elements that distinguish this block of lines from others and that IN-LINE FIND can be less specific, needing only to focus on what distingushes the fragment on this line.
Dealing with Languages
When performing FINDs in lang_ files, keep in mind that ALL languages are going to be updated. Although values will change from language to language the variable names stay the same in ALL language packs. Therefore search only for the $lang array keys like "$lang['Forum']" and not "$lang['Forum'] = 'Forum';". It is very unwise to rely on comment (such as // That's all folks! ) in language files as often the comments are also translated into other languages.
There is an exception to this though. The two FAQ files (lang_faq.php and lang_bbcode.php) have no $lang keys unlike the other lang files. Therefore while FINDs work fine in English (or the primary language setting), they have no chance of working in other lang files. Therefore EM will try to commensate by performing all ADD commands just before the closing ?> of the file. It will be impossible to act on any REPLACE or IN-LINE commands.
Order and FINDs
Much of how order plays a role in FINDs is covered at length in the Order! Order! section. I'll recap the highlights here though. It is intended that you will process a file sequentially and not try to FIND some lines previous to ones already found. FIND something once and only once, and perform as many commands on the FIND black as needed. Unfortunately this means a popular method for ordering command is no longer valid.
Lastly it is important to note that you may have consequtive FIND statements if this will help zero in on some lines that aren't particularly distinctive. For instance, if you need to find a specifc but undestinctive feature like a particular <BR> or a } (closing brace), you can have a FIND command that directs us close to the desired location, and then have a second FIND command containing just the <BR> or }. However, this method should be used as infrequently as possible and in fact all other options should be exhausted before trying it.
Whitespace in FINDs
Much of how whitespace plays a role in FINDs is covered at length in the I need (white)space! section. The FIND command is whitespace indifferent, meaning that the FIND command totally ignores leading and trailing whitepace and also whitespace lines. Since whitespace is ignored, be sure that your FIND is not depending on whitespace to be in a particular spot.
-Nuttzy