CLASS: LiveForm

SUPER CLASS: Container

Subclasses

Related Editor

Synopsis

The LiveForm widget makes it easy to build forms that create, update and delete data in an underlying data table.

The LiveForm widget has built-in functionality for displaying, inputting, deleting or updating a record. The LiveForm widget has an associated DataSet object that represents its data source. It also has a DataOutput object, which you can use to get the data out of the LiveForm.

When you specify the DataSet (Getting the DataSet), the LiveForm widget automatically generates Editor widgets for every item in the DataSet (except lists and substructures). The binding on these Editor widgets is already done for you, so this can save you a huge amount of time.

The Editor widgets that LiveForm generates for you are ordinary Editor widgets. You can configure them as you would any other widget and you are free to delete them. However, do not move these Editor widgets outside the LiveForm that generated them.

If you use a LiveVariable for the dataSet then LiveForm can automatically generate Create/Read/Update/Delete functionality for you. A LiveVariable can be based either on a LiveTable (LiveTables) or a LiveView (LiveViews). However, for LiveForms, use a LiveVariable that references a LiveView.

Note: If you use a liveTable, you won't get composite key fields, since these currently appear to the client as a structured related object.

To use the LiveForm widget to insert or update records, you bind its dataOutput to an appropriate Service Variable (Using the DataOutput).

Full Description

Getting the DataSet

LiveForm has a dataSet property that allows you to define the LiveForm's data set by choosing a data object from a simple drop-down. This menu contains all the objects that are available as the data set for this LiveForm. To define the data set, simply select an item from the dataSet property menu. The dataSet menu includes: Variables, Service Variables, "selected item" in DataGrids and Lists. You can alternatively click the "circle" icon next to the dataSet property and use the full bind dialog to set up the data set (More on Binding).

Using the DataOutput

In addition to a DataSet object, each LiveForm widget has an associated DataOutput object. The DataOutput object contains all the values (dataValue, rather than displayValue) of all the Editor widgets in the LiveForm that are bound to the DataSet. The LiveForm's dataOutput property can be bound directly to any LiveVariable or Service Variable for use in server operations.

Displaying Related Fields: RelatedEditor

When displaying a LiveView that contains related objects, a LiveForm creates a special editor called a RelatedEditor to display the related object. This RelatedEditor is a hybrid between an Editor and a LiveForm. It has dataSet and dataOutput properties like a LiveForm and it can contain other editors. However, the RelatedEditor is bound to the parent LiveForm's dataSet property and dataOutput property like the other Editors in the LiveForm.

Note that when relatedEditors are nested, their editingModes depend on each other. In order for a child relatedEditor to be editable or lookup, its parent relatedEditor must be editable. When a parent's editingMode changes, its children are updated to acceptable settings. When a child is changed to an unacceptable setting the change is disallowed and the user receives a message about the form settings.

Properties

LiveForm.addEditors

Once you have specified the binding for the dataSet property, the addEditors button adds an editor to the LiveForm for each column in the specified dataSet.

For example, if you bind the dataSet to a Customer LiveVariable with two properties, custname and custid, pushing the addEditors button will add a custname editor and custid editor to your LiveForm.

LiveForm.border

described in Control

Sets the border-width in pixels for your widget. Enter a single value like 5 to have a 5 px border around the widget. To have borders with different widths, enter a comma-separated list of pixel values like this:

border-top, border-right, border-bottom, border-left

For example, entering

10, 0, 5, 1

Will result in a border that is 10px wide on top, 0px wide on the right, 5px wide on the bottom and 1px wide on the left.

Use within the javascript editor

this.<WidgetID>.setBorder("5,0,10,15")

LiveForm.borderColor

described in Control

Enter a border color for your widget; rgb and hex values are accepted: rgb(0,255,0) and #00FF00 are both valid entries.

You can also enter css color names, including black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white.

Use within the javascript editor

this.<WidgetID>.setBorderColor("rgb(0,255,0)");       
this.panel1.setBorderColor("#00FF00");
main.editor2.setBorderColor("purple");

LiveForm.captionAlign

This property sets the caption alignment (left, center or right) for all editors in the LiveForm.

LiveForm.captionPosition

This property sets the caption position (top, left, bottom, right) for all editors in the LiveForm.

LiveForm.captionSize

This property sets the caption size as a percentage of the total editor width for all editors in the LiveForm.

LiveForm.clearData

This property clears any data displayed in the editors within the studio live view.

LiveForm.dataOutput

