Converting from DBKit 1 to DBKit 2

Introduction

DBKit 2 removes the TableConnection class. In its place, three new classes DBKit.Window, DBKit.Page and DBKit.Container take over everything the TableConnection used to do: connecting to the database, loading rows, tracking the current row and managing the controls on the layout. Converting a project mostly means deleting the TableConnection instances and the code that went with them, setting the Super of your layouts to one of the new classes, and learning a few new property names.

One thing that has not changed is binding. In DBKit 1 you bound a control by setting its Column property or, more commonly, by simply naming the control the same as the database column. That is still how it works in DBKit 2, except the property is now called ColumnName.

Replace the TableConnection

In DBKit 1, every layout had a TableConnection instance that connected the layout's controls to a database table. In DBKit 2 there is no TableConnection. Instead, set the Super of the layout itself:

Desktop: set the window's Super to DBKit.Window.
Web: set the webpage's Super to DBKit.Page.
DBKit.Container allows you to embed DBKit controls on a DesktopWindow or WebPage that doesn't have DBKit.Window or DBKit.Page as its super.

Then delete the TableConnection instance from the layout. Its settings move to the layout, and a few property names have changed:

DBKit 1 TableConnection property	DBKit 2 layout property
Table	`TableName`
Connection	`Database`
ConnectionName	No equivalent. Set the Database property directly on each layout; layouts using different databases just use different connections.
AutoConnect	No equivalent. DBKit 2 layouts connect automatically.
CreateNewRow	No equivalent as a property. To open a layout ready to create a new row, use a DBKit.NewButton or call `NewRow` on the DBKit.Table.
QueryRows	No equivalent. The DBKit.Table loads its own rows. Use the layout's `Where` and `OrderBy` properties instead of assigning a RowSet from your own query.

The easiest way to set the layout's Database property is to add a DatabaseConnection to your project (Insert > DatabaseConnection), then select it from the Database popup menu in the Inspector. You can also assign it in code.

If you assigned the QueryRows property a RowSet from your own query in order to filter or sort the rows, set the layout's Where and OrderBy properties instead. For example, where you previously wrote SELECT * FROM customers WHERE country = 'USA' ORDER BY lastname, set TableName to customers, Where to country = 'USA' and OrderBy to lastname.

Loading related rows no longer requires code. In DBKit 1 you wrote code in the TableConnection's LoadingRow event that queried with SelectSQL and assigned the resulting RowSet to another TableConnection's QueryRows. In DBKit 2, do two things and DBKit loads the related rows for you:

Set the layout's TableRelationships property. Each relationship must name the table on both sides, in the form foreignTable.column=primaryTable.column:

invoices.customerid=customers.id

The table names on both sides are required. customerid=id will not work. 2. Set a DBKit.Table's TableName to the related table (invoices in this example).

Replace the QueryRowsListBox with a Table

DBKit 1's QueryRowsListBox (and DBKit.ListBox) are replaced by DBKit.Table in DBKit 2. Since you're converting, there's no need to drag a new control: select the QueryRowsListBox on the layout and change its Super to DBKit.Table.

A few property names have changed:

DBKit 1 QueryRowsListBox property	DBKit 2 DBKit.Table property
Columns	ColumnNames
Table	`TableName`
Connector	No equivalent. It isn't needed.
Concatenater	Removed.
QueryRows	No equivalent. The table loads its own rows.

The BindDatabaseColumns method is also gone; set the ColumnNames property in the Inspector instead.

Update your controls

All DBKit data entry controls (TextField, TextArea, NumberField, CheckBox, PopupMenu, RadioGroup, Slider, DatePicker and the rest) work the same way in DBKit 2, with these property name changes:

DBKit 1 property	DBKit 2 property
Column	`ColumnName`
Table	`TableName`
Connector	No equivalent. It isn't needed.

DisplayName and Mandatory are unchanged. As in DBKit 1, if you named your controls to match the database column names, you don't need to set ColumnName at all.

