POSTS APPROVAL MOD FOR PHPBB 2.0.21+ by uncle.f
==============================================================================


SHORT HISTORY
------------------------------------------------------------------------------

I have been looking for the approval functionality in phpBB but could not find
any MOD that would suit my requirements. The best MOD I could locate was
called "Approve Post" [ http://www.phpbb.com/phpBB/viewtopic.php?t=398990 ]

That was OK for a while (although it had "too many features" for my liking)
until its development stopped and the MOD became abandoned. Also, after a
closer look I found some rather questionable code inside that MOD.

Then I came across "Freeze Topic" MOD by axe70
[ http://www.phpbb.com/phpBB/viewtopic.php?t=381964 ]

It looked really promising and was doing things in a simpler and more effective
way than the first MOD I used. Unfortunately, this time it was "too simple"
and the full functionality that I needed wasn't quite there. Plus, I needed the
working solution ASAP...

As they say, if you can't find what you need make it yourself ;)

So I started writing a MOD for the Freeze Topic MOD :) Very soon I recognized
that the functionality I wanted required more fundamental changes in the MOD's
logic, especially with the SQL tables structures. I did not want to push
"my way of doing things", especially because axe70 was actively developing his
MOD at the same time with his own ideas. Instead I scrapped my "modded MOD"
and wrote the whole thing new.

I'd like to thank Freeze Topic MOD for the "starting point" and would like to
note that my MOD does not use a single line from Freeze Topic MOD and is
written completely from scratch.


MOD FEATURES OVERVIEW
------------------------------------------------------------------------------

This MOD allows admins to set an 'Approval' mode for each Forum. If Approval
is enabled in a Forum, all posts made by a normal (non-moderator) user in
that forum must be validated by a moderator/admin before becoming available
for general viewing.

Optionally, it is possible to completely hide unapproved posts from general
viewing before they are approved. In addition, moderators can be notified by
e-mail and/or private message every time the post requiring approval is made.

Finally, the moderators' control panel allows mass approval functions if
required.


MOD FEATURES IN DETAIL
------------------------------------------------------------------------------

- Ability to set per-forum "Approval enabled/disabled" by the admin(s) in the
  "Forum Management" admin Control Panel. By default all newly created forums
  have their approval mode set to disabled.

- Posting behaviour. When the user is making a post in a forum where approval
  is enabled, the subject and the text of the post are replaced by a generic
  message stating that the post is awaiting approval. This does not affect
  admins and moderators who can still see the original posted message (with
  an additional label that the post has not been approved yet). Also, standard
  non-anonymous users can still see and edit their own unapproved messages.
  The unapproved message cannot be quoted in replies (quoting is allowed for
  the moderators and the original authors of the post). Replying to topic is
  disabled until topic's first post is approved.

- Optional user warning. If the standard (non-moderator) user is making a post
  in the forum where approval is enabled, a warning could be displayed at the
  top of the new post page during posting. This warns the user that the post
  contents will not be visible until approved by the moderator. This is
  per-forum setting and can be turned on or off.

- Hiding unapproved posts. It is possible to completely hide all the posts
  that have not yet been approved from viewing by standard users. It means
  that the standard users won't even see the message that says "This post is
  awaiting approval". Mods and admins, however, can see all the posts with a
  special note signifying that the post is awaiting approval but to a standard
  user it will appear as if no message was posted at all. This also includes
  Forums/Topics/Posts statistics which will be changed automatically depending
  on user authorization level, i.e., the mods and admins will see the real
  number of posts/topics in the forums and topics index (as well as stats for
  unapproved posts in brackets) while the standard users will only see the
  number of posts that has been approved and can actually be viewed. Hiding
  unapproved posts is a 'per-forum' setting.

- Moderators notification. As soon as the unapproved post is made (or edited)
  by a standard user an email and/or private message is automatically sent to
  all of the moderators for a given forum. The message contains a link to the
  newly made post as well as the whole posted message itself. In additition,
  the message contains a link which can be used to approve the post directly
  without reading it in the actual forum. If approval notification is on both
  by PM and by E-mail and a moderator has "Private Message notification by
  E-mail" turned on in the user profile, the moderator will only get a Private
  Message regarding the new post to avoid double e-mailing. Moderators
  notification is also a 'per-forum' setting.

- Posts approval. A moderator/administrator has new "approve" button in the
  topic view which allows approving the post. The button has been designed to
  match the default subSilver theme, English.

- Mass approval via Moderator Control Panel. A new "Approve" button is added
  by this MOD to the "Lock/Unlock/Move/Delete" buttons in the moderators'
  Control Panel. This allows mass approval of all the posts inside one or more
  topics with a single click. Moderators can also view the full thread
  before mass-approving it directly from the Control Panel (in a new browser
  window opened by clicking on the approval info link).

- Modified search behaviour. Unapproved topics/posts will not appear in search
  results even when admin or moderator is searching the forums. A post must be
  approved to be a part of search result set. This behaviour may be changed in
  the future if requested by many users.


MOD COMPATIBILITY
------------------------------------------------------------------------------

Please consider the following:

- This MOD has only been tested with the latest available phpBB version 2.0.21
  There is absolutely no guarantee it will work on earlier versions. I will
  not support or address any problems arising from using this MOD with the
  earlier versions of phpBB.

- This MOD is fully compatible with the Attachment MOD.

- This MOD is EasyMOD friendly. Since the MOD is fairly complex it is highly
  recommended to use EasyMOD to install this MOD. This will significantly
  reduce the chances of making a mistake that could cause general forum
  malfunction.

- This MOD has only been tested with MySQL backend. There are some custom SQL
  queries in the "index.php" page that depend on the database back-end, namely
  MySQL, Postgresql and Oracle. This MOD changes all of those queries in the
  "index.php", however, I have no means of testing anything else except MySQL.
  Still, I believe the queries should work OK on all databases. Please let me
  know if you are running with non MySQL DB and it works ok (or not).

- This MOD most likely will NOT work with any other MOD that changes message
  posting or topic/forum viewing behaviour. The approval functionality is
  something that affects phpBB quite deeply, so unfortunately that is the
  price to pay. Sorry :-(  Some MODs like "Topic display order" by Ptirhiik,
  for instance, require tiny adjustment to work together with this MOD.
  Others may require significant code changes.


MOD SUPPORT, BUGS, FEATURE REQUESTS, ETC
------------------------------------------------------------------------------

MOD support will be given directly in phpBB MOD development/released MODs
forums. You can send me a private message or post your query directly in the
MOD's thread:

[ http://www.phpbb.com/phpBB/viewtopic.php?t=438534 ]

Please refrain from posting long code outputs.
Should you need to provide one please send it to me at <avn.soft@gmail.com>.

Most likely I won't implement any new features that require significant code
changes or additions. Sorry.

Smaller suggestions and of course the bug reports are always welcome.
