Quick Objects Documentation Akal Tech Logo
Handling Object Events

Glossary Item Box

Business Logic Framework - Tutorial 17:

This tutorial demonstrate the ability of business objects to fire events while different types of commands are being executed. The event model is consistent through out all types of commands. Each method fires an event before it executes the specified command and it fires a second event after it has executed the command. The first event that is fired before the command is executed gives the ability to cancel the command.

The following methods have events that can be handled:

In addition two additional events are fired by the business object when the object completes initialization, and another event is fired when the object is being disposed.

The following tutorial demonstrate these capabilities by taking the Find and Update methods as sample:

1 private Customers Customer = null;  
2  
3 private void Page_Load()  
4 {  
5     // Please note: This tutorial requires that the QO_SHOP sample database included with v 3.x.  
6     // If you have have the the database schema from a previous version of QO_SHOP please upgrade the  
7     // QO_SHOP database by using the Drop Objects.sql and Create Objects.sql. If you like the default  
8     // test data to be automatically inserted, please use the Insert Data.sql file.  
9  
10     // The purpose of this tutorial is to demonstrate the ability of the business objects to fire events  
11     // at various stages. This tutorial will also demonstrate how an event handler can be used to cancel the command.  
12  
13     // In this tutorial we will return a list of Customers, and the BeforeFind event will be handled and   
14     // extra search criteria will be applied to the business object.  
15     // If the user selects a customer record in the Grid, the Edit tab will gain focus, and the form will be pre filled  
16     // with the currently selected customer information.  
17     // If the user tries to update the customer record, the business object's BeforeUpdate event handler will be used to  
18     // request confirmation from the user.   
19       
20     // In addition, the AfterFind and and AfterUpdate events will be captured, and they can be used to notify the user  
21     // of the result.  
22  
23     if (this.Customer == null)  
24     {  
25         // if this Customer instance is null, create a new instance and wire up the event handlers.  
26         this.Customer = new Customers();  
27  
28         // The following line will hook the Customer_BeforeFind method to the BeforeFind event of the Customer object.  
29         this.Customer.BeforeFind += new BeforeCommandEventHandler(Customer_BeforeFind);  
30  
31         // The following line will hook the Customer_BeforeUpdate method to the BeforeUpdate event of the Customer object.  
32         this.Customer.BeforeUpdate += new BeforeCommandEventHandler(Customer_BeforeUpdate);  
33  
34         // The following line will hook the Customer_AfterFind method to the AfterFind event of the Customer object.  
35         this.Customer.AfterFind += new AfterCommandEventHandler(Customer_AfterFind);  
36  
37         // The following line will hook the Customer_AfterUpdate method to the AfterUpdate event of the Customer object.  
38         this.Customer.AfterUpdate += new AfterCommandEventHandler(Customer_AfterUpdate);  
39  
40         // Execute the Find method, and this will fire the BeforeFind and AfterFind event handlers in that order.  
41         this.Customer.Find();  
42  
43         // Check to see if there were any records returned by the Find method. If records were returned then we attach the ResultSet  
44         // property to the GridView1's DataSource property in order to display the data.  
45         if (this.Customer.AffectedRecords > 0)  
46         {  
47             this.GridView1.DataSource = this.Customer.ResultSet;  
48             this.GridView1.DataMember = this.Customer.GetResultSetName();  
49             this.Button_Save.Enabled = false;  
50         }  
51     }  
52 }  
53  
54 void Customer_AfterUpdate(object sender, AfterCommandEventArgs e)  
55 {  
56     // Event arguments passed are of type AfterCommandEventArgs.  
57     // This type of event arguments are used in all the events that are fired after a  
58     // command has been executed.  
59  
60     // Success property of the event arguments can be used to check if the command was successful  
61     // or not. If the command was not success, there may be more information available in the ErrorString property.  
62     if (!e.Success)  
63     {  
64         MessageBox.Show("Your changes were not saved! \n " + e.BusinessObject.ErrorString);  
65     }  
66     else 
67     {  
68         MessageBox.Show("Changes Saved!");  
69     }  
70 }  
71  
72 void Customer_AfterFind(object sender, AfterCommandEventArgs e)  
73 {  
74     // It is relatively very easy to access the business objects and the status of the command.  
75     // Success property of the event arguments indicates if the command was successful or not.  
76     if (!e.Success)  
77     {  
78         MessageBox.Show("Search was not successful. \n " + e.BusinessObject.ErrorString);  
79     }  
80     else 
81     {  
82         // You can access properties of the business object by accessing the BusinessObject property of the event arguments.  
83         // The type of of the BusinessObject property is IBusinessObject. To access BusinessObject as the actual type just  
84         // case the BusinessObject property instance to the type of the object.  
85         MessageBox.Show("Your search returned " + e.BusinessObject.AffectedRecords.ToString() + " records.");  
86     }  
87 }  
88  
89 void Customer_BeforeUpdate(object sender, BeforeCommandEventArgs e)  
90 {  
91     // We can check if the BusinessObject values that are being saved are valid or not based on the validation criteria  
92     // of the business object.  
93     if (!e.BusinessObject.IsValid)  
94     {  
95         // You can easily access the business object instance from the BusinessObject property of the event arguments.  
96         MessageBox.Show(e.BusinessObject.ErrorString);  
97     }  
98     else 
99     {  
100         DialogResult res = MessageBox.Show("Are you sure you want to save the changes?", "Do you want to Save?", MessageBoxButtons.YesNo);  
101         e.Cancelled = (res == DialogResult.No);  
102     }  
103 }  
104  
105 void Customer_BeforeFind(object sender, BeforeCommandEventArgs e)  
106 {  
107     // Ask the user to specify the criteria he/she would like to search the customer table for.  
108     string criteria = Interaction.InputBox("Enter the value you would like to search the Customers table for?", "Search!", null, this.Left + 50, this.Top + 100);  
109       
110     // If the user specified a criteria, then we set the customer object's field values accordingly.  
111     if (!String.IsNullOrEmpty(criteria))  
112     {  
113         // Setting ObjectMode to ObjectModes.Search will cause business object to toggle the UseInSearch properties of the field's that are assigned a value.  
114         this.Customer.ObjectMode = ObjectModes.Search;  
115  
116         // Setting MoreResults causes the business object to perform a loose search, and records where FirstName or LastName matches the "criteria" will be returned.  
117         this.Customer.MoreResults = true;  
118  
119         // Setting the PartialTextMatch results in all StringField instances to perform a partial text search. Hence any records where the FirstName or LastName contain the search criteria  
120         // will be returned.  
121         this.Customer.PartialTextMatch = true;  
122  
123         // Since the ObjectMode of the business object is set to ObjectModes.Search, setting the value of the FirstName and LastName fields will change their UseInSearch property to true.  
124         this.Customer.FirstName.Value = criteria;  
125         this.Customer.LastName.Value = criteria;  
126     }  
127     else 
128     {  
129         DialogResult res = MessageBox.Show("You did not specify any search criteria, are you sure you want to run the search without any criteria?", "Warning!", MessageBoxButtons.YesNo);  
130         e.Cancelled = (res == DialogResult.No);  
131     }  
132 }  
133  
134 private void Tutorial17_Leave(object sender, EventArgs e)  
135 {  
136     // Since the user is leaving this screen it is time to dispose of the object.  
137     this.Customer.Dispose();  
138     this.Customer = null;  
139     this.GridView1.DataSource = null;  
140 }  
141  
142 private void Tutorial17_Enter(object sender, EventArgs e)  
143 {  
144     // User has just entered, so it is time to load the business object.  
145     this.Page_Load();  
146 }  
147  
148 private void GridView1_SelectionChanged(object sender, EventArgs e)  
149 {  
150     this.TextBox_FirstName.Text = "";  
151     this.TextBox_LastName.Text = "";  
152     // If the Customer object is not null and the user has selected at least one row,  
153     // then we can take the SelectedRows[0] and have the Customer object load these values.  
154     if (this.Customer != null && this.GridView1.SelectedRows.Count > 0)  
155     {  
156         // Lets set the IsLoaded property and this property value can be used later to ensure that  
157         // that Customer object is actually loaded with the values that are needed.  
158         // LoadFromDataRow gives you flexibility to load the object values from the data row. This will essentially  
159         // save a round trip to the database since the values are already available in the Grid.  
160         this.Customer.IsLoaded = this.Customer.LoadFromDataRow((this.GridView1.SelectedRows[0].DataBoundItem as DataRowView).Row);  
161         if (this.Customer.IsLoaded)  
162         {  
163             this.TextBox_FirstName.Text = this.Customer.FirstName.Value;  
164             this.TextBox_LastName.Text = this.Customer.LastName.Value;  
165             this.Button_Save.Enabled = true;  
166         }  
167         else 
168         {  
169             this.Button_Save.Enabled = false;  
170         }  
171     }  
172     else 
173     {  
174         this.Button_Save.Enabled = false;  
175     }  
176 }  
177  
178 private void Button_Save_Click(object sender, EventArgs e)  
179 {  
180     if (this.Customer != null && this.Customer.IsLoaded)  
181     {  
182         // Setting ObjectMode to ObjectModes.Search will cause business object to toggle the UseInSearch properties of the field's that are assigned a value.  
183         this.Customer.ObjectMode = ObjectModes.Save;  
184  
185         // Set the values of FirstName and LastName, and this will change the UseInSave property to true since the   
186         // ObjectMode of the business object is set to ObjectModes.Save;  
187         this.Customer.FirstName.Value = this.TextBox_FirstName.Text;  
188         this.Customer.LastName.Value = this.TextBox_LastName.Text;  
189  
190         // Calling the Update method will fire the BeforeUpdate event handler where the user will be able to cancel the command if desired.  
191         this.Customer.Update();  
192     }  
193 }  
194  
1 Dim WithEvents Customer As Customers = Nothing 
2  
3 Private Sub Page_Load()  
4 'Please note: This tutorial requires that the QO_SHOP sample database included with v 3.x.  
5 'If you have have the the database schema from a previous version of QO_SHOP please upgrade the  
6 'QO_SHOP database by using the Drop Objects.sql and Create Objects.sql. If you like the default  
7 'test data to be automatically inserted, please use the Insert Data.sql file.  
8  
9 'The purpose of this tutorial is to demonstrate the ability of the business objects to fire events  
10 'at various stages. This tutorial will also demonstrate how an event handler can be used to cancel the command.  
11  
12 'In this tutorial we will return a list of Customers, and the BeforeFind event will be handled and   
13 'extra search criteria will be applied to the business object.  
14 'If the user selects a customer record in the Grid, the Edit tab will gain focus, and the form will be pre filled  
15 'with the currently selected customer information.  
16 'If the user tries to update the customer record, the business object's BeforeUpdate event handler will be used to  
17 'request confirmation from the user.   
18  
19 'In addition, the AfterFind and and AfterUpdate events will be captured, and they can be used to notify the user  
20 'of the result.  
21  
22 If Me.Customer Is Nothing Then 
23     Me.Customer = New Customers()  
24  
25     ' Execute the Find method, and this will fire the BeforeFind and AfterFind event handlers in that order.  
26     Me.Customer.Find()  
27     ' Check to see if there were any records returned by the Find method. If records were returned then we attach the ResultSet  
28     ' property to the GridView1's DataSource property in order to display the data.  
29     If Me.Customer.AffectedRecords > 0 Then 
30         Me.GridView1.DataSource = Me.Customer.ResultSet  
31         Me.GridView1.DataMember = Me.Customer.GetResultSetName()  
32     End If 
33 End If 
34  
35 End Sub 
36  
37 Private Sub Customer_AfterUpdate(ByVal sender As System.Object, ByVal e As AfterCommandEventArgs) Handles Customer.AfterUpdate  
38 ' Event arguments passed are of type AfterCommandEventArgs.  
39 ' This type of event arguments are used in all the events that are fired after a  
40 ' command has been executed.  
41  
42 ' Success property of the event arguments can be used to check if the command was successful  
43 ' or not. If the command was not success, there may be more information available in the ErrorString property.  
44 If Not e.Success Then 
45     MessageBox.Show("Your changes were not saved! \n " & e.BusinessObject.ErrorString)  
46 Else 
47     MessageBox.Show("Changes Saved!")  
48 End If 
49 End Sub 
50 Private Sub Customer_AfterFind(ByVal sender As System.Object, ByVal e As AfterCommandEventArgs) Handles Customer.AfterFind  
51 ' It is relatively very easy to access the business objects and the status of the command.  
52 ' Success property of the event arguments indicates if the command was successful or not.  
53 If Not e.Success Then 
54     MessageBox.Show("Search was not successful. \n " & e.BusinessObject.ErrorString)  
55 Else 
56     ' You can access properties of the business object by accessing the BusinessObject property of the event arguments.  
57     ' The type of of the BusinessObject property is IBusinessObject. To access BusinessObject as the actual type just  
58     ' case the BusinessObject property instance to the type of the object.  
59     MessageBox.Show("Your search returned " & e.BusinessObject.AffectedRecords.ToString() & " records.")  
60 End If 
61 End Sub 
62  
63 Private Sub Customer_BeforeUpdate(ByVal sender As System.Object, ByVal e As BeforeCommandEventArgs) Handles Customer.BeforeUpdate  
64  
65 ' We can check if the BusinessObject values that are being saved are valid or not based on the validation criteria  
66 ' of the business object.  
67 If Not e.BusinessObject.IsValid Then 
68     ' You can easily access the business object instance from the BusinessObject property of the event arguments.  
69     MessageBox.Show(e.BusinessObject.ErrorString)  
70 Else 
71     Dim res As DialogResult = MessageBox.Show("Are you sure you want to save the changes?", "Do you want to Save?", MessageBoxButtons.YesNo)  
72     If res = DialogResult.No Then 
73         e.Cancelled = True 
74     End If 
75 End If 
76 End Sub 
77 Private Sub Customer_BeforeFind(ByVal sender As System.Object, ByVal e As BeforeCommandEventArgs) Handles Customer.BeforeFind  
78 'Ask the user to specify the criteria he/she would like to search the customer table for.  
79 Dim criteria As String = Interaction.InputBox("Enter the value you would like to search the Customers table for?", "Search!", Nothing, Me.Left + 50, Me.Top + 100)  
80  
81 ' If the user specified a criteria, then we set the customer object's field values accordingly.  
82 If Not String.IsNullOrEmpty(criteria) Then 
83     ' Setting ObjectMode to ObjectModes.Search will cause business object to toggle the UseInSearch properties of the field's that are assigned a value.  
84     Me.Customer.ObjectMode = ObjectModes.Search  
85  
86     ' Setting MoreResults causes the business object to perform a loose search, and records where FirstName or LastName matches the "criteria" will be returned.  
87     Me.Customer.MoreResults = True 
88  
89     ' Setting the PartialTextMatch results in all StringField instances to perform a partial text search. Hence any records where the FirstName or LastName contain the search criteria  
90     ' will be returned.  
91     Me.Customer.PartialTextMatch = True 
92  
93     ' Since the ObjectMode of the business object is set to ObjectModes.Search, setting the value of the FirstName and LastName fields will change their UseInSearch property to true.  
94     Me.Customer.FirstName.Value = criteria  
95     Me.Customer.LastName.Value = criteria  
96 Else 
97     Dim res As DialogResult = MessageBox.Show("You did not specify any search criteria, are you sure you want to run the search without any criteria?", "Warning!", MessageBoxButtons.YesNo)  
98     If res = DialogResult.No Then 
99         e.Cancelled = True 
100     End If 
101 End If 
102 End Sub 
103 Private Sub Tutorial17_Leave(ByVal sender As System.Object, ByVal e As EventArgs) Handles Me.Leave  
104 ' Since the user is leaving this screen it is time to dispose of the object.  
105 Me.Customer.Dispose()  
106 Me.Customer = Nothing 
107 Me.GridView1.DataSource = Nothing 
108 End Sub 
109 Private Sub Tutorial17_Enter(ByVal sender As System.Object, ByVal e As EventArgs) Handles Me.Enter  
110 ' User has just entered, so it is time to load the business object.  
111 Me.Page_Load()  
112 End Sub 
113  
114 Private Sub GridView1_SelectionChanged(ByVal sender As System.Object, ByVal e As EventArgs) Handles GridView1.SelectionChanged  
115 Me.TextBox_FirstName.Text = "" 
116 Me.TextBox_LastName.Text = "" 
117 ' If the Customer object is not null and the user has selected at least one row,  
118 ' then we can take the SelectedRows[0] and have the Customer object load these values.  
119 If Not Me.Customer Is Nothing And Me.GridView1.SelectedRows.Count > 0 Then 
120     ' Lets set the IsLoaded property and this property value can be used later to ensure that  
121     ' that Customer object is actually loaded with the values that are needed.  
122     Dim rowView As DataRowView = DirectCast(Me.GridView1.SelectedRows(0).DataBoundItem, DataRowView)  
123     Me.Customer.IsLoaded = Me.Customer.LoadFromDataRow(rowView.Row)  
124     If Me.Customer.IsLoaded Then 
125         Me.TextBox_FirstName.Text = Me.Customer.FirstName.Value  
126         Me.TextBox_LastName.Text = Me.Customer.LastName.Value  
127         Me.Button_Save.Enabled = True 
128     Else 
129         Me.Button_Save.Enabled = False 
130     End If 
131 Else 
132     Me.Button_Save.Enabled = False 
133 End If 
134 End Sub 
135  
136 Private Sub Button_Save_Click(ByVal sender As System.Object, ByVal e As EventArgs) Handles Button_Save.Click  
137 If Not Me.Customer Is Nothing And Me.Customer.IsLoaded Then 
138     ' Setting ObjectMode to ObjectModes.Search will cause business object to toggle the UseInSearch properties of the field's that are assigned a value.  
139     Me.Customer.ObjectMode = ObjectModes.Save  
140  
141     ' Set the values of FirstName and LastName, and this will change the UseInSave property to true since the   
142     ' ObjectMode of the business object is set to ObjectModes.Save  
143     Me.Customer.FirstName.Value = Me.TextBox_FirstName.Text  
144     Me.Customer.LastName.Value = Me.TextBox_LastName.Text  
145  
146     ' Calling the Update method will fire the BeforeUpdate event handler where the user will be able to cancel the command if desired.  
147     Me.Customer.Update()  
148 End If 
149 End Sub 
150