The Bind method on controls (which took the TableConnection) is gone, as are the TableConnection's BindAllControls and BindEntryControl methods. Binding is automatic, so delete any Bind calls. If your TableConnection's Opening event only called BindAllControls, you can delete the event entirely.

Code you no longer need

In DBKit 1, the TableConnection had methods for everything the layout did with rows, and methods to wire up buttons in code. In DBKit 2 the layout manages rows itself and buttons wire themselves up when you set their Super, so this code goes away:

DBKit 1 code	DBKit 2
BindDeleteButton, BindEditButton, BindNewButton, BindUndoButton, BindEditingButton, BindToolbar, BindNavigationButton, BindMoveToFirstRowButton, ...	Delete these calls. Setting the button's Super to the DBKit button class is all that's needed.
BindSearchField	Delete. The DBKit.SearchField finds the DBKit.Table on the layout automatically.
BindListBoxControl, BindListBoxColumn	Delete. No longer needed.
LoadSelectedRow	Delete. The selected row loads automatically.
EditRow	Delete. Use a DBKit.EditButton.
UndoRowChanges	Delete. Use a DBKit.UndoButton.
NewRow	Delete. Use a DBKit.NewButton.
ConfirmDeleteRow	Delete. Use a DBKit.DeleteButton.
MoveToFirstRow, MoveToNextRow, MoveToPreviousRow, MoveToLastRow	Delete. Use the DBKit navigation buttons.
CurrentRow, PrimaryKeyColumn, HasBoundListBox, BoundQueryRowsListBox	Delete. The layout tracks the current row itself (see `DBKit.Window.CurrentRow`).
Connect, Connected, Close, CheckForRowChange, RemoveSelectedRow, TableColumnType	Delete. No longer needed.

The localizable strings moved as well. The TableConnection's Confirm* and DeleteConfirm* strings are now properties of the layout (for example UnsavedChangesMessage and DeleteConfirmMessage), and the edit button captions are now EditCaption and DoneCaption on DBKit.EditButton.

Update your events

DBKit 1 TableConnection event	DBKit 2
LoadingRow	`RowLoaded` on the layout or table. Note: RowLoaded is notification-only; it cannot prevent the row from loading the way returning False from LoadingRow did.
SavingRow	`RowSaving` on the layout or table.
ControlsStateChanged	Removed. DBKit 2 manages control state itself.
Error	`Error` on the layout.
Opening	Unchanged. Still the Opening event.
Closing	Unchanged. Still the Closing event on desktop and the Closed event on web.

Update SearchField

The DBKit.SearchField still exists in DBKit 2 and works the same way, with these changes:

DBKit 1 SearchField	DBKit 2 DBKit.SearchField
Connector	No equivalent. It isn't needed.
Table	No equivalent. The SearchField finds the DBKit.Table on the layout automatically.
Columns	Columns (unchanged)
HintPrefix	HintPrefix (unchanged)
ToolTipMessage	ToolTipMessage (unchanged)
ShowAllRowsByDefault	Removed. The table shows all rows by default.
Search(), UpdateHint()	Removed. Searching is automatic as the user types.

New in DBKit 2: the SearchField has an AutoHint property that automatically sets its hint from the column names, a SearchInSelection property and a SearchComplete event.

Explore what's new in DBKit 2

Once your project is converted, these DBKit 2 features are worth a look. You may find they replace code you wrote yourself in DBKit 1:

DBKit.Table loads rows lazily, so large tables stay responsive. It also has aggregate methods (Average, Sum, Minimum, Maximum), a Refresh method and AllowDirectCellEditing for editing values right in the table.
RowDisplayed is a new table event for displaying calculated values in a column.
DBKit.Row is a new class representing the current database row, passed to the row events.
Where and OrderBy on the layout replace hand-written queries for filtering and sorting.
TableRelationships on the layout replaces hand-written code for loading related rows.
AutomaticHints on the layout (and AutoHint on SearchField) automatically set control hints from display names.
DBKit.Container allows you to embed DBKit controls on a DesktopWindow or WebPage that doesn't have DBKit.Window or DBKit.Page as its super.
DBKit.EditingButton combines Edit, Delete, New and Undo into a single control.