Skip to content

Configurable Widgets

Widgets can be configurable. This means that a portion of your widget can be changed at runtime through configuration, allowing it to, for example, use different data, look slightly different, or perform a different navigation.

An example would be a widget containing a list of your 10 latest orders. Through configuration, you could add a property that filters this list based on the order total to only show orders with an order total greater than $1000.

The idea is that through configuration, you can have a single Widget class with slightly different data or behavior, without having to completely create a new Widget for this. You can have multiple instances of this Widget in a container, and by using configuration, they’ll look or behave slightly different.

The steps to make a widget configurable are as follows:

  1. Optionally add new Web Properties to your widget to be used for configuration.
  2. Mark which properties are configurable:
  3. Use OnGetConfigurableProps for this in the Widget. Add your tWidgetConfigProp to the ByRef Array.
  4. Use CreateConfigurableProp function for convenience to get you started, passing the Object handle and Property to make configurable.
  5. Use the (Widget(Self)) instruction if your property exists in the Widget root.
  6. Attach a cWebWidgetConfigurationWizard to your Widget:
  7. Set phoConfigWizard to a cWebWidgetConfigurationWizard implementation.
  8. You can build your own custom wizard or use the provided cWebWidgetConfigurationWizardStandard.
  9. Optionally manipulate a widget’s configurable state through pbAllowConfiguration and the augmentable OnDetermineConfigurableState event.

To build a custom cWebWidgetConfigurationWizard:

  1. Create an object (or class if you want to create multiple instances) that’s a subclass of cWebWidgetConfigurationWizard.
  2. The wizard is basically a dialog with some interface logic in there. Place any DataDictionaries, Controls, etc., that you need inside.
  3. Implement the following:
  4. OnPopulateWizard: Comes with a tWidgetConfigPropValue array. Use this to populate your wizard’s controls with the Widget’s current configurable property values.
    • You can use ParkPropValue to temporarily store a value for later use. Make sure you remember the sObjName and sPropName as these are used as the unique identifiers for retrieving via RetrieveParkedPropValue.
    • Use convenience function GetPropValue for easier sifting through the array.
  5. OnGetConfigValues: Used when closing the wizard. Use this to get the new values from your Wizard’s controls so they can be fed back into the corresponding Widget. Comes with a ByRef tWidgetConfigPropValue array to be filled with the new values.
    • Use convenience function SetPropValue for easier adding of a value to the array.
    • Make sure the sObjName and the sPropName of the new values match with the existing ones, as this is used to map to the Widget’s configurable property.