Concepts

The main concepts used by the Transaction Engine 3 are:

• Transaction

• Dispatcher

• Trigger

Transaction:

A Transaction is, in general terms, a set of operations that the server-side script must perform. The transaction has a main operation that is performed, that is generally a SQL statement. However, you can build transactions that do not use SQL commands at all.

As an example, a transaction can perform the following operations:

• Check if a form was submitted.
• Check if all the required forms values were correctly submitted.
• Build and execute a SQL statement using the submitted form values (e.g. an INSERT statement).
• Upload & save a file selected in the form.
• If every operation was successfully executed, go to another page.
• If not, inform the user of the errors and/or ask the user to re-insert the form informations.

The schematics of a transaction shows that the transaction itself is the whole made up from the main operation and the smaller operations performed before, after or in case of an error:

Depending on the main operation';s type, there are several transaction types:

• Insert Transaction - a Transaction that has as main operation the execution of a single SQL/INSERT statement (will insert a record in a database).

• Update Transaction - a Transaction that has as main operation the execution of a single SQL/UPDATE statement (will update a record in a database).

• Delete Transaction - a Transaction that has as main operation the execution of a single SQL/DELETE statement (will delete a record from a database).

• Custom Transaction - a Transaction that can have as main operation any SQL statement or no SQL statement at all, just a set of instructions. It is generally used to execute more complex INSERT/UPDATE/DELETE statements.

• Multiple Insert Transaction - a Transaction that has as main operation the execution of one or more SQL/INSERT statements (will insert one or more records in a database).
• Multiple Update Transaction - a Transaction that has as main operation the execution of one or more SQL/UPDATE statements (will update one or more records in a database).
• Multiple Delete Transaction - a Transaction that has as main operation the execution of one or more SQL/DELETE statements (will delete one or more records from a database).

Whenever the transaction will throw an error, its execution will fail.

Dispatcher

It represents a container for the transactions, and it is needed to improve the flow when using multiple transactions on the same page. Any transaction that will be executed in a page will have to be registered with the dispatcher. The dispatcher is represented in page by the following line of code:

$tNGs = new tNG_dispatcher("");

The $tNGs variable will be created only once and it will act like a global variable throughout the entire request. The dispatcher is unique on page. It receives as parameter the current file's relative path from the site root.

The Dispatcher is very important, as it handles all interactions between the page and the Transactions that are registered to it (executes the Transactions, feeds the recordsets generated by the Transactions to the page, displays Transaction's error messages etc).

Trigger

Triggers represent operations that prepare or complete the Transaction's main operation. [They can exist only as a part of a Transaction and they are executed by the transaction].

It represents a code block that registers to a transaction, has access to the transaction's contextual information, and is executed before/after the transaction.

There are five types of triggers, based on the cascaded execution of a transaction:

• STARTER triggers are executed before the transaction is started. They can decide whether a transaction is executed or not as they are separate from the BEFORE triggers, because an error is not thrown when the starter trigger stops the execution.

• BEFORE triggers are executed if the transaction is accepted by its start conditions. The before triggers usually check the posted data or change it, making it suitable for the SQL transaction generation. The validation triggers are a good example, as they verify the data's compliance to the validation rules and stop the transaction if it doesn't match.

• AFTER triggers are executed after the transaction has correctly run, without throwing any errors. The AFTER triggers usually manipulate files or use the just updated information.

• END triggers are executed when all the AFTER triggers have already been executed and no error was thrown.

• ERROR triggers are triggers that register to a transaction, and that get executed when the transaction fails. The transaction might fail from various reasons (database integrity, trigger errors etc).