EasyMOD ReadMe for EasyMOD beta 1 (0.3.0)
 

For newest releases of EasyMOD and fresh news see: Announcements and News.

Manual sections

Table of contents

Overview & current release notes

Introduction

EasyMOD is an automatic MOD installer. It does in seconds what used to be the laborious and time-consuming task of manually editing files. EM will install EasyMOD Compliant (EMC) MODs and will try to install all other MODs, as well. For most users, MOD installs should be completely automated. There are break points during the installation, so you can check what EM proposes to do before it makes any permanent changes.

^ back to TOC ^


Author's Notes

This release fixes several bugs and one security issue, but it also comes with several new features. One of the most important changes is it includes a back ported version of the SQL Parser that is being written for the EasyMOD re-write (see notes for MOD Authors below). It also includes two extensions available from the History Details report (Delete MOD Record and Restore Backups). The help system available in the installer panels has been completed and it is also available from the EasyMOD Settings panel in the AdminCP.

The only major feature missing is an uninstaller, which is definitely planned before version 1.0.0. This version still lacks a certain degree of polish, and the SQL and COPY commands may still be a bit buggy, but nothing show-stopping. This is the 13th public release of the program and most parts are battle-tested.

Please refer to the changelog for more details.

MOD Authors: Lastly, thank you to everyone that has pitched in, whether it be translations, graphics, or hard core testing. You've been a big help!

^ back to TOC ^


EasyMOD installation

Downloading EasyMOD

For newest releases of EasyMOD go to the Announcements and News at area51.phpbb.com. There you will find topics called like "EasyMOD v0.3.0 released (for phpBB 2.0.x)". There should be a link for downloading EasyMOD in the topics first post. Remember to get the newest available version (topic with highest version number)!

^ back to TOC ^


Installing EasyMOD

  1. Download the archive of the latest EasyMOD.
  2. Extract it into the admin/ directory of your phpBB2 installation. The proper directory hierarchy should be your_forum_folder/admin/mods/easymod/. The image below shows a proper setup.
    your_forum_folder > admin > mods > easymod
    Note: your_forum_folder should be your forum folder ;) (the default name is phpBB2, but it don't have to be like that)
  3. Before proceeding, make sure subSilver style is installed on your board and also, make sure the English language files are present.
  4. From a web browser:
    • Open your board and make sure you're logged in as an administrator.
    • then open:
      http://www.example.com/your_forum_folder/admin/mods/easymod/easymod_install.php
      where www.example.com/your_forum_folder is the URL (including path) to your board, and then the installer will guide you through everything. No modifications will occur before warning you first.
  5. If you are using FTP access, make sure you, as the owner, have write permission on ALL your phpBB files (CHMOD 755).
If you will encounter any problems then see this FAQ. Also take a look on other FAQs before you ask any questions, thanks.

Good luck and happy MODing :)!

^ back to TOC ^


Post installation/upgrade (optionally)

Once EasyMOD has been installed, please enter the AdminCP and try to install a MOD. If everything looks good, you can then remove the admin/mods/easymod/ directory and all of its contents. Although it is safe to keep it (anyone else but admins can launch the installation, even if they try the installer will report this EM version is already installed and die) it is not used anymore.

^ back to TOC ^


Upgrading EasyMOD

It is advised that you remove any previous admin/mods/easymod directory. Once they are out of the way, just follow the install instructions above. EasyMOD will figure everything else out.

^ back to TOC ^


Reinstalling EasyMOD

If the installation failed in some way, then you may want to reinstall EM. This is what you should do:

^ back to TOC ^


Features

Features of Easy MOD

^ back to TOC ^


Translations

Translations for Easy MOD

EasyMOD is going international! Translations of lang_easymod.php are needed! Several translations have been completed in the past, but they will need to be updated for all of the new language variables in this version. Translations will be available in this topic. If you have translated EasyMOD into a language that's not already available there, please send your translation to wGEric via PM.

^ back to TOC ^


Changes

Version History

A complete list of changes to the EasyMOD code, including past versions, can be found here.

^ back to TOC ^


Language Pack History

A complete list of changes to the EasyMOD language variables, including past versions, can be found here.

