Elevate Web Builder includes extensive database functionality for easily loading data from the web server and then updating the data on the web server using transactions.
The Elevate Web Builder database functionality has the following architecture:
The database functionality is virtual and handled in-memory in the Elevate Web Builder client application using a disconnected database architecture. Database access is stateless and all updates to the actual database via the web server are performed optimistically. All database requests/responses use the JSON format for any associated data. Please see the JSON Reference for more information on the schema for the JSON data.
There can be one or more databases (TDatabase instances) in an application, and within each database can be one or more owned datasets (TDataSet instances).
Core ConceptsThere are three core concepts in the Elevate Web Builder database functionality:
Loading DataSet Columns - Normally the dataset columns are loaded/defined at design-time in the Elevate Web Builder IDE, but it is possible to dynamically load the columns for a dataset at run-time. The column information comes from the web server application in JSON format and includes basic things such as column name, data type, length, and scale.
Loading DataSet Rows - The dataset rows must be loaded at run-time, and come from the web server application in JSON format. When the rows are loaded, you can specify that the rows be appended to the existing rows in the dataset, or completely replace the current rows in the dataset.
Transactions - By default, transactions are automatically started and committed/rolled back as rows are inserted/saved, updated/saved, and deleted in any datasets contained within a database. Nested transactions are supported, so only the outermost commit operation actually results in communications with the web server application. The automatic transaction handling can be turned off (see the TDatabase component below).
You can find the JSON formats used for all of the above in the JSON Reference topic.
Elevate Web Builder requires that any table that you wish to update, or any table containing content stored in BLOB columns that you wish to load (such as images), must have a primary key defined. Elevate Web Builder uses the primary key to uniquely identify each row.
Core ComponentsThe database functionality contains several core components, all residing in the WebData unit in the Elevate Web Builder component library.
A global TDatabase component instance is auto-created at application startup for both visual and non-visual projects, and is simply called Database. This singleton instance of the TDatabase component is used to keep track of all datasets dropped directly on forms and provides methods for iterating over such datasets.
In addition to this default singleton database instance, you can add explicit TDatabase instances to a visual project by dragging and dropping a database defined in the Database Manager into the Project Manager for the currently-opened project. When the database is dropped on or within the Units node of the project manager, a new TDatabase (or descendant) instance will be created for the project, along with an associated unit, and all of the defined datasets for the database will automatically be created as TDataSet instances in the new database instance.
The TDatabase AutoTransactions property is used to control whether transactions are automatically handled by the database instances. Please see the Transactions topic for more information on how the AutoTransactions property affects transaction handling.
TDataSet components can either be dropped directly on a form or database at design-time in a visual project, or created at run-time in both visual and non-visual projects. The Columns property contains the column definitions for the dataset.
The columns for a dataset can be defined manually at design-time or load at run-time using the TDatabase LoadColumns method (via the TDatabase instance that contains the TDataSet instance) or the TDataSet LoadColumns method. The primary difference between the two is that the TDatabase LoadColumns method transparently handles the server request to the web server for retrieving the columns in JSON format, whereas the TDataSet LoadColumns method simply accepts a JSON string containing the columns, and leaves the details of where the JSON originated up to the caller.
Rows must be loaded from the web server application at run-time using the TDatabase LoadRows method (via the TDatabase instance that contains the TDataSet instance) or the TDataSet LoadRows method. The primary difference between the two is that the TDatabase LoadRows method transparently handles the server request to the web server for retrieving the row data in JSON format, whereas the TDataSet LoadRows method simply accepts a JSON string containing the row data, and leaves the details of where the JSON originated up to the caller.
You can navigate the rows in a TDataSet component by using the First, Prior, Next, and Last methods.