How to use transactions
Transactions are extremely useful for allowing you to build up more complex XML structures without having to worry about validity at all steps. Validation is only done at the end of the transaction.
Transactions
A transaction is a sequence of actions that are, for one purpose or another, considered to be atomic (that is, not divisible).
In SDL LiveContent Create , this means that certain background processes and checks (such as the validator) are effectively suspended for the duration of the transaction. This allows you to add larger structures of elements to your document than you could if you had to maintain validity with each individual element.
Editor.runInTransaction()
Editor.runInTransaction()
Editor.runInTransaction() takes as an argument the code that you wish to run in a single transaction. This can be a single function or whole sequence of functions, lines of code, etc. The only limitation being that the code must save its work in some way, whether by attaching it to the document successfully or storing it in a global variable. The reason for this is that Editor.runInTransaction() only returns a boolean value, with true indicating that the transaction was committed and false indicating that it was rolled back.
If you need your code to return a value, you should use Editor.runInTransaction() to create a transactionized function that passes your return value back.
Editor.wrapInTransaction()
Editor.wrapInTransaction() takes an argument of a function and returns a function. Specifically, it returns the same function now wrapped in an SDL LiveContent Create transaction. The new function has two possible return values: if the transaction succeeds, it returns the same value that the input function would have. However, if the transaction fails, it returns null.
Editor.RevertingException
Throwing an Editor.RevertingException is the standard way of cancelling a change in an event handler. It will also cause any transaction that is in process to rollback and Editor.runInTransaction() to return false
Transactions example
This first example uses Editor.wrapInTransaction() to create a transactional anonymous function tied to the "onclick" method of the document element being created. This is necessary because the code invoked by the onclick will execute asynchronously from the rest of SDL LiveContent Create and the transaction will keep it from interfering with other code that it may be interrupting.
function addOption(parent, node, nodeName, sibling)
{
var opt = document.
createElement("div");
opt.onclick = function(){ Editor.wrapInTransaction(restructure(node, nodeName,
sibling));};
opt.className = "addoption";
if (nodeName == "lid")
opt.
appendChild(document.
createTextNode(nodeName));
else
opt.
appendChild(((document.
createTextNode(nodeName + "head"));
parent.
appendChild((opt);
}
In this case, the restructure() function is called, passing it a new node, the name of the new node and the sibling node it should attached next to.
The following example uses Editor.runInTransaction() in a similar manner to provide a context to code that will execute asynchronously from SDL LiveContent Create .
function completeTOC(evt, ask)
{
var xopusElement = evt.childNode;
// various initializations happen here, omitted for length
if(ask && Editor.confirm("Do you want to generate the Table of Contents?"))
{
generateTOC(doc, xopusElement);
}
setTimeout(function()
{
Editor.runInTransaction()(function()
{
Editor.Selection.setRange(range);
labelText.
setNodeValue("Contents");
})
}, 0);
}
completeTOC() builds up the Table of Contents and then uses setTimeout() to detach and run asynchronously the code that selects the table of contents element and sets the default value of the top-most node as "Contents". The reason for detaching the code to run in this way is because the Editor.Selection.setRange(range) may take some time to complete. Doing so requires that the code be set up to execute in an SDL LiveContent Create transaction so it both has a context to execute in and does not disrupt other code that it may interrupt (due to the JavaScript scheduler). T