1 The EmailActivation MoinMoin Plugin
   2 ===================================
   3 
   4 Overview of what it does
   5 ------------------------
   6 
   7 This plugin alters the way new accounts are created by the
   8 UserPreferences page.  Newly created accounts are initially
   9 disabled and must be enabled via a special URL.  The URL is
  10 emailed to the address entered when the account was created.
  11 Once the account has been activated the user is sent a
  12 second email inviting them to log in.
  13 
  14 A MoinMoin superuser can view all unactivated accounts and
  15 activate or cancel them.  If the account isn't activated
  16 with one week it will expire and be cancelled.  Cancelling
  17 an unactivated account deletes it, thus freeing the account
  18 name and email address for re-use.  An unactivated account
  19 can also be cancelled via the emailed URL.
  20 
  21 This default install can be customised in several ways by
  22 providing a single function in wiki configuration script.
  23 The details of how to do this are described below.
  24 
  25 The most useful thing to change is who gets the email.
  26 Typical usage is to allow people you trust to activate
  27 themselves, forwarding the rest onto the wiki administrator.
  28 Example: you might choose to let people who entered an
  29 email address from your company activate themselves, but
  30 require you to authorise the rest.
  31 
  32 The plugin was developed and tested with MoinMoin 1.5.6.
  33 It was altered to work with 1.5.8.  It is moderately
  34 intrusive and so may not work with other versions.
  35 
  36 
  37 Installation
  38 ------------
  39 
  40 To install:
  41 
  42   tar xpfz emailActivation-plugin-VERSION.tar.gz
  43   cp -a emailActivation-plugin-VERSION/* /var/www/mywiki
  44 
  45 Replace /var/www/mywiki with the installation directory of
  46 your wiki.
  47 
  48 To be safe it is wise to uninstall the previous version
  49 before installing a new one.  To uninstall the plugin
  50 just remove the files and directories created by the tar
  51 install file.
  52 
  53 Upgrading from version 1.0.x: this upgrade is not backward
  54 compatible.  To upgrade Cancel all unactivated accounts
  55 before upgrading, and be sure to do an uninstall first!
  56 
  57 Since this plugin relies on email ensure you have defined
  58 the 'mail_smarthost' parameter in the wiki configuration.
  59 See HelpOnConfiguration for more information on how to do
  60 that.
  61 
  62 
  63 Customisation
  64 -------------
  65 
  66 It is a good idea to change the UserPreferences page to say
  67 what will happen when the user creates the account.  The
  68 default one says they will be able to use the account as
  69 soon as it is created.  That won't be the case after you
  70 install this plugin.
  71 
  72 The plugin installs a page called EmailActivation.  It
  73 should be OK but you might what to add more information to
  74 it.  The only thing it must contain somewhere is:
  75 
  76   [[EmailActivation]]
  77 
  78 Finally there is the customisation script.  This is where
  79 the real action happens.  It lives in the wiki instance
  80 script.  You created this script when you followed the
  81 instructions in HelpOnInstalling/WikiInstanceCreation.
  82 Those instructions refer to it as $INSTANCE, and in the
  83 examples it is called 'wikiconfig.py'.  This script is also
  84 the file you modify when following the help in
  85 HelpOnConfiguration.
  86 
  87 The customisation script is a function called:
  88   EmailActivation_email
  89 You add it to the 'Config' class already defined in the wiki
  90 instance script.  Usually this just means appending a few
  91 lines to the end of the script file.  Be careful to keep the
  92 indentation as is: it is important!  A typical example of a
  93 modified wikiconfig.py:
  94 
  95 #
  96 # :
  97 # : Here lives lots of comments and stuff that come with the
  98 # : default version of wikiconfig.py.
  99 # :
 100 #
 101 
 102 # now we subclass that config (inherit from it) and change what's different:
 103 class Config(FarmConfig):
 104     # basic options (you normally need to change these)
 105     sitename = u'MyWiki' # [Unicode]
 106     interwikiname = 'MyWiki'
 107     #
 108     # :
 109     # : other stuff defined in wikiconfig.py that doesn't concern us
 110     # :
 111     #
 112     # ------------ Lines below are the ones added -----------
 113     def EmailActivation_email(self, action, request, user, url):
 114       if action != 'create':
 115         return []
 116       if user.email.endswith("@my-company.com") or user.email.endswith("@my-company.com>"):
 117 	to = user.email
 118       else:
 119 	to = request.cfg.mail_from
 120       return [to]
 121 
 122 In this example if the email address entered by the user
 123 ended in "@my-company.com", the email would be sent straight
 124 to him so he can activate it.  Otherwise it would go to the
 125 wiki administrator.  This example should happily work if you
 126 just paste it into your wikiconfig.py file, and alter the
 127 email address to suite.  Again, be sure to get the
 128 indentation right.  Use spaces for indenting to avoid
 129 confusion.
 130 
 131 The parameters to EmailActivation_email are:
 132 
 133   action   - This is the string 'create' if the account is
 134              being created, 'activate' if the account 
 135 	     has been successfully activated, or 'cancel'
 136 	     if the activation has been cancelled.  'cancel'
 137 	     is sent when the new account is explicitly
 138 	     cancelled.  No email is sent if the unactivated
 139 	     account expires.
 140 
 141   request  - The request instance.  It is moinmoin's central
 142              data structure. You will need it if you are
 143 	     going to do something tricky.
 144 
 145   user     - An instance of MoinMoin.user.User().  This
 146              holds the data entered by the user into the
 147 	     UserPreferences page when the account was
 148 	     created.
 149 
 150   url      - For 'create' this is the URL that will enable
 151   	     the account.  It should be present in the email
 152 	     sent.  It is a string.  For 'activated' this is
 153 	     the url the user should use to login.  For
 154 	     'cancelled' this is the empty string.
 155 
 156 If the function returns None then the account things proceed
 157 as if the plugin wasn't installed.  This means the account
 158 is created normally (ie not disabled) and no email is sent.
 159 
 160 Otherwise the return value must be a list containing up to 5
 161 values.  If values on the end of the list are omitted (ie
 162 the list contains less that 5 values) or if a value is None
 163 then the default will be used instead.  The default is
 164 usually what you would get if you didn't supply a
 165 customisation script.  In fact not supplying a script is
 166 identical to having one that returns [].  The default is to
 167 not send an email when an activation request is cancelled.
 168 You can change this to send a reasonable email by returning
 169 [None].
 170 
 171 The elements of the returned list are:
 172 
 173   [to, subject, text, expire, message]
 174 
 175 They are used like this:
 176 
 177   to       - The email addresses to send the email to.  This
 178              can be a single string containing one email
 179 	     address, or a list of them.
 180 
 181   subject  - The subject of the email.  This is a string.
 182 
 183   text     - The body of the email.  It must be normal text
 184              (ie conform to mine type text/plain).  This is
 185 	     a string.
 186 
 187   expire   - How long before the unactivated account will
 188              expire, in seconds.  This is an integer.  It
 189 	     is ignored when the action parameter isn't
 190 	     'create'.
 191 
 192   message  - The message MoinMoin will display when the user
 193              clicks the 'Save' button.  This is a string.
 194 	     This is ignored when the action parameter isn't
 195 	     'create'.
 196 
 197 
 198 Other Notes
 199 ===========
 200 
 201 1.  Here are the configuration parameters used by the
 202     script.  These are the parameters defined in
 203     wikiconfig.py.  See HelpOnConfiguration for more
 204     information what they do.
 205 
 206       data_dir
 207       mail_from
 208       mail_smarthost
 209       sitename
 210 
 211 2.  This plugin overrides the userform Action.  If you have
 212     installed other plugin's that also override userform it
 213     is likely something will break.
 214 
 215 3.  If a superuser visits:
 216 
 217       http://www.mywiki.site/mywiki/EmailActivation
 218 
 219     they will see all unactivated accounts and can confirm
 220     or cancel them.
 221 
 222 4.  Expired accounts that have not been activated are
 223     deleted the next time someone tries to activate or cancel
 224     a new account.
 225 
 226 5.  Anybody can delete an unactivated account by going to
 227     this URL:
 228 
 229       http://www.mywiki.site/mywiki/EmailActivation?n=UserName
 230 
 231     where UserName is the name entered the UserPreferences
 232     for the page you wish to delete.
 233 
 234 
 235 
 236 --
 237 Russell Stuart
 238 2007-09-27
 239 
 240 
 241 
 242 
 243 ChangeLog
 244 =========
 245 
 246 emailActivation-1.1.4 2007-11-24
 247 
 248   - A couple of spelling mistakes spotted by Peter Chubb fixed.
 249 
 250 emailActivation-1.1.3 2007-11-22
 251 
 252   - By faking a create user account request a spammer could by-pass
 253     EmailActivation.  Not quite so trusting of the form variables
 254     sent by the browser now.
 255 
 256 emailActivation-1.1.2 2007-09-26
 257 
 258   - Made changes as described by StephenEdwards so it would work
 259     under MoinMoin 1.5.8.
 260 
 261 emailActivation-1.1.1 2007-04-10
 262 
 263   - Reformatted code to bring it in line with MoinMoin coding style
 264     as per ThomasWaldmann's request.  No functional changes.
 265 
 266 emailActivation-1.1.0 2007-04-07
 267 
 268   - Fixed bug in account expiry.  This bug probably meant it
 269     didn't work at all - sorry!
 270   - If a superuser views the EmailActivation page a
 271     list of outstanding activations is shown, and they can
 272     be confirmed or cancelled.
 273   - An email is now sent when the account is activated.
 274   - An email can now be sent when the account activation is
 275     cancelled.
 276   - Renamed lots of things to create a more consistent
 277     naming scheme.
 278 
 279 emailActivation-1.0.1 2007-04-03
 280 
 281   - Allowed email destination to be a list.
 282   - Cleaned up wording in README.