Package: plone.app.drafts
Introductionplone.app.drafts implements services for managing auto-saved content drafts in Plone.
This addresses two problems:If the browser is accidentally closed or crashes whilst a page is being edited, all changes are lost.Some data may need to be managed asynchronously,
e.g. via a pop-up dialogue box in the visual editor.
This data should not be saved until the form is saved
(and in the case of an add form, it is impossible to do so).The former problem pertains to any content add or edit form.
The latter applies in particular to the “tiles” model as implemented byplone.app.tilesand its dependencies.InstallationYou can install plone.app.drafts as normal,
by depending on it in yoursetup.pyor adding it to theeggslist in your buildout.
The package will self-configure for Plone; there is no need to add a ZCML slug.You will also need to install the product from the portal_quickinstaller tool or Plone’s Add-ons control panel.Draft storageAfter installation,
you should notice a new tool calledportal_draftsin the ZMI.
When drafts have been created, you can browse them here, and purge them if you believe they are stale.To access the draft storage in code, look it up as a (local) utility:>>> from zope.component import getUtility
>>> draftStorage = getUtility(IDraftStorage)The draft storage contains methods for creating, finding and discarding drafts.
This is mostly useful for integration logic.A draft is accessed by using a hierarchy of keys, all strings:The user id of the user owning the draftA unique “target object” key that represents the object being draftedA unique draft nameThe target object key is by convention a string representation of a unique integer id (viazope.intid) for drafts that represent existing content objects being edited, or a string like:'<container-intid>:<portal_type>'(e.g.'123456:Document') for drafts representing objects being added to a particular container.The draft name is unique and assigned when the draft is created.See theIDraftStorageinterface for details on how to access drafts based on these keys.The draft object itself is a minimal persistent object providing theIDraftinterface.
Importantly, it isnota full-blown content object.
It has no intrinsic security, no workflow, and no standard fields.
Itishowever annotatable, i.e. it may be adapted toIAnnotations.A draft has a few basic attributes
(__name__,_draftUserId, and_draftTargetKey),
but is otherwise a blank canvas.
Draft data may be stored as attributes, or in annotations.
The attributes that are used depends on how the draft is integrated.
The two primary patterns are:AutosaveAn explicit or timed background request submits the edit form to a handler,
which extracts the form data and saves it on the draft object,
e.g. in aformdictionary.
The draft is updated periodically.
On a successful save or cancel the draft is simply discarded.
If the user returns to the edit screen after a browser crash or abandoned session,
however, the request may be restored by copying the draft data to the realrequest.formdictionary prior to rendering the edit form.
Provided the edit form is well-behaved,
it should then show the last auto-saved values.
These values can then be edited, before they are saved as normal.Asynchronous updatesAn AJAX dialogue box can be used to configure an object asynchronously.
For example, a content type that supports attachments may use such a dialogue box to upload attached files.
These must be stored temporarily, but should not be persisted with the real content object until the underlying edit form is saved
(and should be discarded if it is cancelled).
The file upload handler can save the data to the drafts storage,
and then copy it to its final location on save.A helper function calledsyncDraftis provided for this purpose in theplone.app.drafts.utilsmodule.
It looks up any number of namedIDraftSyncermulti-adapters (on the draft object and the target content object) and calls them in turn.Current draft managementTo access the current draft from code,
use thegetCurrentDraft()helper function, passing it the current request:>>> from plone.app.drafts.utils import getCurrentDraft
>>> currentDraft = getCurrentDraft(request)This may returnNoneif there is no current draft.
It is possible that the necessary information for creating a draft (user id and target key) are known,
but that no draft has been created yet.
In this case, you can request that a new draft is created on demand, by passingcreate=True.The current draft user id, target key and (once the draft has been created) draft name are looked up from the request, by adapting it to the interfaceICurrentDraftManagement.
You should not normally need to use this yourself, unless you are integrating the draft storage with an external framework.The defaultICurrentDraftManagementadapter allows the user id, target key and draft name to be set explicitly.
If they are not set, they are read from the request.
This means that they may come in request parameters, or in cookies.
The request keys areplone.app.drafts.targetKeyandplone.app.drafts.draftName.
The user id always defaults to the currently logged in user’s id.TheICurrentDraftManagementadapter also exposes lifecycle functions that can save or discard the current draft information.
The default implementation does this using cookies that are set for a path corresponding to the edit page.
It is the responsibility of the add/edit form integration code to ensure that this cookie is set for a path that is specific enough not to “leak” to other edit pages,
but still allows AJAX dialogue boxes and other asynchronous requests to obtain the draft information if required.IntegrationArchetypes integration is provided in thearchetypesmodule,
which is configured if Archetypes is installed.
The integration works as follows:AnIEditBegunEventis fired by Archetypes when the user enters an add/edit form.
An event handler for this event will calculate a target key for the context, taking “add forms” based on theportal_factorytool into account.
Provided a key can be calculated, it is saved via anICurrentDraftManagementadapter as explained below.
A draft is not created immediately, but if a single draft is discovered in the storage for this user id and key,
that draft name is saved so that it will be returned whengetCurrentDraft()is called.
The cookie path is calculated as well and saved.
This ensures that if the draft is created in an asynchronous request with a “deeper” URL, the cookie path will be the same.An event handler is installed forIObjectInitializedEventandIObjectEditedEvent, which are fired when the user clicksSaveon a valid  add or edit form, respectively.
This handler will get the current draft if it has been created during the editing cycle, and uses thesyncDraft()method to synchronise it as necessary.
The draft is then discarded, as is the current draft information, causing the cookies to expire.An event handler is also installed forIEditCancelledEvent, which is fired when the user clicksCancel.
This simply discards the draft and current draft information without synchronisation.The draft proxySimple drafting integration will tend to just store data on the draft object directly.
However, it may sometimes be useful to have an object that behaves as a facade onto a “real” object, so that:If an attribute or annotation value that has never been set on the draft is read, the value from the underlying target object is used.If an attribute or annotation value is set, it is written to the draft.
If it is subsequently read, it is read from the draft.If an attribute or annotation value is deleted,
it is deleted from the draft, and the fact that it was deleted is recorded so that this may be later synchronised with the underlying object when the draft is “saved”
(e.g. via anIDraftSynceradapter).To get these semantics, create aDraftProxyobject like so:>>> from plone.app.drafts.proxy import DraftProxy
>>> proxy = DraftProxy(draft, target)Here,draftis anIDraftobject andtargetis the object it is a draft of.
If attributes are deleted, they will be stored in one of two sets:>>> deletedAttributes = getattr(draft, '_proxyDeleted', set())
>>> deletedAnnotations = getattr(draft, '_proxyAnnotationsDeleted', set())Note that these attributes may not be present if nothing has ever been deleted,
so we need to fetch them defensively.Changelog2.0.0 (2022-07-22)remove Archetypes. This version targets Plone 5.2+ with Python 3.6+ only.Fix class security warnings
[petschki]1.1.3 (2019-02-10)Python 3 compatible
[vangheem, petschki]1.1.2 (2017-07-03)Fix issue where draft sync failed because draft might have been withotu aq wrapper
[datakurre]1.1.1 (2016-09-09)Remove forgotten debug print
[datakurre]1.1.0 (2016-09-09)Add support for drafted content preview for Dexterity content when request is
marked with IDisplayFormDrafting
[datakurre]Fix not set cookie values twice
[vangheem]Fix to always sync drafts before object modified event subscribers
(especially indexing) are called
[datakurre]Behavior shortnameplone.draftableadded.
[jensens, datakurre]Update testing infrastructure and fix code analysis errors.
[gforcada]1.0 (2016-03-28)Make sure draft is available before initializing the draft proxy object
[vangheem]1.0b3 (2015-06-10)Fix issue where drafting caused ‘AttributeError: This object has no id’
[datakurre]Fix issue where add forms with different content type but the context had conflicting draft
[datakurre]1.0b2 (2015-06-02)Fix rare issue where Dexterity draft had wrong portal_type
[datakurre]1.0b1 (2015-05-26)Add support for drafting on Dexterity add and edit forms
when the drafting behavior is enabled for the content type
[datakurre]Add autosave (using AJAX validation calls) support for
Dexterity add and edit forms when drafting behavior is
enabled for the content type
[datakurre]Change to use UUIDs instead of intids
[datakurre]Change Archetypes-support to be disabled by default
[datakurre]Archetypes-support can included in zcml with:<include package="plone.app.drafts" file="archetypes.zcml" />1.0a2 (2011-10-11)Added MANIFEST.in to fix our previous release. It was missing the history file.1.0a1 (2011-10-10)Initial release.