MoinMoin: attachment:README-emailActivation-1.0.1.txt of RussellStuart/EmailActivation

   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.  Instead of a new account being
   9 usable immediately it is initially disabled and must be
  10 enabled via a special URL.  The URL is emailed to the
  11 address entered when the account was created.
  12 
  13 This default install can be customised in several ways by
  14 providing a single function in wiki configuration script.
  15 The details of how to do this are described below.
  16 
  17 The most useful thing to change is who gets the email.
  18 Typical usage is to allow people you trust to activate
  19 themselves, forwarding the rest onto the wiki administrator.
  20 Example: you might choose to let people who entered an
  21 email address from your company activate themselves, but
  22 require you to authorise the rest.
  23 
  24 The plugin was developed and tested with MoinMoin 1.5.6.
  25 It is moderately intrusive and so may not work with other
  26 versions.
  27 
  28 
  29 Installation
  30 ------------
  31 
  32 To install:
  33 
  34   tar xfz emailActivation-plugin-1.0.0.tar.gz
  35   cp -a emailActivation-plugin-1.0.0/* /var/www/mywiki
  36 
  37 Replace /var/www/mywiki with the installion directory of
  38 your wiki.
  39 
  40 Since this plugin relies on email ensure you have defined
  41 the 'mail_smarthost' parameter in the wiki configuration.
  42 See HelpOnConfiguration for more information on how to do
  43 that.
  44 
  45 
  46 Customisation
  47 -------------
  48 
  49 It is a good idea to change the UserPreferences page to say
  50 what will happen when the user creates the account.  By
  51 default it says they will be able to use the account as soon
  52 as it is created.  That won't be the case after you install
  53 this plugin.
  54 
  55 The plugin installs a page called ConfirmCreateAccount.  It
  56 should be OK but you might what to add more information to
  57 it.  The only thing it must contain somewhere is:
  58 
  59   [[ConfirmCreateAccount]]
  60 
  61 Finally there is the customisation script.  This is where
  62 the real action happens.  It lives in the wiki instance
  63 script.  You created this script when you followed the
  64 instructions in HelpOnInstalling/WikiInstanceCreation.
  65 Those instructions refer to it as $INSTANCE, and in the
  66 examples it is called 'wikiconfig.py'.  This script is also
  67 the file you modify when following the help in
  68 HelpOnConfiguration.
  69 
  70 The customisation script is a function called:
  71   ConfirmCreateAccount_email
  72 You add it to the 'Config' class already defined in the wiki
  73 instance script.  Usually this just means appending a few
  74 lines to the end of the script file.  Be careful to keep the
  75 indentation as is: it is important!  A typical example of a
  76 modified wikiconfig.py:
  77 
  78 #
  79 # :
  80 # : Here lives lots of comments and stuff that come with the
  81 # : default version of wikiconfig.py.
  82 # :
  83 #
  84 
  85 # now we subclass that config (inherit from it) and change what's different:
  86 class Config(FarmConfig):
  87     # basic options (you normally need to change these)
  88     sitename = u'MyWiki' # [Unicode]
  89     interwikiname = 'MyWiki'
  90     #
  91     # :
  92     # : other stuff defined in wikiconfig.py that doesn't concern us
  93     # :
  94     #
  95     # ------------ Lines below are the ones added -----------
  96     def ConfirmCreateAccount_email(self, request, user, url):
  97       if user.email.endswith("@my-company.com") or user.email.endswith("@my-company.com>"):
  98 	to = user.email
  99       else:
 100 	to = request.cfg.mail_from
 101       return [to]
 102 
 103 In this example if the email address entered by the user
 104 ended in "@my-company.com", the email would be send straight
 105 to him so he can activate it.  Otherwise it would go to the
 106 wiki administrator.  This example should happily work if you
 107 just paste it into your wikiconfig.py file, and alter the
 108 email address to suite.  Again, be sure to get the
 109 indentation right.  Use spaces for indenting to avoid
 110 confusion.
 111 
 112 The parameters to ConfirmCreateAccount_email are:
 113 
 114   request  - The request instance.  It is moinmoin's central
 115              data structure. You will need it if you are
 116 	     going to do something tricky.
 117 
 118   user     - An instance of MoinMoin.user.User().  This
 119              holds the data entered by the user into the
 120 	     UserPreferences page when the account was
 121 	     created.
 122 
 123   url      - This is the URL that will enable the account.
 124              It should be present in the email sent.  It is
 125 	     a string.
 126 
 127 If the function returns None then the account is created as
 128 if the plugin wasn't installed.  This means the account is
 129 created normally (ie not disabled) and no email is sent.  
 130 
 131 Otherwise the return value must be a list containing up to 5
 132 values.  If values on the end of the list are omitted (ie
 133 the list contains less that 5 values) or if a value is None
 134 then the default will be used instead.  The default is
 135 usually what you would get if you didn't supply a
 136 customisation script.  In fact not supplying a script is
 137 identical to having one that returns [].
 138 
 139 The elements of the returned list are:
 140 
 141   [to, subject, text, expire, message]
 142 
 143 They are used like this:
 144 
 145   to       - The email addresses to send the email to.  This
 146              can be a single string containing one email
 147 	     address, or a list of them.
 148 
 149   subject  - The subject of the email.  This is a string.
 150 
 151   text     - The body of the email.  It must be normal text
 152              (ie conform to mine type text/plain).  This is
 153 	     a string.
 154 
 155   expire   - How long before the unactivated account will
 156              expire, in seconds.  This is an integer.
 157 
 158   message  - The message MoinMoin will display when the user
 159              clicks the 'Save' button.  This is a string.
 160 
 161 
 162 Other Notes
 163 ===========
 164 
 165 1.  Here are the configuration parameters used by the
 166     script.  These are the parameters defined in
 167     wikiconfig.py.  See HelpOnConfiguration for more
 168     information what they do.
 169 
 170       data_dir
 171       mail_from
 172       mail_smarthost
 173       sitename
 174 
 175 2.  This plugin overrides the userform Action.  If you have
 176     installed other plugin's that also override userform it
 177     is likely something will break.
 178 
 179 3.  To uninstall the plugin just remove the files and
 180     directories created by the tar install file.
 181 
 182 4.  Expired accounts that have not been activated are
 183     deleted the next time someone tries to confirm or cancel
 184     a new account.
 185 
 186 5.  Anybody can delete an unactivated account by going to
 187     this URL:
 188 
 189       http://www.mywiki.site/mywiki/ConfirmCreateAccount?n=UserName
 190 
 191     where UserName is the name entered the UserPreferences
 192     for the page you wish to delete.
 193 
 194 
 195 
 196 --
 197 Russell Stuart
 198 2007-04-02
 199 
 200 
 201 
 202 
 203 ChangeLog
 204 =========
 205 
 206 emailActivate-1.0.1 2007-04-03
 207 
 208   - Allowed email destination to be a list.
 209   - Cleaned up wording in README.