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

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

This plugin alters the way new accounts are created by the
UserPreferences page.  Instead of a new account being
usable immediately it is initially disabled and must be
enabled via a special URL.  The URL is emailed to the
address entered when the account was created.

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 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 installion directory of
your wiki.

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 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 ConfirmCreateAccount_email are:

  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      - 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 the account is created 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 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.

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


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.  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




ChangeLog
=========

emailActivate-1.0.1 2007-04-03

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