Iron Speed Designer uses inheritance to organize the code so your customizations are isolated and protected as the underlying code is regenerated to respond to your design changes.Your custom code will never be overwritten if placed in the appropriate region within the code file. Using the predefined structure of these classes, you can easily customize code without fear of it being overwritten by subsequent regeneration.
|
Key Methods |
Description |
|
LoadData |
LoadData is where you can modify the way data is read from the database, and how they are assigned to the controls. |
|
SaveData |
The SaveData method gives access to record upadate functionality. This method calls Save on all editable records and tables on the page. |
|
SaveButton |
Click handlers (SaveButton, CancelButton, etc.) are ideal place to modify buttons behavior and for example add new logic to the button, such as send email, redirect to another page or save something to session. |
|
GetImage |
GetImage and Get<RecordField>Value are used by Automatic Type Ahead and image popup functionality. They are called from the client side and you can customize them to change Automatic Type Ahead behavior for example. |
|
SetPageFocus |
SetPageFocus tries to set focus on the page to the proper control. It overrides default .NET behavior. Comment its content out if you want to let .NET do its job. |
The page’s code-behind class is derived from the Microsoft .NET Framework’s page class. This class contains event handlers and methods that load the data from the database, display the data in user interface controls and save the updated data back into the database. The page class event handlers and methods call on some of the other classes to actually perform the specific task. Most code customization should be performed in these other classes.
Microsoft .NET Framework does not provide the flexibility of sub-classing of page classes where the controls are defined at both the base class and the sub-class. To provide the ability to customize application code, Iron Speed Designer creates a Base method for each of the methods. For example, Iron Speed Designer creates LoadData and LoadData_Base methods. LoadData calls LoadData_Base to perform the actual work. LoadData can be customized, while LoadData_Base should not be modified. LoadData can perform additional work before or after the call to LoadData_Base, or the entire call to LoadData_Base can be replaced with custom code in LoadData.
The EditCustomers class is derived from the BaseApplicationPage, BasePage and the .NET Page classes. The BaseApplicationPage class can be customized to make a common customization across all pages within an application. It is located in <App Name>\Shared\BaseApplicationPage.vb(cs) file. BasePage class is implemented in the BaseClasses.dll however you can customize it also. See instructions on how to customize BaseClasses
Check out a Sample EditCustomers code-behind including methods that can be customized and those that should not be. Note, not all methods are included and often parameters and closing tags are omitted. Important to remember – you should modify only methods in the Section 1 such as SetPageFocus, LoadData, SaveData but not generated code in Section 2 such as SaveData_Base LoadData_Base, etc.
Normally the methods in Section 1 call the methods in Section 2 to do the required work. You can customize this by executing code before calling the Base method, executing code after calling the Base method, or by copying and modifying the Base code and not calling the Base method. In the following example note calls to generated methods in Section 2 from customizable methods in Section 1
|
Key Methods |
Description |
|
LoadData |
Load the data from the database based on the query specified on the Query Wizard. This method calls the CreateWhereClause to compose the WHERE clause that will be used to read the data from the database. |
|
CreateWhereClause |
For Edit Record and Show Record pages, the CreateWhereClause retrieves the URL parameter and constructs a WHERE clause to read the record from the database. |
|
DataBind |
Binds the record read from the database to the user interface controls. Any formatting of the data such as the conversion of the stored date into a local culture specific date format is performed in this method. DataBind calls SetField for each field displayed on the web page to bind each individual field. |
|
Set<Field> |
Sets the user interface control from the database record. The Set function checks to make sure that the value is non-NULL, and then formats the field based on the data type and the current localized culture in effect for the web page and the application. If the value from the database is NULL, the default value from the database is used. Many of the formatting, display and default value options can be set in the Property Sheet instead of customizing the function. |
|
SaveData |
This method calls Validate to perform additional validation of the data, retrieves the data from the user interface controls, and then saves the data in the database. The transaction must be started prior to a call to this function, and must be committed by the caller. SaveData calls GetField for each control displayed on the web page to retrieve information from the user interface into a record that can be saved. |
|
Validate |
An initially empty Validate method is created in the Base class. You can override this method in the safe class to perform additional validation. In case of an error, an exception must be thrown with an appropriate message that can be reported to the end user. |
|
Get<Field> |
Gets the value from the user interface control into a record that will be saved by SaveData. A Get function is created for each of the user interface controls on the page. This method calls the Parse method to parse the value from the user interface control into the database record. The Parse method first performs validation to ensure the value can be recognized based on the type of the field (e.g., date), and then, if necessary, converts the text value to the data type of the field (e.g., integer). The Parse method may throw an exception if the value is not recognized. The exception must be handled by the caller of the SaveData method. |
If a page contains a record control such as an Add or Edit Record page, a record control class provides the methods necessary to load the data for the specific record and bind its data to the user interface control. There are two record control classes created for each record on the page. A Base record control class contains all the code and is named by prefixing “Base” to the name of the record control (e.g., BaseCustomersRecordControl). An initially empty “safe” class is also created and is named the same as the name of the record control (e.g., CustomersRecordControl). Any methods defined in the base class can be overridden in the safe class to customize the functionality of the record control.
The CustomersRecordControl class is derived from the BaseCustomersRecordControl and BaseApplicationRecordControl classes. The BaseApplicationRecordControl class can be customized to make a common customization across all record controls within an application.
Example of the RecordControl class has only most important methods and events. Most of the content of those methods is omitted, but this example gives you an idea of how the code is organized and different methods are called.
|
Key Methods |
Description |
|
LoadData |
Load the data from the database based on the query specified on the Query Wizard. This method calls the CreateWhereClause to compose the WHERE clause that will be used to read the data from the database. CreateOrderBy is called to create the ORDER BY portion of the SELECT WHERE clause. Both CreateWhereClause and CreateOrderBy methods can be overridden in the safe class to add, modify or replace the code. The LoadData method sets the DataSource of the Table Control class. The DataSource is used later by the DataBind method to bind each of the rows in the table. |
|
CreateWhereClause |
The CreateWhereClause composes and returns a WHERE clause. The WHERE clause is composed of the static WHERE clause defined at page creation time combined with any filtering and searching criteria specified by the end user. You can add additional clauses by overriding the CreateWhereClause method. |
|
DataBind |
Binds the record read from the database to the user interface controls. This method loops through each row in the table, sets the DataSource of the row record control to the specific row from the DataSource of the table control, and then calls the DataBind method of the row record control. Any formatting of the data such as the conversion of the stored date into a local culture specific date format is performed in this method. Pagination controls are bound by calling BindPaginationControls method. The data for any drop-down filter controls is loaded and bound in this method by calling Populate methods for each filter. |
|
SaveData |
This method is applicable to editable tables and calls the SaveData method for each of the row record controls in the table. This method also deletes and rows if the user deleted the row. The row is deleted from the database when the Save button is clicked, not when the delete button is clicked. The transaction must be started prior to a call to this function, and must be committed by the caller. See the SaveData method for the Record Control described above. |
|
BindPaginationControls |
All of the pagination controls are bound in this method. Some controls are disabled if they are not applicable, such as the first page button if the user is already on the first page of the table. |
|
Populate<Field>Filter |
A PopulateFilter method is created for every dropdown filter. The name of the method is of the form Populate<Field>Filter. For example, if there is a Country filter, the method will be called PopulateCountryFilter. This method first calls the CreateWhereClause method for the specific filter (e.g., CreateWhereClause_CountryFilter), and then reads the data from the database, initializes the dropdown list with the values returned, and sets the selected value based on the current value specified in the database. By default, a maximum of 500 items are retrieved from the database. This can be changed by modifying the “Maximum generated items” property on the Property Sheet for the specific filter control. |
|
CreateWhereClause_<Field>Filter |
The CreateWhereClause_<Field>Filter method can be overridden to add, modify or replace the method. This is the best way to display a subset of items in the filters. Please note that the filter is a Display Foreign Key As field, the query may be run on the foreign key table and not on the table from where the data is being displayed. This is based on the Property Sheet setting that determines whether All Values or Only Result Set is selected for the filter settings. For example, if you are displayed the Order Details table containing a Product Id filter that is a foreign key to the Products table, then the Populate method will retrieve data from the Products table if the All Values option is selected. If the Only Result Set option is selected, then the Populate method will retrieve data from the Order Details table. Please take this into consideration when modifying the CreateWhereClause_FILTER methods so you can add the right WHERE clause for the applicable table. |
|
Sort_Click |
A Click handler is created for every column sort hyperlink in a table control. The name of the click handler is of the form COLUMNNAME_Click. For example, if there is a Country1 column header, the method will be called Country1_Click. This method calls the underlying ColumnSort method to set the CurrentSortOrder variable that will be used later by the CreateOrderBy method to set the sorting column and direction. |
The CustomersTableControl class is derived from the BaseCustomersTableControl and BaseApplicationTableControl classes. The BaseApplicationTableControl class can be customized to make a common customization across all table controls within an application.
If a page contains a table control such as a Table Report page, the table control class provides the methods necessary to load, display, filter, search, sort, and paginate the table data. There are two table control classes created for each table on the page. A Base table control class contains all the code and is named by prefixing “Base” to the name of the table control (e.g., BaseCustomersTableControl). An initially empty “safe” class is also created and is named the same as the name of the table control (e.g., CustomersTableControl). Any methods defined in the base class can be overridden in the safe class to customize the functionality of the table control.
In addition to the two classes for each table control, there are two additional classes created that correspond to a row in the table.
|
Key Methods |
Description |
|
Page_Load |
Calls Authorize to verify if user has access to the page, and then calls LoadData to load the data. |
|
LoadData |
LoadData calls the LoadData_Base method which in turn calls each of the record and table controls to actually load the data for the respective controls. The Base method (LoadData_Base) should not be modified, LoadData can be modified to perform additional tasks before or after the call to LoadData_Base or to simply replace the call. |
|
Button_Click |
These methods handle the click event of a button and are named based on the name of the button. For example, a button called SaveButton will have a SaveButton_Click and a SaveButton_Click_Base method created as part of the page class. The SaveButton_Click calls the SaveButton_Button_Click method which in turn calls each of the record and table controls to actually save the data for the respective controls. The Button_Click_Base method starts, commits and ends a transaction and all updating of data occurs within this one transaction. Any errors including validation errors are reported by the lower level methods by throwing an exception. The exception is caught in Button_Click_Base and a Javascript alert is registered for display during the subsequent page load. |
If a page contains a table control, then in addition to the table control classes, two additional classes are created. These classes correspond to a row in the table. The row classes are exactly the same as the Record Control classes defined above.
It is important to note that the row classes do not load the data from the database individually, but instead rely on their DataSource variable being set by the table control’s DataBind method.
A Row class is the same as a RecordControl class described earlier. It is derived from the BaseApplicationRecordControl class. The BaseApplicationRecordControl class can be customized to make a common customization across all record controls and rows within an application.