Not many PHPMaker users know about these 4 popular server events: Row_Inserting, Row_Inserted, Row_Updating, and Row_Updated, since the lack of documentation about this. In this article I want to explain you about this server events so that you will use them in the right place, and also, at the right time. 🙂
The Similarity
The only similarity of all these server events is they have the same level; Table level. It means that they can be fired in the specific table only. They have also two argument/parameter respectively; $rsold and $rsnew.
The Difference
The difference among those 4 server events are, both Row_Inserting and Row_Updating has the code return TRUE by default that is located in the last line before the end of the function; meanwhile both Row_Inserted and Row_Updated does not have it.
Insert vs Update
As the name said, the server events which contains Insert word (Row_Inserting and Row_Inserted) are being used to add or to insert the new record(s), whereas the server events which contains Update word (Row_Updating and Row_Updated) are being used to update the existing record(s). This is the very basic things you should know before we go further.
Row_Inserting vs Row_Inserted
Now let's take a look at bit closer to these two server events: Row_Inserting and Row_Inserted.
As the name said, Row_Inserting is fired when the new record(s) is(are) being added or inserted into the current table. Or, we may also say: this event will be called before inserting a new record. Therefore, in this event, you can have the chance to do the certain action such as changing the values, do the validation, do some calculation, or do the certain verification, before the new record(s) is(are) truly being inserted/added into the table. You can even cancel the inserting/adding process by returning FALSE and display the certain message if the new record(s) is(are) not valid. Row_Inserting is useful if you want to implement your own business logic that must be complied before the record(s) is(are) added into the database. Another important things about Row_Inserting is, the code you put in it will be executed row-per-row or record-per-record. In other words, this server event will be executed in each new record that will be inserted. So, this is also useful if you want to implement the server-side validation in Grid-Add or Grid-Edit (since both of these features have the ability to insert one or many records at once). The arguments of the event are the arrays of the old (if copying record) and new record to be inserted. You can change the values in the $rsnew.
Meanwhile, Row_Inserted is fired when the record(s) has(have) been successfully inserted/added into the current table. So the code you put in it, will be executed after either one record (via a single Add form), or all records (via Grid-Add or Grid-Edit) is/are successfully inserted into the database. Thus, in this event, you cannot cancel the inserting/adding process anymore. This event is usually useful if you want to execute your own code after you want to make sure the record(s) is(are) truly inserted/added into database. In more specific case, let's say you want to insert or update another table based on the inserted record's ID.
See? You should be able now to compare between Row_Inserting and Row_Inserted server events.
Row_Updating vs Row_Updated
Now let's take a look at bit closer to these two server events: Row_Updating and Row_Updated.
As the name said, Row_Updating is fired when the existing record(s) is(are) being updated or saved into the current table. Or, we may also say: this event will be called before updating a record. Therefore, in this event, you can have the chance to do the certain action such as changing the values, do the validation, do some calculation, or do the certain verification, before the current record(s) is(are) truly being updated/saved into the table. You can even cancel the updating process by returning FALSE and display the certain message if the record(s) is(are) not valid. Row_Updating is useful if you want to implement your own business logic that must be complied before the record(s) is(are) updated into the database. Another important things about Row_Updating is, the code you put in it will be executed record-per-record or row-per-row. In other words, this server event will be executed in each existing record that will be updated. So, this is also useful if you want to implement the server validation side for Grid-Edit (since it has the ability to update one or many records at once). The arguments of the event are the arrays of the old (if copying record) and new record just inserted.
Meanwhile, Row_Updated is fired when the record(s) has(have) been successfully updated/saved into the current table. So, the code you put in it, will be executed after either one record (via a single Add form), or all records (via Grid-Edit) is/are successfully updated/saved into the database. Thus, in this event, you cannot cancel the updating/saving process anymore. This event is usually useful if you want to execute your own code after you want to make sure the record(s) is(are) truly updated into database. In more specific case, let's say you want to insert or update another table based on the updated record(s).
See? You should be able now to compare between Row_Updating and Row_Updated server events.
Conclusion
- Row_Inserting
- Fired when the new record(s) is(are) being inserted into the current table.
- Used to do server-side validation for the new inserted record(s).
- Have the chance to cancel the inserting process by returning FALSE.
- Will be executed record-per-record or row-per-row.
- Useful for server-side validation while inserting record(s) via Grid-Add or Grid-Edit.
- Row_Inserted
- Fired after the new record(s) is(are) being inserted into the current table.
- Will be executed once either a record or many records is or are successfully inserted into the current table.
- Useful for server-side process after the new record(s) is(are) fully inserted into database.
- Row_Updating
- Fired when the new record(s) is(are) being updated into the current table.
- Used to do server-side validation for the existing record(s).
- Have the chance to cancel the updating process by returning FALSE.
- Will be executed record-per-record or row-per-row.
- Useful for server-side validation while updating record(s) via Grid-Edit.
- Row_Updated
- Fired after the existing record(s) is(are) being updated into the current table.
- Will be executed once either a record or many records is or are successfully updated into the current table.
- Useful for server-side process after the existing record(s) is(are) fully updated into database.
Example of Usage
Please note that if you want to see some examples of usage those server events, then simply read Server Events and Client Scripts topic in the help file.