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

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

This plugin causes new accounts to be disabled when they
are created.  An attempt to log in while the account is
disabled generates a 'invalid password' error, so it is
unusable until it is enabled.

The user is sent an email to the email address entered
when the account was created.  In that email is a URL
to your wiki. Clicking on the URL and following the
directions it gives you enables the new account.

This default install can be customised in several ways
by providing a single function in 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
let you (the wiki administrator) do the rest.

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


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

To install:

  tar xfz emailActivation-plugin-1.0.0.tar.gz
  cp -a emailActivation-plugin-1.0.0/* /var/www/mywiki

Replace /var/www/mywiki with the path to the 
installion directory of your wiki to.

Since this plugin relies on email ensure you have defined
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.  By
default it 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 ConfirmCreateAccount.  It
should be OK but you might what to add more information to
it.  The only thing it must contain somewhere is:

  [[ConfirmCreateAccount]]

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:
  ConfirmCreateAccount_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 ConfirmCreateAccount_email(self, request, user, url):
      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 send straight to him
so he can activate it.  Otherwise it would go to the wiki
administrator.  This example should happily work is 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!

The parameters to ConfirmCreateAccount_email are:

  request  - The request instance.  It is moinmoin's central data
             structure, which you will need 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 creating the account.

  url      - This is the URL that will enable the account.  It
             should be present in the email sent.  It is a string.

If the function returns None then nothing unusual happens.
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 any of these values are omitted from the end of
the list or are None then a nice default will be used instead.
The default is usually what you would get if you didn't
supply a customisation script.

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.  This is a string.

  expire   - How long before the unactivated account will expire,
             in seconds.  This is an integer.

  message  - The message MoinMoin will display when the user
             clicks the 'Save' button.  This is a string.


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

1.  Configuration parameters defined in wikiconfig.py that are
    used by this script.   See HelpOnConfiguration for more 
    information what these do.

      data_dir
      mail_from
      mail_smarthost
      sitename

2.  This plugin overrides the userform Action.  If you have
    other plugin's that also override that Action either they
    or this plugin probably won't work.

3.  To uninstall the plugin just remove the files and directories
    created by the tar install file.

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

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

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

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



--
Russell Stuart
2007-04-02
