Step 1: Connect to the Database
Connect to the database of your choice: CubeSQL, MySQL, ODBC, PostgreSQL, or SQLite. Encrypted SQLite files are supported! Microsoft SQL Server is supported on Windows only. iOS projects are supported on Mac only.
ARGen does not store a copy of your database password and will ask you to enter it every time you open the project. Note that the generated project will not have the database password in it as well!
Step 2: Setup the Project
Fill in the project name first and foremost. Next, fill in the application name, company name, and application identifier for the generated project. These can be changed in the future if desired.
If the project is not an iOS project, select whether it’s a Desktop or Web project.
Select the type of error handling to be generated. “Basic” does not add in any extra database error handling to the generated ActiveRecord classes. “BKeeney Software” error handling raises a runtime exception when a database error occurs. These can be caught and handled.
The GMT Offset setting will change stored dates to use a GMTOffset of zero when enabled. This can be handy with dates that span multiple time zones.
Step 3: Select Tables and Views
Tables and views not selected with the checkbox will not be created as classes in the generated Xojo project. As such, these tables and views will also not be available to the rest of the generation wizard and cannot have interface objects created.
Step 4: Assign Property Types
Xojo doesn’t always asses database column types properly. In this step verify the database column is aligned to the proper Xojo datatype. A good example is Boolean column types, as occasionally these are automatically assessed as Integers. To use Active Record effectively ensure that all database column types are assigned properly.
Additionally, in this step a column can be flagged as unique. A method will be added to the generated Active Record class that checks the selected column is unique when selected.
Step 5: Auto Create Objects
ARGen can generate related objects automatically. Select which objects are automatically added to classes. ARGen automatically adds any foreign keys that are detected in the database, but others may be added using the Add Manual Relationship function. Objects are created as lazy-load properties on their parent. This means that the child object won’t be created – and the data will not be asked for – until the object is used.
In the example shown, the table “Track” from the Chinook database has foreign keys for “AlbumID”, “GenreID”, and “MediaTypeID”. These are all single, one-to-one relationships, so they will generate one object. Use the popup menu in the Type column to change the relationship to an Array of objects for a one-to-many relationship.
The checkbox toggles whether ARGen will create these objects when generating the project and classes.
Step 6: Auto Create UI
For Desktop and Web projects, ARGen can optionally generate user interface elements. Tables can be created as windows (WebPages for Web), ContainerControls, or both. The table on the right shows the options for columns on the selected table.
The type of control selected in the “Control” column reflects what kind of control is generated on the interface to edit the field. The checkbox in the “List” column determines whether that field is included in the Listbox on the selected table’s edit window/container. The “Label” column is the text for the label of that field; used as a Label next to the control on the edit window, and as the column header on the list window.
On the “Table Options” pane are settings related to the controls generated with the table. Set whether the Edit and List controls are a Window or Container Control here, as well as the initial sort for the List control.
Step 7: Extra Modules
The Database Update Module non-destructively adds a database version table to your database. Updating database structure can be done with the module, as it will check the database structure version after connecting and before registering the Active Record classes. The updates are done incrementally so even databases that are a few versions out of date can be used.
The Audit Trail Module non-destructively adds an audit trail table to your database. With this extra enabled, ARGen will add audit-trail functions to the generated classes AfterCreate, AfterUpdate, and AfterDelete events. Changes to records will then appear on the audit trail table.
The Localization Module is a module that contains dynamic constants for strings used in the interface generated by ARGen. Localization must be done after the fact (ARGen does not offer translation services). More information about localization in Xojo with Lingua.
Step 8: Review and Generate!
Review project settings and change them as necessary before generation. When satisfied click the Generate Project button to generate the Xojo XML Project.