This is an advanced property. It allows you to bind the editor values of the LiveForm to some other variable. For example, this could be used to populate the fields of a query or web service call.

The dataOutput property under the main properties window binds all the editors in the LiveForm to a single composite variable.

You can also bind to individual dataOutput variables by selecting the dataOutput submenu under Properties, as shown below:

LiveForm.dataSet

This property specifies the data type and input data for this LiveForm widget. The

• Grid selectedItem: this sets the input data for LiveForm to the currently selected row from a particular grid. This is the most common usage.
• LiveVariable: this sets the input data for a LiveForm to the value of a LiveVariable
• Service variable: this sets the input data for a LiveForm to the value of a Service Variable, such as a database query or web service call.

LiveForm.defaultButton

LiveForm.displayErrors

If unchecked, suppresses validation errors during input.

LiveForm.editorHeight

This property sets the height to apply to all the editors contained in this LiveForm. You can also set editor height individually to override this global setting.

LiveForm.editorWidth

This property sets the width to apply to all the editors contained in this LiveForm. You can also set editor widths individually to override this global setting.

LiveForm.fitToContent

described in Container

This property causes the containing widget to size automatically based on the size of the widgets it contains. The width and height are set to the cumulative maximum width and height of the contained widgets.

Use within the javascript editor

this.<UniqueID>.setValue("fitToContent", true)

LiveForm.fitToContentHeight

LiveForm.fitToContentWidth

LiveForm.freeze

described in Container

Checking the checkbox to freeze a containing widget makes it impossible to move any individual widget currently inside the container, however it is possible to drag new objects into this widget.

This is valuable for creating templates, where the border components (e.g., the chrome) are not meant to change, but the interior can be edited by other developers.

LiveForm.height

described in Control

The height of your widget can be specified in px or % (i.e 50px, 75%).

You can have a column of widgets that combined are more than 100% width; components will be allocated space based on the ratio of sizes (a 80% height widget gets twice as much space as a 40% widget).

Use within the javascript editor

this.<WidgetID>.setHeight("50%");  
this.label1.setHeight("40px");

LiveForm.horizontalAlign

described in Container

This property controls how contained widgets are aligned horizontally (e.g., left to right) within this widget container.

1. left: each widgets inside this container will be displayed left justified inside the container
2. center: each widget inside this container will be displayed centered horizontally inside the container.
3. right: each widget inside this container will be displayed right justified inside the container

Use within the javascript editor

this.<UniqueID>.setHorizontalAlign("right");

LiveForm.imageList

LiveForm.layoutKind

described in Container

This property controls how contained widgets are displayed within this widget container.

1. top-to-bottom: each widgets inside this container will be displayed below the other widgets inside the container
2. left-to-right: each widget inside this container will be displayed to the right of other widgets inside the container.

Use within the javascript editor

this.<UniqueID>.setLayoutKind("top-to-bottom");

LiveForm.liveEditing

Default value is true;

If true, then the LiveForm determines when the form elements are readOnly and when they are not.

Example: you open a live form, and nothing is editable; you hit the edit button, and now the liveform fields are editable.

You may want to set this to false if you want the live form to always be editable.

You may want to set this to false if you want to manage when the form is and is not editable.

This is intended to be set at design time, not when your project is running.

LiveForm.lock

described in Container

Checking the checkbox to lock a containing widget makes it impossible to select any individual widget inside the container.

This is similar to the "group" function in PowerPoint and makes it easy to cut and paste a group of object. It also ensures that an object cannot be accidentally dropped into a group of widgets.

LiveForm.margin

described in Control

Sets the margin in pixels for your widget. The margin for an object is outside of its border (the padding is inside the border).

Enter a single value like 5 to have a 5 px margin around the widget. To have margins with different widths, enter a comma-separated list of pixel values like this:

margin-top, margin-right, margin-bottom, margin-left

For example, entering

10, 0, 5, 1

Will result in a margin that is 10px wide on top, 0px wide on the right, 5px wide on the bottom and 1px wide on the left.

Use within the javascript editor

this.<WidgetID>.setMargin("5,0,10,15")

LiveForm.name

described in Component

The name is a unique identifier for your widget. Each page element and component must be uniquely identified. WaveMaker automatically renames any non-unique element.

The name makes it easy

1. Find the component in a bind dialog box
2. Find the component in your model tree
3. Reference the component in javascript

Use within the javascript editor

this.<UniqueID>.setShowing(true)

LiveForm.onBeforeOperation

This event is called before beginning an insert, update or delete operation.

