doc/book/en/additionnal_services/undo.rst
author Anthony Truchet <anthony.truchet@logilab.fr>
Tue, 21 Feb 2012 18:23:23 +0100
changeset 8698 b2443e266661
permissions -rw-r--r--
[doc] Book entry for the undo functionnality.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
8698
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
     1
Undoing changes in CubicWeb
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
     2
---------------------------
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
     3
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
     4
Many desktop applications offer the possibility for the user to
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
     5
undo its last changes : this *undo feature* has now been
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
     6
integrated into the CubicWeb framework. This document will
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
     7
introduce you to the *undo feature* both from the end-user and the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
     8
application developer point of view.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
     9
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    10
But because a semantic web application and a common desktop
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    11
application are not the same thing at all, especially as far as
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    12
undoing is concerned, we will first introduce *what* is the *undo
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    13
feature* for now.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    14
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    15
What's *undoing* in a CubicWeb application
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    16
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    17
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    18
What is an *undo feature* is quite intuitive in the context of a
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    19
desktop application. But it is a bit subtler in the context of a
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    20
Semantic Web application. This section introduces some of the main
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    21
differences between a classical desktop and a Semantic Web
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    22
applications to keep in mind in order to state precisely *what we
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    23
want*.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    24
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    25
The notion transactions
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    26
```````````````````````
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    27
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    28
A CubicWeb application acts upon an *Entity-Relationship* model,
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    29
described by a schema. This allows to ensure some data integrity
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    30
properties. It also implies that changes are made by all-or-none
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    31
groups called *transactions*, such that the data integrity is
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    32
preserved whether the transaction is completely applied *or* none
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    33
of it is applied.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    34
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    35
A transaction can thus include more actions than just those
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    36
directly required by the main purpose of the user.  For example,
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    37
when a user *just* writes a new blog entry, the underlying
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    38
*transaction* holds several *actions* as illustrated below :
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    39
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    40
* By admin on 2012/02/17 15:18 - Created Blog entry : Torototo
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    41
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    42
  #. Created Blog entry : Torototo
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    43
  #. Added relation : Torototo owned by admin
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    44
  #. Added relation : Torototo blog entry of Undo Blog
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    45
  #. Added relation : Torototo in state draft (draft)
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    46
  #. Added relation : Torototo created by admin
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    47
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    48
Because of the very nature (all-or-none) of the transactions, the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    49
"undoable stuff" are the transactions and not the actions !
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    50
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    51
Public and private actions within a transaction
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    52
```````````````````````````````````````````````
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    53
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    54
Actually, within the *transaction* "Created Blog entry :
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    55
Torototo", two of those *actions* are said to be *public* and
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    56
the others are said to be *private*. *Public* here means that the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    57
public actions (1 and 3) were directly requested by the end user ;
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    58
whereas *private* means that the other actions (2, 4, 5) were
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    59
triggered "under the hood" to fulfill various requirements for the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    60
user operation (ensuring integrity, security, ... ).
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    61
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    62
And because quite a lot of actions can be triggered by a "simple"
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    63
end-user request, most of which the end-user is not (and does not
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    64
need or wish to be) aware, only the so-called public actions will
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    65
appear [1]_ in the description of the an undoable transaction.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    66
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    67
* By admin on 2012/02/17 15:18 - Created Blog entry : Torototo
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    68
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    69
  #. Created Blog entry : Torototo
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    70
  #. Added relation : Torototo blog entry of Undo Blog
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    71
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    72
But note that both public and private actions will be undone
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    73
together when the transaction is undone.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    74
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    75
(In)dependent transactions : the simple case
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    76
````````````````````````````````````````````
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    77
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    78
A CubicWeb application can be used *simultaneously* by different users
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    79
(whereas a single user works on an given office document at a
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    80
given time), so that there is not always a single history
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    81
time-line in the CubicWeb case. Moreover CubicWeb provides
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    82
security through the mechanism of *permissions* granted to each
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    83
user. This can lead to some transactions *not* being undoable in
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    84
some contexts.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    85
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    86
In the simple case two (unprivileged) users Alice and Bob make
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    87
relatively independent changes : then both Alice and Bob can undo
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    88
their changes. But in some case there is a clean dependency
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    89
between Alice's and Bob's actions or between actions of one of
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    90
them. For example let's suppose that :
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    91
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    92
- Alice has created a blog,
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    93
- then has published a first post inside,
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    94
- then Bob has published a second post in the same blog,
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    95
- and finally Alice has updated its post contents.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    96
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    97
Then it is clear that Alice can undo her contents changes and Bob
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    98
can undo his post creation independently. But Alice can not undo
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
    99
