Using Iron Python Scripting in PowerForms

Python scripting is a powerful tool for your customizations.

You can find here some common scripts you can use in your forms.

IMPORTANT: Python uses “Significant Whitespace”, meaning that whitespaces in front of commands are important for the interpreter to identify code blocks.

You can apply scripting to either Control Value Change events, or to handle the Form Validation and the completion of Form loading.

For Value Change events, you can apply the script in the control properties window, in the Scripts tab.

Variables :

control : this variable points to the control that raised the event.

template : this variable references the current form

IMPORTANT :

Value Change events are raised when controls value change. This happens both by user interaction or during form loading.

When the form initializes to display an existing record, it sets the appropriate record values to controls, one by one.

This also raises the ValueChange event so users should be carefull when writing scripts because some actions should only happen on user action.

For example you may want when the STATUS control of your form is set to “CLOSED”, to set a value to the “ClosedBy” control. Since the ValueChange event would also be raised when editing an existing record, this script should only be executed when a user makes that change.

For that reason, a property exists in the “template” object called “Loaded” which indicates if the form has finished loading or not.

So for our example you should write something like the following :

The form Validation event is raised just before submitting the record for save.

Variables :

template : this variable references the current form

result : boolean variable that should be returned according to the validation result. Return False when validation fails

error : string variable that should contain the error messagee that should be displayed to the user.

Example :

IMPORTANT :

You should always define the “result” and “error” variables for validation to work as expected.

You should initialize the “result” to True and the “error” variable to a blank string, and then perform validations. In case validation fails, you should set False to the “result” variable and fill the “error” variable with the error message you want to display to the end user.

This event is raised after the controls have been placed on the form and before the data item values are applied.

Variables :

template : this variable references the current form

dataitem : this variable contains the fieldName/fieldValue pairs of the actual data from the record.

Available methods for the dataitem :

dataitem.GetValue(“ColumnName”)

returns the value from the record

dataitem.GetValue_Value(“ColumnName”)

returns the ID part of a lookup column value

dataitem.GetValue_Name(“ColumnName”)

returns the TITLE part of a lookup column value

Example :

control.SetValue(string) 

Sets the value to a control

control.GetValue()

Retrieves the current value of the control (string).

GetValue_Value()

Retrieves the “value” portion of the control value in case of lookup columns where the value is in the ID;#NAME format

GetValue_Name()

Retrieves the “name” portion of the control value

GetDisplayValue()

Some controls return a user-friendly representation of their value.

SetFontBold(bool)    (For boolean operations you should use “True” or “False”)

SetForeColor(string)

Sets the foreground color of a control. You can use named colors (“White”, “Red”, etc) or hexadedimal colors (i.e. “#AB557D”)

SetBackColor(string)

Sets the background of the control

SetBorderThickness(int)

Set a control to look required under conditions using script

SetBorderColor(string) 

SetEnable(bool)

SetVisible(bool)

GetVisible()

Returns if the control is visible or not

SetReadOnly(bool)

 

 

GetControl(name)

Retrieves a control from the form

Loaded

The “Loaded” property is readonly and returns True if the form initialization has completed. Otherwise it returns False.

SaveRecord(), SaveAndExit()

Saves the current record. Can be used inside Action Buttons to apply Save operations to the form without using the default toolbar buttons.

DeleteRecord()

Deletes the current record

CancelRecord()

Cancels the record editing

GetListId(), GetListName(), GetListUrl()

Retrieves list metadata

ReloadValue(controlName)

Reloads the value of a control

EnableTab(int index)

Enables a form tab. The index is zero based. (0 for first tab, 1 for the second, etc)

DisableTab(int index) 

Disables a form tab

ShowTab(int index) 

Shows a (hidden) form tab. Index is zero based.

HideTab(int index) 

Hides a form tab

ExecuteJavascript(string script)

Executes javascript command(s).

SaveRecord(url, listName, data) 

Saves a record (Insert or Update depends on the ID value provided)

SaveRecord(url, listName, data, callback) 

Saves a record and calls a callback method when complete

DeleteRecord(url, listName, id, callback) 

Deletes a record

LoadRecord(url, listName, id, callback) 

Loads an existing record.

Example : LoadRecord(“http://servername/sitename, “TestList”, “1”, callback)

where “callback” is a method defined inside script

SetDataItemValue(fieldName, value)

You can use this method to set values to the current record. If you set values to fields bound to controls, the values will be overriden before record update. So it can normally be used for columns that do not have a bound control on the form.

GetDataItemValue(fieldName)

Retrieves a value from the underlying record (this value may be different from the current value inside the bound control)

SetSectionBackColor(index, color)

Changes the background color of a section on the form.

SetSectionBorderColor(index, color)

Changes the border color of a section on the form.

SetSectionBorderThickness(index, thickness)

Chages the border thickness of a section on the form

SetSectionHeader(index, headerText)

Changes the header/caption of a section

 

ReloadRecord()

Reloads the current record from the SharePoint list

 

ExpandSection(index)

Expands the form section

 

CollapseSection(index)

Collapses the form section

 

HideButton(string)

Hides a toolbar button. Available values are : “New”, “Save”, “SaveAndExit”, “Delete”, “Cancel”, “Edit”, “Help”, “Design”, “Customizations”

 

ShowButton(string)

Shows a (hidden) toolbar button. Available values are : “New”, “Save”, “SaveAndExit”, “Delete”, “Cancel”, “Edit”, “Help”, “Design”, “Customizations”

 

SetGlobalVariable(string, object)

Sets the value for a global variable. Global variables are created inside the “LoadCompleted” script.

ExecuteSQLQuery(string queryListUrl, string queryListName, string queryName, FieldValue[] parameters, callback)

Executes a SQL Query defined in the specified list. Read more about how to define a sql query here.

ExecuteSQLQuery(string queryName, callback)

Executes a predefined sql qeury (from the Sql Queries section of the designer)

CallWebService(string wsName, callback)

Executes a predefined web service (from the web services section of the designer)

 

Change Control Appearance depending on control value 

Import a .Net namespace

Show a confirmation dialog

Exception Handling

Asynchronous Methods / Save a new list item

Load Records using criteria from the form / Perform Calculations

 

Instead of using scripting in various form events, scripting may be applied with the ActionButton control.

For extensive language reference use the following links :

http://ironpython.net

http://en.wikipedia.org/wiki/IronPython