10.4 How to Add a Create Button on a Page

To add a Create button, drag and drop a Create operation for a data collection from the Data Control Palette onto a JSP page or Swing panel.

Note:

The built-in Create operation behaves differently in a web-based application than in a Swing-based desktop application. For web applications, depending on the situation, you may want to use CreateInsert instead of Create.

10.4.1 What Happens When You Drop a Create Button on a Web Page

If you drag a Create operation for a data collection from the Data Control Palette onto a JSP page — whether using JSF or not — you'll get a Create button on your page that is declaratively bound to the built-in Create operation. The Create operation creates a new row for the data collection, but does not insert it into the data collection's row set. By not inserting the new row into the row set at creation time, it helps avoid having an unwanted blank row appear in other pages should the user navigate away from your create page before actually entering any data for the new row. After you've invoked a Create operation, the iterator binding temporarily points to this new row as if it were the current row. When the user successfully submits data for the attributes in the new row, the new row gets inserted into the row set at that time. This is the declarative row creation approach that works best for most web application use cases.

10.4.2 What Happens When You Drop a Create Operation Onto a Swing Panel

If you drag a Create operation for a data collection from the Data Control Palette onto a Swing panel, you'll get a Create button on your panel that is declaratively bound to a built-in operation called CreateInsert instead. The CreateInsert operation creates a new row in the data collection and inserts that new row into the collection just before the current row. CreateInsert is the best approach for Swing applications.

10.4.3 When to Use CreateInsert Instead of Create

There are some situations in a web application where you need to use CreateInsert instead of Create. Use CreateInsert when creating:

An editable table control
A table with a single, current editable row
A Master/detail page and want the newly created master row to correctly show no existing detail rows

CreateInsert is used when a new row needs to be inserted into the row set. Since only the one Create operation shows in the Data Control Palette, to use a CreateInsert operation in a web application involves a couple of additional steps.

How to Change a Create Operation to CreateInsert:

Drop the Create operation from the Data Control Palette onto your page
Select the button in the visual editor and choose Edit Binding... from the context menu
In the Action Binding Editor use the Select an Action dropdown list to change the action binding from using the Create to using CreateInsert instead.

10.4.4 What You May Need to Know About Create and CreateInsert

When you use the Create or CreateInsert operations to declaratively create a new row, under the covers they end up performing the following lines of code:

// create a new row for the view object
Row newRow = yourViewObject.createRow();
// mark the row as being "initialized", but not yet new
newRow.setNewRowState(Row.STATUS_INITIALIZED);

In addition, if you are using the CreateInsert operation, it performs the additional line of code to insert the row into the row set:

// insert the new row into the view object's default rowset
yourViewObject.insertRow(newRow);

When you create a row in an entity-based view object, the Transaction object associated to the current application module immediately takes note of the fact. The new entity row that gets created behind the view row is already part of the Transaction's list of pending changes. When a newly created row is marked as having the initialized state, it is removed from the Transaction's pending changes list and is considered a blank row in which the end user has not yet entered any data values. The term initialized is appropriate since the end user will see the new row initialized with any default values that the underlying entity object has defined. If the user never enters any data into any attribute of that initialized row, then it is as if the row never existed. At transaction commit time, since that row is not part of the Transaction's pending changes list, no INSERT statement will be attempted for it.

As soon as at least one attribute in an initialized row is set, it automatically transitions from the initialized status to the new status (Row.STATUS_NEW). At that time, the underlying entity row gets enrolled in the Transaction's list of pending changes, and the new row will be permanently saved the next time you commit the transaction.

Note:

If the end user performs steps while using your application that result in creating many initialized rows but never populating them, it might seem like a recipe for a slow memory leak. Not to worry, however. The memory used by an initialized row that never transitions to the new state will eventually be reclaimed by the Java virtual machine's garbage collector.