BPC-Components

Home > Products > BPC PowerForms - Silverlight > Knowledge Base > Controls > Control Properties

Control Properties

In order to design your form, a number of control types is available for you to select from.
At the time PowerForms is registered for a List or Document Library, the system automatically tries to detect list column types and selects the appropriate control for each column.
For example for single line of text columns the Textbox control is selected, for Lookup columns, the ComboBox control is added to the form and so on.
For columns that are not recognized (like custom column types) the TextBox controls is used by default.

PowerForms provides the maximum flexibility in designing forms, so for each list column, 2 separate controls are added on the form :
- The actual control holding the column data
- The label for that control (always a Label control)

These controls can be placed anywhere independently allowing users to achieve the desired result everytime.

Each control type has its unique characteristics but they all share some common attributes like :
- Name
- Binding
- Required
- Enabled
- etc.

These properties can be changed within the Properties Editor page which can be opened by clicking on the gear button at the bottom-right corner of each control inside the designer.

 


The properties window

You can setup control properties using the following property sections / tabs :

 

General Tab

 

 

The most basic control properties are defined here.

Name
A unique name should be provided to each control. It is useful to identify controls in the designer as well as use that name in formulas or within script.

Type
Defines the type of the control. Depending on the column type, a lot of controls are available to display column data.

Multiline
For TextBox controls the Multiline property can be used in order to define that the control will accept multiple lines of text.
This only applies to the TextBox control as for Rich Text columns, the RichTextBox control can be used which by default supports multiple lines of text as well as rich content.
If the control type is different from TextBox, the Multiline property is unavailable.

Binding
For each control there are 3 different options on binding :

- The control is bound to a list column (option : The control saves its values in a list column)
This means that the control will try to show the value of the corresponding column and the value provided in that control will be used to save data for that column.
If the options is selected, the Column Name property must be supplied too.

- The control is a label for a bound control
This means that the control (usually a Label) is defined as the Label for a bound control.
These controls are created by the system.

- The control is unbound
This option indicates that the control will not display any value from the selected list item or save its value to a list column.
Instead, it can have a static value, display a value calculated from a formula, receive its value from a list query or a web service, etc.
This option can be selected in order to add static text to a label just to provide instructions to the users, retrieve and display a value relative to the form data and so on.

Enabled On New / Enabled On Edit
These options are used to disabled controls on when creating new or opening existing records.
If a control must be enabled all the time, these options should be both checked.
There are cases when a user should be able to enter a value for a list column only for new or only for existing records.
Example 1:
A user may select the customer for a sales order when adding a new record but is not allowed to change it afterwards.
In that case, the Enabled On Edit option should be unchecked providing the required result.
Example 2:
The title of a record should be automatically calculated (through a formula) when adding new records but the user may change that title when editing that record.
In that case the Enabled On New option should be unchecked and the value should be applied through a formula or script.

ReadOnly
This option only applies to some controls. When selected, it disabled input in that controls but allows users to copy the value.
If the control does not support the ReadOnly property, these controls are disabled.
For example the TextBox, LookupPikcer, MultiLookupPicker, TreeViewPicker, RichTextBox controls can be set to be ReadOnly.

Enabled Formula
There are cases when some controls should be enabled or not under certain conditions.
These conditions may depend on form data or user properties (like name, id or group).
The property should contain a valid formula that should evaluate to a boolean (true or false) value.

Example 1: (Checking control values)

Code
FieldValue("c_Status") = "Closed"

The same result may be accomplished with the following formula :

Code
"{c_Status}" = "Closed"

This happens because the {control_name} keywords are replaced with the control values before evaluating formulas.

Example 2: (Checking user attributes)

Code
UserInGroup("Guests")
or
UserID() = "3"
or
UserInGroupById("12")
or
UserFullName() = "Administrator"

Read more on formulas.

Value Tab

 

 

This tab contains the required properties to determine where the value of the control comes from.

By default, every control is set up to receive its value from the user (meaning that the end user will have to type/set the required value).

Exceptions:

- Label controls by default are set the have static values (since their value cannot be set by users)

- Buttons should have static value that represents the text inside the button control.

To define a static value for a control, select the "Value is static" option and type the corresponding value in the available textbox.

For controls with calculated values based on formulas, select the "Value is calculated by a formula" option and provide the formula.

Values in control can come from List Queries already defined in the List Queries section of the designer.

Each list query may retrieve more than one record (depending on criteria) and may have more than one field values retrieved.When setting a control to receive its value from a list query, the value of the first field of the first record retrieved is set  to that control.

So users should be carefull when defining criteria for list queries in order to accomplish the expected results.

Similar to the List Query, a control may receive values from a web service call. The web service should be defined in the special section of the designer.

The last option is to define a uri (absolute) that will be called and the response will represent the value for the control.

For example, there may be a web page that accepts the ID of a customer and returns the balance. The following uri can be used. The {c_ID} key will be replaced with the run-time value of the referenced control.

Layout Properties

 

Here you can define the layout properties of the control like Size, Color, Font, etc.

Details on how to use the layout properties can be found HERE.

 

Lookup Details

This tab applies only to controls that lookup data in other lists like ComboBox, LookupPicker, AutoCompleteTextbox, MultiRadioButtons, MultiCheckBoxes, etc, as well as PeoplePickers.

Most of the controls in this tab are used by lookup controls.

The "PeopleOnly" and the "Specific Group(s)" properties are used for PeoplePicker controls.

 In order to load data inside a lookup control from a list, you must fill in the following information :

First provide the Lookup Url. This should be the url of the site containing the list we want to query.

For example : http://server1/site1

Loosing focus from that control (i.e. by pressing the tab key), forces loading the lists of the specified site.

The lists are filled in the "Source List" combobox.

As soon as a list is selected from that combobox, the available views are loaded inside the "Source View" combo.

You can define additional criteria for your list query using the criteria editor. Details on setting up your criteria can be found HERE.

Constraints:

There are lookup controls that their values should be filtered using existing values from other controls on the same form.

Cascading lookups can be defined using the "Constraint By" - "Match To" properties.

"Constraint By" represents the column value that the system will use to query the target list.

"Match To" represents the column in the target list that will be queried using the "Constraint By" value.

Extra Configuration

Each control may have some extra properties that can be defined in the "Extra" tab to enhance control appearance and behaviour.

Details on the Extra Control Configuration can be found HERE.

 
A complete reference for the Extra Configuration properties for the available controls can be found HERE.

Scripts

Additional customization can be added on the behaviour of controls, using script.

Python script is supported in the Script tab where you can write the script that will be executed every time the control value is changed.

For this script, 2 variables are available to use :

"control" : Represents the actual control raising the Value Change event

"template" : Represents the parent form containing all form controls.

Available functions for controls and the form template can be found HERE.