Introduction to scripting with layouts

Use this general information as a guide when you write server-side scripts for portal layouts.

Scripting help

Use IntelliSense within the script to find which APIs (methods) and events are available in the current context. For example, you can type context.Alert within the script to see a list of the Alert events that are available in the current display layout. Then you can hover over each of the listed methods or events to see additional information about how to use it.

Inheritance

Each script defines one class that inherits from a generic scripting class that is appropriate to the layout type. For example, this line is from a script in a layout used with the IPFGrid FDF:


Public Class CustomCode: Inherits IPFGridCustomCode

In this example, the name you defined for the class is CustomCode. The IPFGrid FDF looks for a class that inherits from the IPFGridCustomCode class. Use the layout type’s script template to determine which generic class to inherit from.

Registering custom APIs and associating them with events

Events occur during the execution of layouts and are entry points for your custom code. For example, the ItemLoaded event occurs after a record has been loaded from the data source.

Your custom class must implement an API called OnScriptInitializing. This API registers event handlers for the various entry points into the class. For example, if you want some custom script to be executed when a record is loaded from the data source, you could define this API:


Public Sub OnItemLoaded()
	ByVal context As GridItemLoadedContextI,
	ByVal parms As GridItemLoadedParmsI)
	...Your Custom Code Here...
End Sub

In order for your custom API to be executed, you must associate the API with an event. For example, to associate the ItemLoaded event with your OnItemLoaded API, add this line to the OnScriptInitializing API:


AddHandler ItemLoaded, AddressOf OnItemLoaded

This registers your OnItemLoaded API, which will then be called when the event occurs.

The events with which you can associate custom code are described in Events associated with layouts.

API parameters

The parameters of registered APIs must match the parameters passed in by the layout. If they do not match, IntelliSense displays an error and the script does not compile.

All layout APIs take two parameters:

  • The first parameter gives access to the context of the event.

    Using the example shown in the previous section, the first parameter contains general APIs that might be needed by your code, such as error logging, data source access, or the user interface.

    
    ByVal context As GridItemLoadedContextI
    

    For more information about the general APIs that are available to your scripts, see API quick reference.

  • The second parameter contains the APIs and parameters specific to the event that just occurred.
    
    ByVal parms As GridItemLoadedParmsI
    

    In this example, a record was just loaded, so information about that record is made available through this parameter.

Imports statements

The scripting templates contain Imports statements appropriate for the layout type. If you want to change these statements, be aware that System.dll and System.Core.dll are the .NET assemblies available to the scripts.

Data types, properties and components

A property is one field of data on a record. There are two types of properties:

  • A bound property is persisted by the data source. Bound properties are stored internally in the data type that is defined by the data source. If you try to put data into a bound property that the system cannot convert to the underlying data type, the script produces an error.
  • An unbound property has no intrinsic data type and accepts any data you assign to it, no matter the type.

When you include a property in a display layout, the system checks whether the underlying data source has a field with the same name. If so, the property becomes a bound property and takes on the appropriate data type. Otherwise the property is an unbound property.

If a property is displayed as part of the layout, it is automatically associated with a bound component. Any data in the property is automatically displayed in the bound component.

A component that is not associated with a property is an unbound component. An unbound component has no intrinsic data type and accepts any data you assign to it, no matter the type.