Written by: Unknown Bliss
Within this article I’m going to briefly outline how to create your modification, package it up, submit it to the Modifications Database and support it afterwards.
Writing MODs can be so simple but yet so complex. It really depends on what MOD you wish to make. If you wish to make a portal or arcade then it will be quite complex. If you just want to make dynamic page titles or ACP Link in header it will be a rather small trivial task.
The first thing you need to do is open up word or notepad and prepare information on your modification, a brainstorm of ideas. It should include items such as your modification name, description, what sort of features you might include and what requirements do you want. Then you need to think about what features you’ll need. For instance, if you are creating a portal, will you have a configuration setting to toggle or re-order individual modules?
Once you have a good idea of how you want to make your MOD you can start to do a bit of research. Take a look at something similar. If you’re designing a blog with articles and comments then take a look at phpBB’s Topic and Replies system. See how it works and what can be done with it. While you’re doing research feel free to note down bits and pieces of information for future reference.
Once you know what you’re making and you have a rough idea on how you are going to make it, you can start working on it. Normally, it’s easiest to start with the database structure. If you have a bug tracker you know you need to make the table for tickets, the table for projects, table for comments/replies, table for logging etc. So plan this structure out.
After you have done all the planning, notes and researching you can install your test board. I recommend you use QuickInstall (QI) as it does a lot of items already done for you and it can generate multiple boards faster. If you use QI then I always find it’s best to populate your board with users and posts as it can come in handy later on. If you don’t use QI then you need to install a board then enable debug and debug extra. You also should change the recompile style components option to ‘yes’ inside ACP –> Load Settings so you don’t need to refresh your style components or cache every time you make an edit to a style file. There is a blog article about QI here
Now that you have a test board, you should use your DB Structure Plan to make your database changes. If you need to add something later then you can. Once you have your database changes in place what you’ll need to do next is write the PHP functions files. I can’t say much about this except that this is when you need to take out your notes and use a checklist of everything that you need to include.
Once you have made the PHP Function Files you need to create the basic language PHP files. At the moment, you won’t have much to put in them. However, you will need to put in the basics, such as, if you are making a set of modules, you will need language entries such as “Recent posts”. Just a reminder that all standard language files should be inside /language/en/mods as all MODs should have an English language built into the MOD. Any additional languages should be in additional MODX Files but I’ll come back to that later. As a general rule it’s normally useful to have a generic error and success message for most MODs.
Now that you have made you language and function PHP files you need to make your template files. These may need to contain the Overall Header and Overall Footer and sometimes forum jump but otherwise its up to you what goes in them. One very common error people make is putting hardcoded language inside template files. This is against phpBB Coding Guidelines and it will make your Modification deny worthy. If you can remember this rule it then means less of a nightmare later on when your MOD is denied for hard coded language and you then have to re-submit it. Note: Hardcoded language can be anywhere, the most obvious and common place to put it is in template files but you can put it in most files and that’s where it normally catches people off-guard.
Now you need to make your PHP file that the user will visit (such as viewtopic.php or blog.php or index.php rather than /includes/acp/info/blog.php). An attempt should be made to keep file names short and simple like portal.php or blog.php rather than my_absloutley_almighty_cool_portal.php.
Once you have a working set of files you need to start adding your ACP, UCP, MCP etc. Modules. I’m not going to go into much more detail with regards to this much except to say that when designing these try to keep them looking uniform with the built-in modules in these control panels.
Now you should have a working test board. At this moment in time you shouldn’t have all of your features implemented except the very core and basic ones. Now you need to add your UMIL files. To do this just generate a UMIF File with the hosted UMIF Generator. Also make sure you include a copy of the latest UMIL and you must make sure this is always the latest and when a new version is released remember to update. Outdated UMIL makes a MOD deny-worthy.
So now its time to create a development topic in the phpBB.com MODs in Development Forum. Make a topic and I recommend you use the suggested template for your topic. At this moment in time don’t attach any downloads and keep the status as [DEV] but if you wish you can provide screenshots.
Now you need to package it into a MODX. I suggest you use the MODX Generator. Once you have this you can then edit the MODX using the MODX Creator with additional information.
Now that you have made your MOD you need to make a new board. This board should be the same as the one you made earlier with debug, debug extra and AutoMOD. Now you need to zip up your modification, go into AutoMOD on the new board and upload it using the upload feature within the AutoMOD module. Once it has been uploaded, install it. If it fails but you can’t see why double check if you have used spaces instead of tabs and vice-versa in finds. Once you have AutoMOD working you are almost ready to submit your MOD.
You should now update your topic to Alpha or Beta (ALPHA is for a VERY unstable MOD. BETA is generally when almost all of the features have at least been implemented, but not much testing has taken place) and add a download link. Downloads aren’t required for the alpha stage but are recommended; otherwise how do people test your MOD and provide feedback? Downloads for beta are required due to rule 3d. The MODs in Development Forum is a place to get ideas, free beta testers and market your Modification so you should take advantage of it.
Once you have added a download I recommend you test your MOD thoroughly for any bugs and fix them. There is a blog post about how the Junior MOD Validators test (and I recommend you test it in the same way) here. Once you are quite sure that all of the bugs have been squashed and that all of the features have been implemented, as you planned from the start, you can promote the MOD status from the BETA to RC (Release Candidate) stage. Many MOD authors will not accept any more feature requests for the current MOD version, pushing any further requests back to the next major version (X.Y). At this point, your MOD should be ready to be submitted for validation by the MOD Team for approval and release into the MOD Database.
To submit it for validation you need to create a Modification type contribution in the MOD Database. For the contribution details, you should generally use the same information as was used in your MODX install file. You will also have the opportunity to include further information, such as a demo URL and screenshots. Finally, select one or more relevant categories into which your MOD fits. Note that at the bottom of the submissions page there is an option to upload screenshots, not revisions.
The next page to come up will be the “New revision” page. On this page you should upload your zipped up Modification, type in your version number and version name (can be the codename for the release or just the version number or the name of the mod). Then you have the notes to the MOD Team section in which I personally add a note of thanks to those who out of their own free time test and validate my MOD’s code but its up to you what you enter into this section.
Once your MOD has been submitted, it is a waiting game of sorts while the MOD Team and Junior MOD Validators review the code and test the functionality. Note that it can normally take a month, sometimes more, for the entire process to be completed, due to the number of MODs submitted. Once your MOD has been approved or denied, you will receive a PM with validation notes. This can include issues in the code, or problems found while testing. Even if your MOD is approved, it is suggested that the validation notes be taken into account for the next version of your MOD. If your MOD is denied, most of the issues found in the report must be changed before your MOD can be resubmitted. If you find that something in the validation report is incorrect or that there is an issue in the report, you may communicate that by replying to your Queue Discussion topic, found in the Discussion/Support tab of your Contribution page. This topic is only viewable to you, the MOD team, and the Junior MOD Validators. If your MOD is denied multiple times, do not become discouraged. Sometimes, when different people look through your code and test your MOD, different problems will be found. Simply fix the issues and resubmit your MOD.
So when you get your MOD approved it is time to provide support for it. This is not required but is asked for by the phpBB.com MOD Team that you update for new versions/bug fixes and support your MOD. I suggest you subscribe to the support tab in your Modification section in the Modifications Database so that you get updates when support is posted. When new phpBB Versions are released you are asked to re-submit it with any fixes that my be required.
If you wish to add features to it you can also re-submit it at any time for that.
And that’s it really. If you have finished this Modification perhaps you would like to start work on another modification (Maybe from the MOD Requests Forum).
In closing, this guide is just that: a guide. It is how I tend to approach the MOD writing process. If you have a method that works better for you, then you are welcome to use that and possibly share it in the discussion topic. It is quite common to skip the earlier section with planning but that is totally up to you. It can, however, prevent confusion, duplication and missing code later on.
Also remember, if you ever need help with anything MOD related you can always ask in the MOD Writers Discussion, in the Queue Discussion Topic (for queries about issues in a validators report being un-reproducible, queries as to what they mean or any notes to the team about issues that arise in validation etc.) or by asking on the FreeNode #phpbb-coding IRC Channel.