her post creation while she has not first undone her changes.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   100
It is also clear that Bob should *not* have the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   101
permissions to undo any of Alice's transactions.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   102
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   103
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   104
More complex dependencies between transactions
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   105
``````````````````````````````````````````````
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   106
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   107
But more surprising things can quickly happen. Going back to the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   108
previous example, Alice *can* undo the creation of the blog after
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   109
Bob has published its post in it ! But this is possible only
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   110
because the schema does not *require* for a post to be in a
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   111
blog. Would the *blog entry of* relation have been mandatory, then
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   112
Alice could not have undone the blog creation because it would
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   113
have broken integrity constraint for Bob's post.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   114
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   115
When a user attempts to undo a transaction the system will check
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   116
whether a later transaction has explicit dependency on the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   117
would-be-undone transaction. In this case the system will not even
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   118
attempt the undo operation and inform the user.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   119
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   120
If no such dependency is detected the system will attempt the undo
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   121
operation but it can fail, typically because of integrity
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   122
constraint violations. In such a case the undo operation is
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   123
completely [3]_ rollbacked.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   124
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   125
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   126
The *undo feature* for CubicWeb end-users
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   127
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   128
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   129
The exposition of the undo feature to the end-user through a Web
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   130
interface is still quite basic and will be improved toward a
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   131
greater usability. But it is already fully functional.  For now
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   132
there are two ways to access the *undo feature* as long as the it
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   133
has been activated in the instance configuration file with the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   134
option *undo-support=yes*.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   135
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   136
Immediately after having done the change to be canceled through
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   137
the **undo** link in the message. This allows to undo an
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   138
hastily action immediately. For example, just after having
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   139
validated the creation of the blog entry *A second blog entry* we
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   140
get the following message, allowing to undo the creation.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   141
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   142
.. image:: /images/undo_mesage_w600.png
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   143
   :width: 600px
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   144
   :alt: Screenshot of the undo link in the message
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   145
   :align: center
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   146
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   147
At any time we can access the **undo-history view** accessible from the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   148
start-up page.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   149
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   150
.. image:: /images/undo_startup-link_w600.png
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   151
   :width: 600px
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   152
   :alt: Screenshot of the startup menu with access to the history view
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   153
   :align: center
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   154
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   155
This view will provide inspection of the transaction and their (public)
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   156
actions. Each transaction provides its own **undo** link. Only the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   157
transactions the user has permissions to see and undo will be shown.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   158
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   159
.. image:: /images/undo_history-view_w600.png
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   160
   :width: 600px
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   161
   :alt: Screenshot of the undo history main view
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   162
   :align: center
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   163
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   164
If the user attempts to undo a transaction which can't be undone or
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   165
whose undoing fails, then a message will explain the situation and
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   166
no partial undoing will be left behind.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   167
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   168
This is all for the end-user side of the undo mechanism : this is
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   169
quite simple indeed ! Now, in the following section, we are going
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   170
to introduce the developer side of the undo mechanism.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   171
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   172
The *undo feature* for CubicWeb application developers
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   173
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   174
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   175
A word of warning : this section is intended for developers,
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   176
already having some knowledge of what's under CubicWeb's hood. If
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   177
it is not *yet* the case, please refer to CubicWeb documentation
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   178
http://docs.cubicweb.org/ .
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   179
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   180
Overview
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   181
````````
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   182
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   183
The core of the undo mechanisms is at work in the *native source*,
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   184
beyond the RQL. This does mean that *transactions* and *actions*
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   185
are *no entities*. Instead they are represented at the SQL level
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   186
and exposed through the *DB-API* supported by the repository
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   187
*Connection* objects.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   188
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   189
Once the *undo feature* has been activated in the instance
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   190
configuration file with the option *undo-support=yes*, each
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   191
mutating operation (cf. [2]_) will be recorded in some special SQL
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   192
table along with its associated transaction. Transaction are
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   193
identified by a *txuuid* through which the functions of the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   194
*DB-API* handle them.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   195
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   196
On the web side the last commited transaction *txuuid* is
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   197
remembered in the request's data to allow for imediate undoing
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   198
whereas the *undo-history view* relies upon the *DB-API* to list
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   199
the accessible transactions. The actual undoing is performed by
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   200
the *UndoController* accessible at URL of the form
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   201
`www.my.host/my/instance/undo?txuuid=...`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   202
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   203
The repository side
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   204
```````````````````
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   205
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   206
Please refer to the file `cubicweb/server/sources/native.py` and
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   207
`cubicweb/transaction.py` for the details.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   208
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   209
The undoing information is mainly stored in three SQL tables:
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   210
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   211
`transactions`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   212
    Stores the txuuid, the user eid and the date-and-time of
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   213
    the transaction. This table is referenced by the two others.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   214
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   215
`tx_entity_actions`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   216
    Stores the undo information for actions on entities.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   217
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   218
`tx_relation_actions`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   219
    Stores the undo information for the actions on relations.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   220
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   221
When the undo support is activated, entries are added to those
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   222
tables for each mutating operation on the data repository, and are
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   223
deleted on each transaction undoing.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   224
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   225
Those table are accessible through the following methods of the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   226
repository `Connection` object :
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   227
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   228
`undoable_transactions`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   229
    Returns a list of `Transaction` objects accessible to the user
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   230
    and according to the specified filter(s) if any.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   231
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   232
`tx_info`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   233
    Returns a `Transaction` object from a `txuuid`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   234
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   235
`undo_transaction`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   236
    Returns the list of `Action` object for the given `txuuid`.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   237
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   238
    NB:  By default it only return *public* actions.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   239
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   240
The web side
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   241
````````````
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   242
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   243
The exposure of the *undo feature* to the end-user through the Web
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   244
interface relies on the *DB-API* introduced above. This implies
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   245
that the *transactions* and *actions* are not *entities* linked by
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   246
*relations* on which the usual views can be applied directly.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   247
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   248
That's why the file `cubicweb/web/views/undohistory.py` defines
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   249
some dedicated views to access the undo information :
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   250
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   251
`UndoHistoryView`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   252
    This is a *StartupView*, the one accessible from the home
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   253
    page of the instance which list all transactions.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   254
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   255
`UndoableTransactionView`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   256
    This view handles the display of a single `Transaction` object.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   257
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   258
`UndoableActionBaseView`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   259
    This (abstract) base class provides private methods to build
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   260
    the display of actions whatever their nature.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   261
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   262
`Undoable[Add|Remove|Create|Delete|Update]ActionView`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   263
    Those views all inherit from `UndoableActionBaseView` and
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   264
    each handles a specific kind of action.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   265
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   266
`UndoableActionPredicate`
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   267
    This predicate is used as a *selector* to pick the appropriate
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   268
    view for actions.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   269
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   270
Apart from this main *undo-history view* a `txuuid` is stored in
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   271
the request's data `last_undoable_transaction` in order to allow
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   272
immediate undoing of a hastily validated operation. This is
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   273
handled in `cubicweb/web/application.py` in the `main_publish` and
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   274
`add_undo_link_to_msg` methods for the storing and displaying
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   275
respectively.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   276
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   277
Once the undo information is accessible, typically through a
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   278
`txuuid` in an *undo* URL, the actual undo operation can be
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   279
performed by the `UndoController` defined in
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   280
`cubicweb/web/views/basecontrollers.py`. This controller basically
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   281
extracts the `txuuid` and performs a call to `undo_transaction` and
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   282
in case of an undo-specific error, lets the top level publisher
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   283
handle it as a validation error.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   284
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   285
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   286
Conclusion
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   287
~~~~~~~~~~
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   288
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   289
The undo mechanism relies upon a low level recording of the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   290
mutating operation on the repository. Those records are accessible
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   291
through some method added to the *DB-API* and exposed to the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   292
end-user either through a whole history view of through an
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   293
immediate undoing link in the message box.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   294
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   295
The undo feature is functional but the interface and configuration
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   296
options are still quite reduced. One major improvement would be to
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   297
be able to filter with a finer grain which transactions or actions
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   298
one wants to see in the *undo-history view*. Another critical
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   299
improvement would be to enable the undo feature on a part only of
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   300
the entity-relationship schema to avoid storing too much useless
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   301
data and reduce the underlying overhead.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   302
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   303
But both functionality are related to the strong design choice not
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   304
to represent transactions and actions as entities and
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   305
relations. This has huge benefits in terms of safety and conceptual
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   306
simplicity but prevents from using lots of convenient CubicWeb
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   307
features such as *facets* to access undo information.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   308
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   309
Before developing further the undo feature or eventually revising
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   310
this design choice, it appears that some return of experience is
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   311
strongly needed. So don't hesitate to try the undo feature in your
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   312
application and send us some feedback.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   313
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   314
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   315
Notes
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   316
~~~~~
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   317
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   318
.. [1] The end-user Web interface could be improved to enable
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   319
       user to choose whether he wishes to see private actions.
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   320
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   321
.. [2] There is only five kind of elementary actions (beyond
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   322
       merely accessing data for reading):
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   323
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   324
       * **C** : creating an entity
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   325
       * **D** : deleting an entity
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   326
       * **U** : updating an entity attributes
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   327
       * **A** : adding a relation
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   328
       * **R** : removing a relation
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   329
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   330
.. [3] Meaning none of the actions in the transaction is
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   331
       undone. Depending upon the application, it might make sense
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   332
       to enable *partial* undo. That is to say undo in which some
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   333
       actions could not be undo without preventing to undo the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   334
       others actions in the transaction (as long as it does not
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   335
       break schema integrity). This is not forbidden by the
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   336
       back-end but is deliberately not supported by the front-end
b2443e266661 [doc] Book entry for the undo functionnality.
Anthony Truchet <anthony.truchet@logilab.fr>
parents:
diff changeset
   337
       (for now at least).