Package: collective.depositbox
IntroductionThis is a small package for Zope2 that does something similar to a
part of what the PasswordResetTool from Plone does.  It stores a
value, with a possible validation token, and guards it with a secret.The PasswordResetTool uses a similar technique to store password reset
requests; it then sends an email with a link and a generated secret to
a given email address.  When the recipient follows the link and fills
in the secret (this is actually part of the link so this is done
implicitly) and his user name (the validation token) he is allowed to
set a fresh password.This package is meant to support this and similar use cases.  The part
this package does is:storing the value (done with annotations)possibly confirming in case there is a validation tokengetting the valueediting the valueremoving the valueNo emails are sent.  If that is needed for a use case, that is the
responsibility of integrators.Target audienceTarget audience is integrators, as the package does not really do
anything interesting for end users.  You will have to build something
around it.  This could be as easy as a PloneFormGen form.  Here are
some possible use cases.You could use this to store an email address that needs to be
confirmed before adding it to a mailing list.Or you generate 1,000 secrets, print them, hand them out on a trade
show, and give people 5 euro when they register on your website with
this secret; perhaps you could cobble something like this together
in combination with PloneFormGen.DependenciesTested with Plone 3.3.5, 4.0.9, 4.1, 4.2, 4.3.6, 5.0.
Might work in Plone 2.5 already.
Probably works in plain Zope2 as well.InstallAdd this to the eggs of your buildout.  On Plone 3.2 or lower also
load the zcml (done automatically in 3.3 or higher).Sample usageThere are some sample browser views in the sample directory of the
package.  If you want to use them in a test instance, load their
zcml; in a buildout config that would be something like this:[instance]
...
zcml =
    ...
    collective.depositbox.sampleRerun buildout, start the instance, and in the root of the site (or
somewhere else) visit@@deposit-simpleor@@deposit-add.  If
you follow the instructions of the last one you will add, confirm,
edit and delete an item.Sample codeThis should give you an idea of how you should use the code:>>> from collective.depositbox.store import Box
>>> box = Box()
>>> secret = box.put(object())
>>> box.get(secret)
<object object at ...>
>>> box.edit(secret, 42)
>>> box.get(secret)
42
>>> box.pop(secret)
42
>>> box.pop(secret)
>>> secret = box.put('my data', token='maurits@example.com')
>>> box.get(secret, token='maurits@example.com') is None
True
>>> box.confirm(secret, token='maurits@example.com')
True
>>> box.get(secret, token='maurits@example.com')
'my data'
>>> box.get(secret, token='bad@example.com') is None
True
>>> box.pop(secret) is None
True
>>> box.pop(secret, token='maurits@example.com')
'my data'Storing data persistentlyIf you instantiate aBox()like above, but do not add the box to
some object in the database, then you will lose your data once your
Plone Site restarts.  The normal way to save the box is to use an
adapter to store it in annotations on the context:from collective.depositbox.interfaces import IDepositBox
box = IDepositBox(context)That context can be the Plone Site root, a folder, a document or
whatever you want.  You can have multiple boxes: different contexts
will have different boxes.  A secret for one box is not valid for
another box.ExpiringNote that after a while (7 days by default) the secret expires and the
data is removed.IntegratorsThe default adapter is registered for anything that is
IAttributeAnnotatable, which is true for any content item in Plone.
It adds one deposit box on the context.  This may be fine for your use
case, but maybe you want something else.  So here are a few ideas.Look inconfig.pyfor some settings you could easily override in a
monkey patch.Maybe replace the randomid_generatorusing a monkey patch if
you don’t like the secrets that are generated.  Secrets are
currently 8 characters from the lowercase alphabet or digits.  We
avoid accidentally creating (swear) words by excluding vowels, and
avoid further confusion by excluding 0 and 1.  8 characters sampled
from these 28 characters give 125 billion possible results.  That is
enough for 1 random key every second for almost 4000 years.  If you
want some uuid thingie instead that is fine.  I like that the secret
is short so that you can safely include it as part of a url in an
email without making the link too long, which can lead to problems
in some email programs.You could register your own adapter that inherits fromBoxAdapter.  You can then overrideANNO_KEYso you can store
a box under a different name.  Withmax_ageyou can determine
the number of days before a secret expires.  Similarly, with
purge_days you can determine how often old items get purged.  Maybe
register this adapter specifically for IPloneSiteRoot.You can add a value in the deposit box and get the secret back in a
page template with a TAL definition like this:depositview nocall:context/@@deposit-box;
secret python:depositview.put('foobar');For a slightly bigger example seecollective/depositbox/sample/templates/simple.pt.Changelog1.3 (2015-09-01)Added documentation about using theIDepositBoxadapter.
[maurits]1.2 (2014-08-04)Add locales, with Dutch translations.
[maurits]Add simpledeposit-box-dataview to see confirmed data.  You may
want to override this in your own code with some view that presents
it in a nicer way because it knows what kind of values are stored.
[maurits]Add permissioncollective.depositbox: View Data.  Allow access
toget_all_confirmeddata when the user has this permission.
We do not grant the permission explicitly, so by default only a
Manager has it.
[maurits]1.1 (2012-09-13)Moved to github:https://github.com/collective/collective.depositbox[maurits]1.0 (2011-08-13)Initial release.
[maurits]