Control : FormList

Back to Controls

The FormList control allows you to display (in list fashion) the forms belonging to application object within a collection.

 

Contents

Examples 

The following examples are intended to be used with sample code that you can import into your Bungee Builder workspace from the Start Page. Each example is intended to build upon the previous example to provide you with a complete understanding of how to use this control.

Example 1: FormList bound to a Collection Field (Ex1_Addresses)

You can bind a FormList to a collection. In this example, a FormList control is bound to a collection (addr) whose element type is Address. The Element Form property (Adatper tab) is set to RowDetail (this is the form adapter used by the FormList control).

Click for larger image 

Example 2: FormList bound to a Collection Field with Selection Support (Ex2_AddressesWithSelection)

You can include selection support when you bind a FormList to a collection. This example is the same as Example 1, but with support for selecting an item added. To allow for selecting items, the Allow Selection property is set to true. In addition, to allow for selecting multiple items simultaneously, the Multiple Select property is also set to true. The selection connection adapter is implemented by the example object containing the collection field.

Click for larger image 

Example 3: FormList bound to a Collection Field with Selection Support and Editing (Ex3_EditAddresses)

You can add the ability to edit when you bind a FormList to a collection. This example builds on the two previous examples. Now, support for direct editing (selecting an item and pressing the Delete key after selecting within the control) and indirect editing (through buttons bound to functions that programmatically change the collection using add and removeSelected API functions) are added. 

The Add New button control is bound to the addNewAddress function on the parent object of the collection. When the end user clicks the button, the function creates a new instance of Address and prompts the user to fill in the information. When the user clicks OK, the newly created address object is added to the collection.

In removeAddressWithPrompt, the end user is prompted to confirm the removal of the object, and the selected context (the selectedName argument passed in) is used to delete the object from the collection. To enable edit, the selectedFormAdapter field is set on the Element connection adapter. When an end user selects the address in the list, the form changes to RowEdit per the adapter set on the selectedFormAdapter.

Click for larger image 

Example 4: FormList bound to a Collection Field with Selection Support, Editing and Drag-and-Drop (Ex4_DragDropAddresses)

You can add drag-and-drop ability when you bind a FormList to a collection. This example includes all the functionality of the previous example and adds support for drag-and-drop by adding a field (favorites) as a target location to which address objects can be dragged. The Drag Zone and Drop Zones properties (Behavior tab) are changed so each property contains the same reference (AddrList).

Click for larger image 

Example Helper Classes

Task

Click for larger image 

Address

NewAddressDetail Form

Click for larger image 

RowEdit Form

Click for larger image 

Row Form

Click for larger image 

Reference

Supported Types (Control Adapter)

Type Summary
Collection<Object>

Use the FormList to display an collection type field of complex Objects. You choose either of two ways indicate which form to use to represent the item in the collection:

1) Select the FormList control on the form, then set the Element Form property in the Adapters property sheet tab. At runtime the Collection will query the item object for a form that references that Element Form type.

2) Implement the "Element" connection adapter on the object item itself. This allows the object item to "compute" the form to use at runtime. A common practice is to create a collection field whose item type is Object or some other base type representative of all the items in that collection. For example, if the collection element type is "Person" then at runtime, all the items in the list are at least an instance of type Person. In addition, any subclass of Person is also acceptable. If you are unsure which type instances will be in the collection (as designed) then set the type to Object, as all objects in the system inherit from Object.

Property Adapters

Name Summary
Tooltip Displays the Tooltip as the user moves the mouse within the FormList area.
Element Form

The Element Form property is found in the Adapter section of the Property Editor for FormList. You can simply pick any named form adapter. If you have set this property, then at runtime, the FormList queries each object item in the collection for a form that is implemented on that item type and that references the form adapter set through the Element Form property. For a collection containing a heterogeneous set of object item types, each item type encountered in the collection by the FormList may display a unique form.

Connection Adapters

Name Default Summary
Selection FormListAdapter Use the selection adapter to cause the FormList control to respond to selection by end-users, as well as set initial selection within the list when bound to an application object. This allows the parent object of the collection field to respond to selection events that take place within the FormList control at runtime.
Element FormListElementAdapter Use the element connection adapter to control which form the FormList displays for each item in the list within the application object. If at design time you know the form adapter to use, then it is easier to set the "Element Form" property. If, however, you want to dynamically determine at runtime which form to use, then implement this connection on each object type that will have item instances in the bound collection field at runtime.

Connection Adapter: Selection

