The Main Definition Fields

Let's review some important fields that must be part of your object definition.

Schema

The schema identifier defines the database where the table(s) of your object are defined. If most of your tables belong to the same schema, you will generally want to define this schema as the default schema within your site's site_settings definition. In such a case, it will not be necessary to specify the schema when defining the object unless the schema differs from the default schema.

Primary Table

Every db_object must reference exactly one primary table.

Object Name

Provide a descriptive name for your object. This name will be used within messages shown to the user. For example, a message might say "Film 4 displayed successfully". In this case, Film is the name of the object. If your object will be used by multilingual sites you can dynamically set the name of the object according to the user's language by utilizing the translation model. To make this name dynamic it must start with a colon (:) followed by the translation variable. This assumes that you have also supplied the name of a translation class. Alternatively, you can supply a translation class as part of the name also, for example :object_names->film. In this case, object_names would be used as the translation class and film would be the translation variable (and Label would be the translation column).

Cache Data Class

This field is optional. Normally method calls to the object are stateless, that is, it is not necessary to maintain a connection to the server between requests. Nevertheless, there may be situations where it would be convenient to "remember" information from previous requests. In cases like this you can define a class that contains the information you want to remember. The data from this class will be saved within the browser so that it can be returned to the object on subsequent requests. Since this involves network traffic you will want to keep the size of these cache objects as small as possible.

Logical Lock Column

Recall that db_objects use an optimistic locking mechanism which involves checking the value of a certain table column to see if it has changed. Enter the name of the column to be checked here. This column will be automatically changed whenever the object instance is updated.

Lock Column Value

Choose whether the logical lock column is a timestamp or an integer value to be incremented.

Fields Related to Audit Trail Logging

If you want to keep track of changes made to your db_object tables you will need to define a separate log table. This will normally contain the same fields as your primary table however it should also contain the additional log fields such as the user who performed the update and when the change was made. It is not necessary to log all fields in your primary table so the log file could contain only the subset of fields whose changes you want to log.

We provide a brief overview of the log related field below, for a more comprehensive description of how to implement audit trail logs please refer to the Log Profile Help.

Log File Schema

If the log file is not defined within the same schema as the primary db_object file, specify the log file schema here.

Log Table Name

Enter the name of the log file table. Normally, this should be the same as the primary table with a suffix of _log.

Log Update Type

Log files are normally written whenever a change is made to the primary file (or a new record is inserted). In most cases, only a subset of the fields on the primary file are actually changed during any given update. Use this setting to specify whether only the changed columns are to be logged or all columns, including the ones whose values stayed the same.

Log Column Option

This changes the default log column candidates. If you are only planning to log a small number percentage of the eligible fields you should make "Exclude" the default. In this case you must indicate the fields to be included by adding log:true to the DB Column Parameters within the Primary Table Columns grid. If you are planning to log most of the columns, you should choose "Include" as the default and if there are columns to be excluded, these would be indicated with log:false in the DB Column Parameters.

Log Profile

The log profile defines the generic columns defined on your log table.

Update Recognition

Other Scalar Specification Fields

Next let's discuss the fields listed below:

Translation Class

The translation class is normally used when building multilingual applications. In such cases the object name and field name references can reflect the user's current language. This class is created using the translation model.

Translate Labels

Check this box if field labels (used in messages) are to be translated by default. When this is set, rather than referencing field names within validation messages, the system will use the name of the field, along with the translation class, to look up a translation for the field in the user's current language.

Extends Class

It is possible to define a db_object which extends another db_object. To do so, enter the name of the db_object to be extended.

Implements

If this db_object is to implement a certain interface, enter the interface that must be implemented.

Abstract Class

Check this option if the class is to be an abstract class that cannot be instantiated directly (instead it must be extended).

Include Descriptions

Check this option if you want the field descriptions to be included in the generated class.

Continue reading to learn about defining the fields that will be part of your object.