^ back to TOC ^


Support

Important notice

Please note that EasyMOD is still considered BETA quality software. That means you should still expect bugs and fixes and the need of upgrading and so on. If you can't deal with that, then you should probably just wait for it to become more stable and user friendly. But if you want to install it then we'll be happy to welcome you as a beta-tester ;).

^ back to TOC ^


Before reporting problems

First of all check for new releases - maybe the problem was already solved with it.

If you are having problems with newest EasyMOD then go ahead and report it. This would help a lot to improve EM and solve problems for others. Just please take some time to check if the solution can't be easily found in this manual or at the EasyMOD forum (try googling).

We don't ask you to spend long hours searching for the answer, we only ask you not to ask a question that is already answered and out on the view, because then we would spend long hours answering the same question again and again and not going any where near to give you next releases.

Reporting problems with EasyMOD installer
Reporting problems with EasyMOD installing a MOD

^ back to TOC ^


Googling your way out

In some cases searching with phpBB search system just don't work too good (e.g. you are looking for a word that system rejects). Still you can always try to google (www.google.com).

The first thing you should try is a phrase like: EasyMOD something (where something is a word/phrase you are looking for). When you don't hit anything when searching for the whole phrase then just try some part of it. It's also helpful to look for synonyms e.g. ~upgrade will find upgrade but also upgrading.

To look in a specific site (like area51.phpbb.com) use: site:area51.phpbb.com EasyMOD something.


For more tips see: www.google.com/help/.

^ back to TOC ^


Reporting problems with EasyMOD installer

Be sure to read the above before you report a problem.
  1. Write at what step of the installation you've got the error: Step 1 (gathering settings), Step 2 (confirming your file access settings), Step 3 (information on actions), Step 4 (moving files), Step 5 (confirmation of changes).
  2. Include any error messages or warnings you get, and if helpful, your own description of any problems you are having. If the debug information isn't displayed, then be sure to click the "Display Debug Information" link and include that information in your post.
  3. Please also write if you ever succeeded in installing EasyMOD (which version) on your current or some other servers. This could help to find out what's causing the problem.
  4. The debug info is already formatted for forum posting so there is no reason to put inside of [code] tags!
  5. If you are using FTP, then also be sure to enable FTP debug mode and include that information as well.
Following these simple steps will help us fix your problem and we will really appreciate it.

Thanks!

Forum for reporting problems with EasyMOD installer

^ back to TOC ^


Reporting problems with EasyMOD installing a MOD

Be sure to read the above before you report a problem.

Theoretically, if EM installs correctly, there shouldn't be any problems with MOD installations that are truly an EM bug. The problem will be mostly with the MOD itself (you should try to ask the MOD author then), but if you think this is the fault of EM...
  1. Write at what step of the installation you've got the error: Step 1 (processing MOD file), Step 2 (database alterations - SQL), Step 3 (backing up and copying the files).
  2. Include any error messages or warnings you get, and if helpful, your own description of any problems you are having.
  3. Please also write if you ever succeeded in installing MODs with EasyMOD (which version) on your current or some other servers. This could help to find out what's causing the problem.
  4. Be sure to provide a download link to the MOD you are trying to install. Otherwise we could only guess what was wrong!
  5. Please be patient. As said above - it is most often not going to be an EM problem so answering these questions are lower priority. But we'll get to you eventually so please don't bump your topic needlessly.
Following these simple steps will help us fix your problem and we will really appreciate it.

Thanks!

Forum for reporting problems with EasyMOD installing a MOD

^ back to TOC ^


IRC Support

A support channel, #easymod, is registered on the freenode.net IRC network (irc.freenode.net). After reading the phpBB IRC rules, feel free to drop in and ask a question. Several team members are usually there, but please don't flood the channel with support requests. Note that this channel is for EasyMOD discussion only.

^ back to TOC ^


General EasyMOD FAQ

Where do I download the latest EM?

The latest can always be found in the Announcements forum.

^ back to TOC ^


Will EM work with my other Templates (like subBlack) and lang packs?

Yes, it will try but since all MODs are written for subSilver it is possible that it will run into problems with the other templates if they are too different from subSilver. Both subSilver and English must be present though.