The Selection connection adapter is invoked in the application object context, not merely the context or scope of the field that is tied to the FormList control itself. That way, the selection for that particular field can be managed in a parent context that is able to handle the specific semantics for that member. The parent context is always the root of the path used to connect the FormList to the field (see the Path property on the Behavior tab of the Property Editor.

Field Type Field Name Description
string selectName The collection type can manage multiple selected sets where each selection is identified with a string name. You can set selectName to a specific selection that is desired. If you do not set selectName, then default is the name used by the FormList control when setting selection on the collection. Typically, you do not need to set this value; if it is not associated with a value then the default selected set is used.
Object selectedElement The selectedElement is set when the end user selects an item in the FormList control. You can either map this value to a currentSelected field in your class, or you can implement custom logic to be run on either the model or view when this field changes. Be sure to set Linked to true if you want the selected state to update during the life of the connection between the FormList and the object to which you you have bound the control.
boolean setSelectOnInit If you associated an application object field with the selectedElement field (see above), then setSelectOnInit determines if that field is set when the FormList control is first connected to the Model. If you have a field on your class that needs to reflect the currently selected state of the collection, then with the collection bound to the FormList control and the setSelectOnInitconnection field set to true, when a user selects an item in the collection, the FormList control sets the selected member you have associated with this field.

Connection Adapter: Element

Field Type Field Name Description
FormAdapter formAdapter This is the adapter that the FormList uses to find the form on each item in the collection. You can either associate the form adapter with a field in the parent object that contains the collection field (of type FormAdapter), or you can implement the model side of the connection to compute this form adapter value using logic that gets executed for each item the FormList encounters in the collection. If you know the form adapter will never change during the life of the connection, then simply set the Element Form property of the FormList control (found on the Adapter tab of the Property Editor), this way you do not have to implement this connection on any object in the list.
FormAdapter selectedFormAdapter Use the selectFormAdapter when you want the FormList control to display a second form to an end user after the end user selects an item in the list. Suppose for example, you want "read-only" forms displayed by default for each item in the list, but you also want a second editable form to replace the read only form if a user selects that item. The selectFormAdapter makes this possible.
Object targetMember The target member allows you to point the FormList control at an object other than the actual object item in the collection, and also to find and display the form for that second object (the item in the collection is the default object FormList uses if this field is not set). Suppose for example, you have an item in the collection of type "Person" and the Person class has a field called "Address" that you want to use as the item to display in the FormList row. To do this, set the targetMember to Person.address when implementing this connection on Person.

Function Adapters

Name Default Summary
Double Click <not set> The Double Click property on the FormList (accessible on the Adapter tab of the Property Editor) allows you to set a function adapter on the application object, which gets called when a user double-clicks an item in the FormList control. No attempt is made to call the Double Click function adapter on the application object if the property is left in the default state of <not set>. The object tied to the form displayed in the FormList control is the object on which the double-click handler is called (i.e., the parent object containing the collection field tied to the FormList).
Drag Function <not set> The Drag Function function adapter on the application object is called when an end user drags an item into the FormList. No attempt is made to call the Drag Function function adapter on the application object if you leave the adapter <not set> for this property. See the DragDrop API docs for more details on the single argument passed into this function as well as the Drag Zone and Drop Zones Property Group.
Remove <not set> The remove function adapter is the function adapter you specify by setting the Remove property on the FormList control. At runtime, when when a user presses the Delete key on a selected item in the FormList control, the remove function adapter gets called on the application object. If you leave the property set to the default (<not set>), the control does not call the remove function adapter.

Function Adapter: Double Click

Field Type Field Name Description
Data Item  This is the item double-clicked. The value is of type Data because this function adapter is used by other controls that support primitive items in collections. Assign the Item value to a known or expected type. You should also note, the target function on the application object can contain this signature but with the expected type for this argument being the argument type. For example, if the expected type for the Item is Person, then the signature on the  application object may look something like this: showDetail(Person item, long index); 
long  index  This is the index of the item the end user double-clicked. 

Function Adapter: DragFunction

Field Type

Field Name

Description
DragDrop data You can use the FormList control’s space to allow drag-and-drop interactions.

Function Adapter: Remove

The Remove function adapter (if set on the FormList control property) is called when an end user selects an item and presses the Delete key. The FormList control does not remove the item from the collection; instead, the FormList uses the Remove function adapter implemented on the application object containing the collection field to remove the item--or not: the remove function may include validation logic that results in the item not being removed, or may query the user whether to remove the item, etc..

Field Type Field Name Description
string selectedName This is the name of the selected set involved in the item removal. selectedName allows the function to differentiate between selected sets when deciding to remove an item from the Model side of the connection (the application object collection).
boolean shiftKeyDown This indicates to the function that the user intends to permanently remove the item, not merely remove the item from the current collection. You (as the implementer of the function adapter of the application object) must decide whether to remove the item from the selectName selected set in the collection. You can query the collection (using selectName) for the item(s) involved in that selected set (see Collection).

Associated Properties

Common Properties Index

Specialized Properties

Unique Properties

 

 

 

Retrieved from "http://docs.bungeeconnect.com/wiki/index.php/Control_:_FormList"

Log in if you would like to rate this page.
    Copyright © 2005 - 2007 Bungee Labs. All rights reserved.