Dynamize

The current codebase is organized into server-side and client-side code. The server-side code is currently written in PHP, while the client-side code is written, according to the facts presented earlier, in Java. The client-side code revolves around the BaseDBO class. This class provides all the methods necessary to create concrete classes that will provide the needed data for the client-side application. Data is read from the underlying table and marshaled into JSON. A DBO object is initialized by creating a collection of Field objects. This is also the place where you can specify different properties of the underlying table:

• setPrimaryKeyField(): specifies the primary key; this will be used in update and delete operations
• setSecondKeyField(): specifies a unique constraint; based on this key, the update operations will or will not be permitted depending on the existence of a record with the same value for the specified key
• setDefaultSortField(): this is the default field based on which the data will be sorted
• setDefaultSortOrder(): specifies the default sort direction (only if default sort field was set)
• setTreeDataSql(): if you specify a full SQL SELECT statement here, than the BaseDBO object will also provide data for hierarchical relationship (tree-like) structures stored in the underlying table; a programming convention is made here: the dataset must contain the following fields: `ID`, `NAME` and `PARENT`

The Field object may be of several predefined types:

• FIELD_TYPE_INTEGER: for holding integer numbers
• FIELD_TYPE_STRING: for holding textual data
• FIELD_TYPE_COMPOSITE: for simulating foreign keys; if you have a foreign key, than one would prefer to see data presented by its meaning, rather than a numerical identifier
• FIELD_TYPE_FLOAT: for holding floating point numbers

For each Field object, several properties may be defined using the provided API. All these properties apply only if the field type is set to FIELD_TYPE_COMPOSITE. In this case, the field will act as a foreign key relation to a secondary table.
• setInjectedFrom(): in order to be able to get data from a secondary table, a SQL JOIN operation must be performed; by setting this property, the constructed SQL is augmented by the specified clauses
• setInjectedFields(): specifies the fields used to construct the foreign key relationship
• setForeignKeyField(): the corresponding ID field in the secondary table
• setForeignDataField(): the corresponding data field in the corresponding table; this is used to present meaningful information to the user, rather than presenting him IDs

The basic idea for developing client-side code using Dynamize is to create the menu and implement action listeners by extending the ItemBaseListener class. Each action will correspond to a table you want to manage. All you need to do here is to augment a CompleteGridWidget with needed information by using the following methods:

• addColumn(): ads a column to the grid’s column model; each column is represented by a CustomColumnConfig instance
• disableAddTab(): prevents the user from adding new rows to the grid; so, the button for adding and the tab used for adding are disabled
• setDataUrl(): specifies the URL from which the grid loader will actually load data; this is an absolute URL which points to a data source in JSON format; basically, each data grid has a server-side counterpart which provides the data stream (see above)
• setRecordsPerPage(): sets the number of records that will be initially loaded into the grid; this is also the equivalent of the page size (based on this information, the entire data is spitted into pages of data)
• setSelectedRow(): specifies which row is initially selected
• groupBy(): specifies the field by which the grid will be grouped by; the grouping view is a special view, providing collapsing features for each group
• render(): this method actually invokes the grid rendering process (data is requested, store is populated and DOM objects are created)

In order to add columns to a grid, objects of type CustomColumnConfig need to be instantiated. A column represents any of the entities that will appear either in the grid, in the panel used for adding fields or in the panel used for filtering records. There are several predefined types for the grid’s columns:

• COLUMN_TYPE_TEXT: for displaying and editing textual data of limited size
• COLUMN_TYPE_INT: for displaying and editing integer data (integer numbers)
• COLUMN_TYPE_FLOAT: for displaying and editing floating point numbers
• COLUMN_TYPE_DATE: for displaying and editing calendar dates
• COLUMN_TYPE_DATATREE: for displaying and editing hierarchical data (tree-like data – for objects that are contained within objects)
• COLUMN_TYPE_RICHTEXT: for displaying and editing rich text (for instance to edit HTML pages)
• COLUMN_TYPE_COMBOLIST: for displaying drop-down lists (with autocomplete capabilities)
• COLUMN_TYPE_FILE: for displaying and uploading resources representing files (any kind of file)
• COLUMN_TYPE_LONGEXT: for displaying and editing large amounts of textual data
• COLUMN_TYPE_CHECKBOX: for displaying and editing checkboxes (true/false values)
• COLUMN_TYPE_COLOR: for displaying and editing data representing color codes; similar to a color-picker
• COLUMN_TYPE_CUSTOM: for displaying custom data-selecting widgets; for instance, it can be used to display an interactive map (e.g.: Google Maps); the custom widget must be enclosed within a HTML page
  • in order to have access to the custom data, you must use the following pattern: $(window.parent.getEditorId()).value, $() is a shorthand for window.parent.document.getElementById() DOM method
  • in order to set your data, you must use the window.parent.setContent() method and provide it with the value retrieved from your control

Also, the framework presents the developer with several methods for manipulating and populating objects of CustomColumnConfig type:

• setColumnType(): defines the type for the column; may be any of the above column types
• setEditable(): specifies whether or not this column will be editable; if is set to false, then no control for editing will be rendered; this column may only appear in the grid or in the panel used for records filtering
• setPrimaryKey(): specifies whether or not this column is a primary key column; if so, editing is disabled for this column (in the current version of the framework, we are only permitting the use of auto-generated primary keys)
• setRequired(): specifies whether or not the value in the column is required; if the value is required, the control will trigger validation errors when the value is null or equal to the default value for that particular field type
• setRegexp(): specifies a regular expression for validating the content of the value contained in the current column; if the value does not match the regular expression, validation errors will occur
• setAssociatedControlDataUrl(): only applicable if the column type is set to COLUMN_TYPE_DATATREE or COLUMN_TYPE_COMBOLIST; it specifies the URL of the data store (provides JSON format data)
• setRootSelectable(): only applicable if the column type is set to COLUMN_TYPE_DATATREE; specifies whether or not the root node can be selected or not; this is useful if you want to select a null parent for the current data, meaning that the current data has no parent, thus, is located on the first level of the hierarchical structure
• setSelectableLevels(): only applicable if the column type is set to COLUMN_TYPE_DATATREE; specifies the exact tree levels which can be selected

Instead of creating an actual column, you may also create what is called a “row expander”. The row expanders are used to display additional information related to that specific record. For instance, you might want to display a long description here, description which will be available to the user only after clicking on the row expander.