Supplemental Articles

[Nuttzy99]

NOTE: these articles are referenced from the main text of EMC. It is not necessary to read them.



Template Command Generations

1st Generation Template commands have the basic OPEN, FIND, AFTER, and BEFORE commands. The REPLACE command is used frequently and it obliterates the original core PHP code with each use. After reviewing the MOD sites of competing bulletin boards, I've determined only phpBB has moved beyond 1st Generation.

2nd Generation Template commands add the IN-LINE commands to allow for precision operations on the core PHP files. This causes for a great decrease in the disruption of the code from its original form. Its more like performing surgery on the code whereas 1st Generation is like whacking it with a sledgehammer.

3rd Generation Template commands are less about the actual commands and more about the how the commands are used. By the shaping of the FIND command targets, avoidance of REPLACE commands, and general concern for maintaining the integrity of the original core PHP code, MODs are constructed so that they will not be interferred with by previous MOD installations and will not interfer with future MOD installations. This allows for true automation to be performed. EMC is 3rd Generation, putting phpBB two generations ahead of any other BB's MODing community.

What could 4G be? The next generation will somehow (I've not a clue how!) be self-diagnosing and self-healing when it comes to errors in modifing the phpBB code. This in a sense will be a guarantee that the changes made make sense and are reliable. Reliablity is the ultimate goal.

[Nuttzy99]

File Manipluation Technology

1st Generation Automation programs are just happy to be doing something. Security concerns or platform compatiablity is not even considered. Users are asked to 777 all the files of their forum which is of course a huge security hole. No intermediate files are made so the work of the automation program to be checked. Users have to have faith that the program works well enough and does not destroy their forum without them being able to check the work of the program.

2nd Generation Automation programs attempt to become more platform independent while respecting security. One solution is to MOD files locally and then FTP the files into place. This also allows for intermediate files to be inspected before being moved into position. The problem is that it requires a client program that is generally run in a Windoze environment, which not everyone has. It also relies on FTP access which not everyone has.

3rd Generation Automation programs strive for both platform independence and security. The program is PHP based, running on the same webserver as the forum. This ensures that executing the program is platforum independent. Next a host of methods are devised to conqueer getting around the myraid issues of manipulating files through a webserver. The goal is 99% compatiablity with all potential user configurations all without introducing a single security hole.

What could 4G be? Probably something like automatically installing MODs directly from a central database. No downloading involved! Actually members of the MODs Team are already tackling this

[Nuttzy99]

Ordering of FINDs

You have to remember that the MOD Template has been evolving and that means occasionally we must break with the way things were in order to make the next big leap. Folks had been used to the idea that you would think of commands as groups and that no matter where you were looking in a MOD script, all the commands were neatly found in the same group. For example, for each IN-LINE find command you would have have a FIND and an IN-LINE FIND preceeding it, even if you were doing multiple IN-LINE operations on the same line. So you would have FIND -> IN-LINE FIND -> IN-LINE BEFORE, ADD and then have FIND (the same line) -> IN-LINE FIND (the same fragment) -> IN-LINE AFTER, ADD.

I agree this does make for a nice, neat, and readable MOD script. However the idea is flawed. When dealing with automation, computers take things quite literally. Therefore if you take things literally, then the second time around when you do the FIND it will b/c the line has changed! Furthermore since we are building a new file through automation, at some point we have to commit to the line being done of any more modifications. The logical point to do this is at the next FIND statement. Lastly, it is possible the same line appears twice in the file and allowing for a FIND of the same target multiple times would be an issue.

FYI, we also must do commits after an AFTER, ADD. This is necessary because when building the file you have to write the FIND target before you perform the AFTER, ADD. Therefore no more operations can occur on the line following and AFTER, ADD.

The same applies for IN-LINE FIND where the same target is to only be found once and then operated on multiple times if necessary.

[Nuttzy99]

Whitespace

When I refer to whitespace, I simply mean the empty lines between lines of code and the tabs or spaces at the beginning and end of a line.

code without whitespace:

Code: Select all

<?php
for ($i=0; $i<5; $i++)
{
if ($i==2)
{
echo "Hello World\n" ;
}
}
for ($x=0; $x<5; $x++)
{
if ($x==2)
{
echo "Goodbye World\n" ;
}
}
?>

code with a whitespace tabs to improve readablity:

Code: Select all

<?php
   for ($i=0; $i<5; $i++)
   {
      if ($i==2)
      {
         echo "Hello World\n" ;
      }
   }
   for ($x=0; $x<5; $x++)
   {
      if ($x==2)
      {
         echo "Goodbye World\n" ;
      }
   }
?>

code with a whitespace lines to improve grouping recognition:

Code: Select all

<?php


   for ($i=0; $i<5; $i++)
   {
      if ($i==2)
      {
         echo "Hello World\n" ;
      }
   }


   for ($x=0; $x<5; $x++)
   {
      if ($x==2)
      {
         echo "Goodbye World\n" ;
      }
   }


?>

-Nuttzy

[Nuttzy99]

THIS IS A RAW UNEDITED REPLY (it needs work for sure )

Why FIND must not be forced to include the start of the line:

There are several obscure reasons I could use but I will not use those in my arguement. There are so many very legitmate reasons that it is not necessary for me to stretch things.

First the principal goal of FIND to use unique elements of a line (or block of lines) to find the part of the code you are looking. We do this with the knowledge that lines may have been changed by a previous MOD installation or we may be looking for lines in a non-subSilver TPL file.

It is completely reasonable to assume that any part of a line may have changed from the default phpBB, whether it be the beginning, middle, or end of the line. Therefore it is necessary to limit the FIND to only what is unique about it and eliminate all other text that could possiblely causes a FIND to fail. But one must remember to not be overzealous in trimming out text or must include additional lines in the FIND to assure that the correct line(s) will be found.

Some folks, especially those that like to comment out a lot of code, support the notion that FIND must be forced to include all of the text from the start of a line until the desired unique element is encountered. Unfortunately this idea is flawed and will needlessly result in FINDs failing to do their job. Several examples follow.


Conditional statements
In PHP files the most likely instance where the beginning of a line will change is on any conditional statement. For example, it is entirely like that you may be seeing a line like this....

Code: Select all

if ( $mode == 'editpost' || $mode == 'delete' || $mode == 'poll_delete' )

...but another MOD has changed it somethign like this...

Code: Select all

if (( $mode == 'editpost' || $mode == 'delete' || $mode == 'poll_delete' ) && ($foo))

...therefore the best way to find this line possiblely may be to reduce the search string down...

Code: Select all

$mode == 'delete' || $mode == 'poll_delete'

...but there is no doubt here that forcing FIND to include the beginning of the line is going to cause it fail.

Similar things can be said for "while loops" or with variable assignment. For example you may have a while loop that has changed from...

Code: Select all

while ( $end_counter && $end_html < strlen($message) )

...to...

Code: Select all

while ( ($end_counter && $end_html < strlen($message)) && ($foo == $bar) )

You may also have a variable assignment like this...

Code: Select all

$is_auth = auth(AUTH_ALL, $forum_id, $userdata, $post_info);

...that gets changed to...

Code: Select all

$is_auth = ($foo) ? auth(AUTH_ALL, $forum_id, $userdata, $post_info) : $bar ;

...in both these examples there are plenty of unique elements to search for, but forcing the requirement of the beginning of the line will make the FIND fail when it is totally preventable.

SQL statements
To a lesser degree, SQL statements are also susceptible. Take this for example...

Code: Select all

$sql = "SELECT u.username, u.user_id, u.user_posts, u.user_from, u.user_website, u.user_email, u.user_icq, u.user_aim, u.user_yim, u.user_regdate, u.user_msnm, u.user_viewemail, u.user_rank, u.user_sig, u.user_sig_bbcode_uid, u.user_avatar, u.user_avatar_type, u.user_allowavatar, u.user_allowsmile, p.*,  pt.post_text, pt.post_subject, pt.bbcode_uid
   FROM " . POSTS_TABLE . " p, " . USERS_TABLE . " u, " . POSTS_TEXT_TABLE . " pt
   WHERE p.topic_id = $topic_id
      $limit_posts_time
      AND pt.post_id = p.post_id
      AND u.user_id = p.poster_id
   ORDER BY p.post_time $post_time_order
   LIMIT $start, ".$board_config['posts_per_page'];

...in this frequently modified section of code, if anything inserted before u.username or POSTS_TABLE or if the code following WHERE, ORDER BY, OR LIMIT is modified only slightly then the FIND could needlessly fail. For the most part though, authors will probably insert new code in the middle of the line rather than the start, but there is no guarantee. I prefer to give authors as much freedom as possible so they may order things however they want.


The big one! TPL files
The greatest need for not forcing the use of the start of the line comes from TPL files. It is undeniable that many user have more than just the default subSilver installed. Some of these templates are more similar to subSilver than others. Even an unmodified non-subSilver TPL can have problems being MODed unless there are specific instructions for it. But the goal remains the same of trying to install MODs into all templates even if they are different from subSilver and modified as well.

By forcing the inclusion of the start of the line then you are going to be requiring the inclusion of items such as widths, colspans, alignments, and classes. This is pretty much guaranteeing failure in anything but subSilver. I simply cannot allow this to happen.

But requiring these will even create problems for subSilver once it has been modified. It means that in the following line...

Code: Select all

<td width="150" align="left" valign="top" class="{postrow.ROW_CLASS}"><span class="name"><a name="{postrow.U_POST_ID}"></a><b>{postrow.POSTER_NAME}</b></span><br /><span class="postdetails">{postrow.POSTER_RANK}<br />{postrow.RANK_IMAGE}{postrow.POSTER_AVATAR}<br /><br />{postrow.POSTER_JOINED}<br />{postrow.POSTER_POSTS}<br />{postrow.POSTER_FROM}</span><br /></td>

...if a previous MOD has changed anything before {postrow.U_POST_ID} (which is the first unique thing about the line) then your FIND will fail. There are just too many elements that people may want to change.


Adding comments to the code
As I've said before, the core phpBB core code is like a map. We rely on various landmark to FIND our way around. Some folks have the practice of automatically including in their MODs large blocks of duplicate code that matches the original phpBB core code, except it has comments in front. The intention is good, allowing users that manually edit files can see what was changed. However the effect is like adding extra landmarks that don't really exist into our map! Without some way of distinguishing these blocks from the rest of the code, then integrity of our map degrades rapidly. To allow for this practice there must be a standard adopted to inform us that we must not use these lines in our FIND.

-Nuttzy

[Nuttzy99]

MODing Globalization

The next release of EM will feature complete multilingual support. The hope is that this feature will serve to unite all the MODing communities around the globe and increase the number of MODs being shared between them. MOD authors will be able to write MODs in their native language including the template commands. Thus 100% of the MOD is in the native language. Translations of the MOD will also be in 100% of the translated language. EasyMOD will be able to work with all of these translations.

Therefore we are bridging the language gap between MODing communities. Hopefully this system will make things much easier for a MOD written in one community to be shared with the other international communities. This will make MODs available to more users and also eliminate redundant efforts by Authors.

The key will be a consistent translation of the template commands for a particular language. The phpBB French site ( http://www.phpbb-fr.com ) appears to be an excellent model. The site is the known hub for the French MODing community and this makes them the logical choice for choosing the wording for any translations. They have already translated the MOD Template commands and it is assumed that this is a widely used resource by the French community. EM will be able to use these commands seamlessly as if they were written in English. So the need is for the leading phpBB resource site for each international community to settle on a translation for the MOD Template commands.