LiveForm.onBeginDelete

This event is called before the delete database operation is called on a LiveForm.

This is useful to set perform any validation that should be performed before a record is deleted.

LiveForm.onBeginInsert

This event is called before the insert database operation is begun on the LiveForm.

This is useful to set default values, such as setting the primary or foreign key values of an object or setting the date value for a column to today's date.

LiveForm.onBeginUpdate

This event is called before the update database operation is performed on a LiveForm.

This is useful to set perform any actions which should occur before an update, such as multi-field validation.

LiveForm.onCancelEdit

This event is called whenever the cancel button is pressed for inserting, updating or deleting a record.

LiveForm.onDeleteData

This event is called after the delete database operation is completed on a LiveForm.

This is useful to set perform any actions which should occur after a delete, such as updating a LiveVariable to make sure it reflects the data that was just deleted.

LiveForm.onError

This event is called whenever a database insert, update or delete produces a database error message.

LiveForm.onInsertData

This event is called after the insert database operation is completed on a LiveForm.

This is useful to set perform any actions which should occur after an insert, such as updating a LiveVariable to make sure it include the new data that was just inserted.

LiveForm.onResult

This event is called after invoking an insert, update or delete service call, whether or not the service call was successful.

LiveForm.onSuccess

This event is called upon successful completion of an insert, update or delete.

LiveForm.onUpdateData

This event is called after the update database operation is completed on a LiveForm.

This is useful to set perform any actions which should occur after an update, such as updating a LiveVariable to make sure it include the new data that was just updated.

LiveForm.padding

described in Control

Sets the padding in pixels for your widget. The padding for an object is inside of its border (the margin is outside the border).

Enter a single value like 5 to have a 5 px padding around the widget. To have padding with different widths, enter a comma-separated list of pixel values like this:

padding-top, padding-right, padding-bottom, padding-left

For example, entering

10, 0, 5, 1

Will result in padding that is 10px wide on top, 0px wide on the right, 5px wide on the bottom and 1px wide on the left.

Use within the javascript editor

this.<WidgetID>.setPadding("5,0,10,15")

LiveForm.readonly

If checked, this property specifies that all the editors in this LiveForm widget will be read only.

LiveForm.removeEditors

The removeEditors button removes all editors inside this LiveForm.

LiveForm.scrollX

described in Control

The ScrollX property enables you to turn on scrollbars for this widget such that more contents than would normally fit into its allocated width can be accessed. Technically, this sets the overflow style to scroll or to none.

Use within the javascript editor

You may want to programatically access this after changing the contents of this widget at runtime.

this.<WidgetID>.setScrollX(true);

LiveForm.scrollY

described in Control

The ScrollY property enables you to turn on scrollbars for this widget such that more contents than would normally fit into its allocated height can be accessed. Technically, this sets the overflow style to scroll or to none.

Use within the javascript editor

You may want to programatically access this after changing the contents of this widget at runtime.

this.<WidgetID>.setScrollY(true);

LiveForm.showing

described in Control

Showing determines whether or not a component is visible. A page element that is not showing has its css display style set to none; it is still a part of the DOM model of the page, but no longer affects the layout of other components.

Uncheck the checkbox to make this widget invisible. A widget that is not showing can still be selected by navigating to that widget in the model tree and clicking it.

Use within the javascript editor

this.<UniqueID>.setShowing(true)

LiveForm.validateBeforeSave

If this is checked, reviews all required fields and if any of the required fields do not have values, will refuse to submit it to the server, and will alert the user of each field that needs to be populated.

This property may evolve in future versions to refuse to submit to server if any validation tests fail.

The default behavior is to attempt to submit to the server whatever the user has entered, and then let the server report an error to the user.

LiveForm.verticalAlign

described in Container

This property controls how contained widgets are aligned vertically (e.g., top to bottom) within this widget container.

1. top: each widgets inside this container will be displayed aligned to the top of the container
2. middle: each widget inside this container will be displayed centered vertically inside the container.
3. bottom: each widget inside this container will be displayed aligned to the bottom of the container

Use within the javascript editor

this.<UniqueID>.setVerticalAlign("middle");

LiveForm.width

described in Control

The width of your widget can be specified in px or % (i.e 50px, 75%).

You can have a row of widgets that combined are more than 100% width; components will be allocated space based on the ratio of sizes (a 80% width widget gets twice as much space as a 40% widget; they will fit in the designated space even though the sum is 120%).

Use within the javascript editor

this.<WidgetID>.setWidth("80px");