The EmailActivation MoinMoin Plugin
===================================

Overview of what it does
------------------------

This plugin alters the way new accounts are created by the
UserPreferences page.  Newly created accounts are initially
disabled and must be enabled via a special URL.  The URL is
emailed to the address entered when the account was created.
Once the account has been activated the user is sent a
second email inviting them to log in.

A MoinMoin superuser can view all unactivated accounts and
activate or cancel them.  If the account isn't activated
with one week it will expire and be cancelled.  Cancelling
an unactivated account deletes it, thus freeing the account
name and email address for re-use.  An unactivated account
can also be cancelled via the emailed URL.

This default install can be customised in several ways by
providing a single function in wiki configuration script.
The details of how to do this are described below.

The most useful thing to change is who gets the email.
Typical usage is to allow people you trust to activate
themselves, forwarding the rest onto the wiki administrator.
Example: you might choose to let people who entered an
email address from your company activate themselves, but
require you to authorise the rest.

The plugin was developed and tested with MoinMoin 1.5.6.
It was altered to work with 1.5.8.  It is moderately
intrusive and so may not work with other versions.


Installation
------------

To install:

  tar xpfz emailActivation-plugin-VERSION.tar.gz
  cp -a emailActivation-plugin-VERSION/* /var/www/mywiki

Replace /var/www/mywiki with the installation directory of
your wiki.

To be safe it is wise to uninstall the previous version
before installing a new one.  To uninstall the plugin
just remove the files and directories created by the tar
install file.

Upgrading from version 1.0.x: this upgrade is not backward
compatible.  To upgrade Cancel all unactivated accounts
before upgrading, and be sure to do an uninstall first!

Since this plugin relies on email ensure you have defined
the 'mail_smarthost' parameter in the wiki configuration.
See HelpOnConfiguration for more information on how to do
that.


Customisation
-------------

It is a good idea to change the UserPreferences page to say
what will happen when the user creates the account.  The
default one says they will be able to use the account as
soon as it is created.  That won't be the case after you
install this plugin.

The plugin installs a page called EmailActivation.  It
should be OK but you might what to add more information to
it.  The only thing it must contain somewhere is:

  [[EmailActivation]]

Finally there is the customisation script.  This is where
the real action happens.  It lives in the wiki instance
script.  You created this script when you followed the
instructions in HelpOnInstalling/WikiInstanceCreation.
Those instructions refer to it as $INSTANCE, and in the
examples it is called 'wikiconfig.py'.  This script is also
the file you modify when following the help in
HelpOnConfiguration.

The customisation script is a function called:
  EmailActivation_email
You add it to the 'Config' class already defined in the wiki
instance script.  Usually this just means appending a few
lines to the end of the script file.  Be careful to keep the
indentation as is: it is important!  A typical example of a
modified wikiconfig.py:

#
# :
# : Here lives lots of comments and stuff that come with the
# : default version of wikiconfig.py.
# :
#

# now we subclass that config (inherit from it) and change what's different:
class Config(FarmConfig):
    # basic options (you normally need to change these)
    sitename = u'MyWiki' # [Unicode]
    interwikiname = 'MyWiki'
    #
    # :
    # : other stuff defined in wikiconfig.py that doesn't concern us
    # :
    #
    # ------------ Lines below are the ones added -----------
    def EmailActivation_email(self, action, request, user, url):
      if action != 'create':
        return []
      if user.email.endswith("@my-company.com") or user.email.endswith("@my-company.com>"):
	to = user.email
      else:
	to = request.cfg.mail_from
      return [to]

In this example if the email address entered by the user
ended in "@my-company.com", the email would be sent straight
to him so he can activate it.  Otherwise it would go to the
wiki administrator.  This example should happily work if you
just paste it into your wikiconfig.py file, and alter the
email address to suite.  Again, be sure to get the
indentation right.  Use spaces for indenting to avoid
confusion.

The parameters to EmailActivation_email are:

  action   - This is the string 'create' if the account is
             being created, 'activate' if the account 
	     has been successfully activated, or 'cancel'
	     if the activation has been cancelled.  'cancel'
	     is sent when the new account is explicitly
	     cancelled.  No email is sent if the unactivated
	     account expires.

  request  - The request instance.  It is moinmoin's central
             data structure. You will need it if you are
	     going to do something tricky.

  user     - An instance of MoinMoin.user.User().  This
             holds the data entered by the user into the
	     UserPreferences page when the account was
	     created.

  url      - For 'create' this is the URL that will enable
  	     the account.  It should be present in the email
	     sent.  It is a string.  For 'activated' this is
	     the url the user should use to login.  For
	     'cancelled' this is the empty string.

If the function returns None then the account things proceed
as if the plugin wasn't installed.  This means the account
is created normally (ie not disabled) and no email is sent.

Otherwise the return value must be a list containing up to 5
values.  If values on the end of the list are omitted (ie
the list contains less that 5 values) or if a value is None
then the default will be used instead.  The default is
usually what you would get if you didn't supply a
customisation script.  In fact not supplying a script is
identical to having one that returns [].  The default is to
not send an email when an activation request is cancelled.
You can change this to send a reasonable email by returning
[None].

The elements of the returned list are:

  [to, subject, text, expire, message]

They are used like this:

  to       - The email addresses to send the email to.  This
             can be a single string containing one email
	     address, or a list of them.

  subject  - The subject of the email.  This is a string.

  text     - The body of the email.  It must be normal text
             (ie conform to mine type text/plain).  This is
	     a string.

  expire   - How long before the unactivated account will
             expire, in seconds.  This is an integer.  It
	     is ignored when the action parameter isn't
	     'create'.

  message  - The message MoinMoin will display when the user
             clicks the 'Save' button.  This is a string.
	     This is ignored when the action parameter isn't
	     'create'.


Other Notes
===========

1.  Here are the configuration parameters used by the
    script.  These are the parameters defined in
    wikiconfig.py.  See HelpOnConfiguration for more
    information what they do.

      data_dir
      mail_from
      mail_smarthost
      sitename

2.  This plugin overrides the userform Action.  If you have
    installed other plugin's that also override userform it
    is likely something will break.

3.  If a superuser visits:

      http://www.mywiki.site/mywiki/EmailActivation

    they will see all unactivated accounts and can confirm
    or cancel them.

4.  Expired accounts that have not been activated are
    deleted the next time someone tries to activate or cancel
    a new account.

5.  Anybody can delete an unactivated account by going to
    this URL:

      http://www.mywiki.site/mywiki/EmailActivation?n=UserName

    where UserName is the name entered the UserPreferences
    for the page you wish to delete.



--
Russell Stuart
2007-09-27




ChangeLog
=========

emailActivation-1.1.2 2007-09-26

  - Made changes as described by StephenEdwards so it would work
    under MoinMoin 1.5.8.

emailActivation-1.1.1 2007-04-10

  - Reformatted code to bring it in line with MoinMoin coding style
    as per ThomasWaldmann's request.  No functional changes.

emailActivation-1.1.0 2007-04-07

  - Fixed bug in account expiry.  This bug probably meant it
    didn't work at all - sorry!
  - If a superuser views the EmailActivation page a
    list of outstanding activations is shown, and they can
    be confirmed or cancelled.
  - An email is now sent when the account is activated.
  - An email can now be sent when the account activation is
    cancelled.
  - Renamed lots of things to create a more consistent
    naming scheme.

emailActivation-1.0.1 2007-04-03

  - Allowed email destination to be a list.
  - Cleaned up wording in README.