^ back to TOC ^


How well does thing really work?

EM works fantastic for MODs that are properly formatted. Truthfully, most MODs are not written very well in that they do not prevent clashes with other MODs. But this is not really the MOD Author's fault since no guidelines have been written on how they should do this.

Nutzzy and the dev-team are still writing the guidelines. Until this is done and MOD Authors start following them, then there are bound to be problems. (FYI, we do plan on being fairly flexible on what kind of coding styles we'll allow ;)).

^ back to TOC ^


My EM password doesn't work, or I can't remember it.

This won't be very easy, but if you'll go through this steps then you should manage.
  1. Run phpMyAdmin (it doesn't come with phpBB, but is often supplied by the server administrator, if not download it from www.phpmyadmin.net); for PostgreSQL database use phpPgAdmin.
  2. Select your forum database.
  3. Run this SQL:
    SELECT * FROM phpbb_config WHERE config_name = 'EM_password'
    Note: this assumes that you haven't changed the table prefix (phpbb_) when you installed phpBB! You'll have to correct this if you changed it.
  4. Click on the edit button (shaped like a pencil)
  5. Select Function MD5 to be done with config_value
  6. Write your new password in the edit-box and press "Go".
This wasn't so hard ;). If you will need some help updating your DB, then this Tutorial on using phpMyAdmin could be helpful; for phpPgAdmin go to it's support page (try asking at their forums).

^ back to TOC ^


How to uninstall EasyMOD?

That depends on why you want to do that and whether you have the latest version of EM.

When you do any installations and uninstallations you should always be careful! If you are sure you want to do that then go through these steps:
That should be enough, though you might also want to run these SQL statements to delete the EasyMOD records completely:
Note: Change phpbb_ to your table prefix for phpBB tables.

^ back to TOC ^


How to install MODs on different templates?

If you just installed another template or the installation on some template didn't work and you want to try again then you should do this:
  1. Install EM on some test forum (the forum shouldn't have any MODs installed).
  2. Install the template(s) that you want (on the test forum of course).
  3. Install all of the MODs that you have now.
  4. Copy the files of the template(s) that you want (to your working forum).
Warning! The installation on some (probably many) templates will fail as most MODs are made to be installed on specific template (subSilver mostly). This can't be fixed without the manual manipulation of the MOD and/or the files of the template(s).

^ back to TOC ^


Why are MODs reappearing as unprocessed?

In the latest EM (0.3.0) the phpBB version check for processed MODs was removed, so this shouldn't happen.

In previous versions of EM this would happen when you upgrade your phpBB forum. This way EasyMOD was allowing you to reinstall already processed MODs after the upgrade.

Important: Reinstalling some MODs may damage your board! It all depends on how the forum was upgraded - if it was by an upgrade MOD then all MODs should be already installed so there is no need to reinstall them.

Information on how to disable this feature is here (not needed in the latest EM).
More information about the dangers of reinstalling MODs may be found here.

^ back to TOC ^


EasyMOD Installation FAQ

Step 1: I get "Warning: main(./../extension.inc): failed to open stream: No such file or directory..."

Most probably you moved the installation files of EasyMOD to a bad installation directory - should be admin/mods/easymod (See more)

^ back to TOC ^


Step 1: I'm trying to reinstall EM, but it says "This version of EM has already been installed."

Go to the EasyMOD Settings (in the Administration Panel), login and just change the version to something lower then you already have (e.g. from 0.3.0 to 0.2.0). After this you will be able to reinstall the EasyMOD.

Note: If you are unable to reach the settings of EasyMOD you may use the Version Changer by GPHemsley.

^ back to TOC ^


Step 1: It says "Critical Error: EasyMOD cannot be installed. The subSilver template is not present..."

EasyMOD needs subSilver to work correctly, this is an obligation...

To be more exact EM checks if: So you don't really need to use it you just need to have it and add it in your ACP.


If you want to trick EM then you may change your templates name to subSilver, but then you must follow this steps:
  1. Change the name of the folder of your template to subSilver (case sensitive!)
  2. Change the name of main css file of your template to subSilver.css (case sensitive!)
  3. Change the name of main cfg file of your template to subSilver.cfg (case sensitive!)
  4. Most important! You will need to find and replace all occurrences of the name of your template in the files of your template to subSilver (case sensitive!)
    This is needed because some pictures and other files path may need to be updated to the changed path (after all you just changed the name of their folder).
So... I'm not sure if you really want to do all that ;). I suggest the first solution ;).

IMPORTANT: Do not report any "bug" that's related to failure of any FIND in changed templates. The reason is simple - most of them are just too different from subSilver.

^ back to TOC ^


Step 1: It says (in the File Access Info) that I don't have copy access, or write access, or some other kind of access. What do I do?

You don't need these. It is purely informational. As long as you have Read Access = OK then you will probably be fine.

If you still don't know what to do then generally if you will choose "I don't have FTP access. Have EasyMOD suggest what to do please!" and hit submit, then EasyMOD will check everything for you.

If you want to now more then read on...

First thing you have to know is that the user that is running a script is set in conf(iguration) files of the server. So this is basically, the host's problem.

Second thing is that if something isn't really strange, then if you copy something to FTP, then you will be able to modify and delete it, because you will be the owner of that file.

About File Access Info:

All of the below tests are done by, through and for the modes not using FTP access.
Other tests:

Only tmp path write, Safe Mode and FTP extension can mean something for the FTP moving/writing methods, but none really means that using FTP will be possible or impossible.

Write method "server" need: write access and mkdir access.
Move method "copy" need: copy access and root write.

^ back to TOC ^


Step 1: "I use a local server, so why do I get write access = No?" aka "How do I set file access on local/test machines?"

If you can, then you should change Apache conf(iguration) file so that the user and the group will be the same as the owner of the files.

Alternatively you may change the owner of the files of your forum to the currently set Apache user (usually named "apache"), but this could complicate things to you.

The path for the configuration file (for Apache) should be something like: In general look for *httpd.conf file(s).

The configuration to change will probably be:
User apache
Group apache

^ back to TOC ^


Step 1: When I look at the installer, it has nothing but F's where the text is supposed to be!

This truly bizarre problem is caused when at some point you tried running the EM installer and the lang_easymod_english.php file was not present. Make sure the file is in the admin/mods/easymod/languages/ directory. If you continue to get the problem, then you need to clear your cache. For Internet Explorer, go to "Tools", "Internet Options", and then click the "Delete Files" button. Now try the installer again, refresh if needed.

^ back to TOC ^


Step 3: I get the error "Could not open [language/lang_german/lang_admin.php] for reading". What do I do?

Most likely you have the Attachment MOD already installed and you do not have the German language package installed. Many people simply take the lang_german directory of the Attach MOD and copy it into place. This is wrong. If you do not have the German lang pack installed then simply delete the language/lang_german directory.

^ back to TOC ^


Step 4: I get FTP errors like:
Critical Error: FTP ERROR: could not move file [admin/mods/easymod/processed/language/lang_english/lang_admin.php.txt] to [lang_admin.php]
ATTEMPING REMAINDER OF POST PROCESS
Critical Error: FTP ERROR: could not change directory to [admin]
Current dir: [/public_html/forum/language/lang_english]
.
What do I do?

Most likely your phpBB files are set to read-only (644 or 444 access). You need to give all the files in your phpBB installation write access to the file owner (744). This is not a security hole.

^ back to TOC ^


Step 5: I get error like: Could not find $lang['MOD_control_tag'] = '0.3.0 in [language/lang_english/lang_admin.php]. What do I do?

This means something has not gone correctly. Could mean a few things. If you got any errors or warnings before this step, post them up so we can see them. Also click the "Display Debug Information" link and post that information. If you are using FTP then enable the FTP debugging so we can see that too.

^ back to TOC ^


Installing MODs with EasyMOD

Installing MODs with EasyMOD

Theoretically, EM should be able to install any single MOD currently in the MODs database at www.phpbb.com. However, MOD authors do not currently write their MODs to prevent clashes with other MODs. Therefore the more MODs you install then the more likely they will clash with each other and EM won't be able to install them. The next phase of the project will be to write a set of standards to prevent this (EMC).

To Install a MOD
  1. Connect to the server (through the FTP) where the MOD(s) are to be installed
  2. Go to the forum folder and then admin/mods/ folder
  3. Create a new folder for the MOD files and folders
    • note: the directory you create cannot have any spaces or single quotes (')
    • note: All MODs should have their own directory
    • example (correct): admin/mods/Country_Flags
    • example (incorrect): admin/mods/Country Flags
  4. Upload all files and folders for the MOD into the created folder.
  5. Visit the forum where the MOD(s) are to be installed, log in as an Administrator, and enter the Administration Panel.
  6. Click on "Install MODs" under the "MOD Center" header in the left-hand-side panel.
  7. Enter the password for EasyMOD that you first set at installation (or on the "EasyMOD Settings" page).
  8. EM will list any MODs it detects (see below for problems). Find the MOD in the list of MODs and just click the "Process" button to the right of it.
  9. Confirm that EasyMOD has detected and correctly interpreted all steps in the MOD and then click the "Next Step" button.
  10. EasyMOD will now make changes to your database if you command it to. Any SQL with a check next to it will be performed by EM. If you are reinstalling a MOD, you probably do not want to run the SQL a second time, so be careful!

    Official Warning: This is a DUMB process. Commands you check off will be executed but EM does NOT check to see if these changes will negatively impact your database. You are STRONGLY advised to backup your database before making any changes! Prior to executing, you are advised to examine each command thoroughly or ask for feedback from experienced MOD installers. Again, if you are reinstalling a MOD, multiple executions of the same SQL lines could adversely effect your database!

    Click the "Complete Installation" button when your done.
  11. Check to make sure that the MOD installed correctly.
    • note: in most of the cases (settings) you won't have to worry about that, but if you had chosen "download" or "on screen" method for writing or "manually load" for moving then you will need to move backups and other files to places shown in the tables.

^ back to TOC ^


EM won't see your MOD? Here's why...

  1. EasyMOD will scan for any .txt or .mod file in the directories in admin/mods to see if it's a MOD, that's why it won't find any MODs if they are just in the admin/mods directory and not in their own folder.
  2. EasyMOD looks in the header of the MOD and needs to find at least a title and an author name in order to install. EM is fairly flexible in what it will accept, but optimally it is looking for the following format:
    ## MOD Title: mod_title_goes_here
    ## MOD Author: username < email > (real_name) website_url
    ## MOD Description: some_description_goes_here
    ## MOD Version: x.x.x
To check if a syntax of the MOD is correct try out the on-line MOD Validator. If all will be correct, but EM won't see your MOD then please report to EasyMOD fourm, thanks.

If you want to know more about the correct MOD template syntax then read this article.

^ back to TOC ^


EM says it cannot FIND a line in a file.

Most likely this is not EM's problem. The reason is either going to be one of the following:

^ back to TOC ^


After installing a MOD I get SQL errors. What do I do?

Visit SQL Parser forum if you will have problems with the SQL processing done by EasyMOD.

If there were no SQL statements shown when installing in the MOD then you should check the Author's Notes or any documentation files supplied with the MOD - there may be some installation script to run.

^ back to TOC ^


Installing Attachment MOD v2.3.13 with EM

Attachment MOD (Attach) by Acyd Burn is one of the most popular MODs for phpBB. There is also a lot involved with installing it and there are many requests for it to work with EM. It almost does ;) You just need to follow the simple steps below to get Attach ready for EM and have it installed in no time!

IF YOU ENCOUNTER A PROBLEM, ASK ON THE ATTACHMENT MOD SUPPORT TOPIC, NOT ON EASYMOD FORUM!
  1. Refer to the Attach documentation for the most detailed installation instructions (start with readme.txt)
  2. Create the attach_mod directory in admin/mods. You will now have an empty admin/mods/attach_mod directory.
  3. From attach_mod/docs move (through FTP) the appropriate script to admin/mods/attach_mod. For a fresh install use (copy) install.txt

    Note: Sadly upgrades are not correct MOD files, though update_23x_to_latest.txt should work if you replace all of the header instructions with at least a minimal MOD header (described here).
  4. And now we go by the steps as described in install.txt...
    • Step I (copying files): Copy/Upload all files from attach_mod/root to the their respective locations.

      In most of FTP programs you can just mark all files from attach_mod/root and upload them to your forum folder (the one that has config.php in it).
    • Step II (database changes): Just run mod_table_inst.php in your browser (http://www.example.com/your_forum_folder/install/mod_table_inst.php
      where www.example.com/your_forum_folder is the URL (including path) to your board).

      Note: The file would be "attach_update_23x_to_latest.php" when updating from 2.3.x.

      The used file should have already been uploaded in the first step, so if you don't have it then you've probably made some mistakes in the first step (recheck all files).

      Remember to delete the whole install directory after you finish.

      Note: you should also delete the language/lang_german if you don't use this language on your forum.
    • Step III (file changes): You are a lucky one ;) - EasyMOD will do this for you! Just install Attach as any other MOD.

      See here if you need help on installing MODs with EM.
    • Step IV (the finishing touch): You're almost done just read those "Additional Instructions" at the end of install.txt. You'll have to find out if you have to chmod (change access mode) of files to 777. This is important - you'll probably get an "Upload Error" if you're going to ignore this step.
IF YOU ENCOUNTER A PROBLEM, ASK ON THE ATTACHMENT MOD SUPPORT TOPIC, NOT ON EASYMOD FORUM!

^ back to TOC ^


General troubleshooting FAQ

I get a blank page in the Administration Control Panel (ACP).

Most likely you installed manually and made a common error of not changing the name of easymod's lang file.

admin/mods/easymod/languages/lang_easymod_english.php
should be copied (or moved) to:
language/lang_english/lang_easymod.php

(the same goes to any other languages)

^ back to TOC ^


I get a "INVALID PASSWORD SUPPLIED" error when trying to enter the install page.

You have entered a password other than the one set for entrance to EasyMOD or you have not entered a password at all. Try entering a different password.

^ back to TOC ^


I get an "All MODs have been processed" message instead of a list of MODs on the "Install MODs" page.

This is the same as here.

^ back to TOC ^


I get a "Critical Error" message on the first page of installing a MOD.

Usually critical errors occur when FINDs or COPYs cannot be completed. Make sure the code being looked for exists in the file it is being looked for in or that the file to be copied exists in the folder that it is said to be in.

^ back to TOC ^


I get a "Warning" message on the first page of installing a MOD.

This is just informing you that EasyMOD cannot find the specified lines of code in languages other than English or styles other than subSilver. You can then choose to continue with or halt installation of that MOD.

^ back to TOC ^


There are errors in pages outside of the EasyMOD pages in the Admin Panel (i.e. Parse errors, unexpected characters, etc.).

This is probably not an error on EasyMOD's part. Please contact the MOD Author in whichever way he/she prefers. If the MOD normally functions correctly with the version you tried to install, please report your error (See: Reporting problems).

^ back to TOC ^


Links

General

^ back to TOC ^


Add Ons

^ back to TOC ^


MOD installation and uninstallation

^ back to TOC ^


EasyMOD Compliance

^ back to TOC ^


ReadMe file - About & Credits

About this ReadMe file

This is the version 0.0.4, so any comments are very welcome :). For suggestions go to this topic. I don't want it to become an ultimate support topic ;), so please be specific about what you would like to see in this ReadMe.

This ReadMe file is a compilation of all basic knowledge (mainly the FAQs) I could get to at area51 plus some extra stuff (like: updated installation instructions for Attachment MOD v2.3.13). Most of the first gathered posts (for ver. 0.0.1) were written by Nuttzy99 and GPHemsley.

^ back to TOC ^


Credits for this ReadMe file

^ back to TOC ^


Copyrights

This ReadMe is an Open Source software released under the GNU General Public License (ver. 2).

Contents of this file are the Copyright © 2003-2005 Nuttzy - Craig Nuttall, 2003-2005 by GPHemsley, 2005 by Maciej "Nux" Jaros, 2005 by The phpBB Group.

The script that generated this file is the Copyright © 2005 Maciej "Nux" Jaros.

^ back to TOC ^