Create Custom Controls

Create a custom control to design a control with specific or custom properties.

To create a custom control

1. Create a DLL project (Visual C# > Windows > Class Library) using Visual Studio.NET.

2. Create or add two .cs files – SFControls.cs (control initialization file) and MyCustom.cs (public control class file) to your project.

3. Add a reference to the Skelta.Forms.Core.dll (located at <AVEVA Work Tasks Install Path>\Bin folder) in your project.

4. Add the following namespaces to your MyCustom.cs file.

   using Skelta.Forms.Core;
   using Skelta.Forms.Core.External;
   using Skelta.Forms.Core.CommonObjects;
   using Skelta.Forms.Core.Controls;
   using Skelta.Forms.Core.Interfaces;

5. Ensure the control class (MyCustom.cs) inherits from the BaseDataExternalControl class.

6. Write the control definition code with the following in mind:

   1. Ensure the Core Designer is set to Next Generation Designer and the Designer Category is set to Custom to show up the control in the toolbox of the Forms Designer.

      [DesignerControl(992200, CoreDesigner.NextGenDesigner, DesignerCategory.Custom)]
      public class MyControl : BaseDataExternalControl

   2. Suppress properties, if required, using the attribute SuppressedPropertiesNextGen.

      // Suppress properites PropertyName1, PropertyName2, and PropertyName3.
      [SuppressedPropertiesNextGen("PropertyName1;PropertyName2;PropertyName3;")]

   3. Override the GetNewInstanceForClone() function, create an instance of the control, and assign the basic properties of the control.

   4. Override the GetControlHtml() function and define the HTML code. Use the TopLevelForm.InDesignMode boolean variable to segregate the designer and run-time views, if required. Ensure all view model properties are specific to the instance defined in the view.

   5. Override the GetViewModelDefinition() function (if required) to define the ViewModel definition of the Knockout binding based on the custom control Binding Attribute (For more information, see Binding Attribute in Attributing Properties). Ensure all view model properties are specific to the instance defined in the view model. For more information, see Autocomplete.cs.

   6. Override the GetViewModelScript() function (if required) to define the ViewModel script based on the predefined named script like Value, Validate, Mandatory and so on.

   7. Ensure you add the JS file reference to this.TopLevelForm.RuntimeJS variable to add custom JS files referred by the custom control. The variable is a key value pair collection where the key is the file name and the value is the file path (absolute or relative). Also ensure the JS files are present in the BPMUITemplates/Default/NextGenForms/custom/js folder. Otherwise, it will not be rendered.

      Note: For the earlier versions of the product, ensure the JS files are present in the BPMUITemplates/Default/NextGenForms/js folder.

   8. Ensure you add the CSS file reference to this.TopLevelForm.RuntimeCss variable to add custom CSS files referred by the custom control. The variable is a key value pair collection where the key is the file name and the value is the file path (absolute or relative). Also ensure the CSS files are present in the BPMUITemplates/Default/NextGenForms/custom/css folder. Otherwise, it will not be rendered.

      Note: For the earlier versions of the product, ensure the CSS files are present in the BPMUITemplates/Default/NextGenForms/css folder.

   9. Define rules for a custom control to validate the data using the client-side JavaScript, if required. For more information, see Rules and Defining Rules.

   10. Create class properties as control properties.

       //Designer Property
       [DesignerProperty(773000, Categories.Validation, CoreDesigner.NextGenDesigner)]
       //Binding Property
       [BindingAttribute(882995, "Skelta.Forms.Core.CommonObjects.IntegerBindingProperty")]
       

7. Create SFControls.cs class under Skelta.Forms.ExternalControls namespace.

8. Add the following namespaces to your SFControls.cs file.

   using Skelta.Forms.Core.Controls;
   using Skelta.Forms.Core.External;
   using MyCustomControls; // Control namespace

9. Implement the IExternalControls in the SFControls class.

   1. In the IExternalControls.GetControl(string controlFullName) method, return the new control instance based on the control namespace.

   2. In the GetControls method, return a new object array which contains all the control instances.

10. Build your project, create a SOA folder on your hard drive (for example, C:\SOA), place your custom control DLL file in the folder, and then register the location of the folder with the Skelta SOA Folder List.

11. Register the custom control DLL file through the Form Controls to display the custom control in the controls or custom category. For more information, see Custom Categories.

    Note:
    - Control initialization file must always be named as SFControls.cs and the class name must always be named as SFControls.
    - Ensure reference to the Skelta.Forms.Core.dll assembly is the same as the assembly on the AVEVA Work Tasks server.
    - For information about SOA, see Object Access in the Workflow Management User Guide.

To localize the text for the custom control

• See Localization.

To add an icon to a custom control

12. Add a custom icon in the <AVEVA Work Tasks Install Path>/Web/BPMUITemplates/Default/NextGenForms/Themes/<ThemeName>/images folder.

    Note:
    - If the image name is tagged with FormCustomPath:, the location is <Installpath>/Web/BPMUITemplates/Default/NextGenForms/custom/images/MyImage.png
    
    - If the image name is tagged with or FormCustomThemePath:, the location is <Installpath>/Web/BPMUITemplates/Default/NextGenForms/custom/images/MyImage.png
    
    - If the image name is not tagged with FormCustomPath: or FormCustomThemePath:, the location of image of earlier version will be considered i.e. <Installpath>/Web/BPMUITemplates/Default/Themes/<ThemeName>/ NextGenForms/images folder.

13. Open the SkeltaCustomControlDesigner.css file in the <AVEVA Work Tasks Install Path>/Web/BPMUITemplates/Default/NextGenForms/Themes/<ThemeName>/custom\css folder.

    Note: If the stylesheet name is not tagged with FormCustomPath: or FormCustomThemePath:, the location of stylesheet of earlier version will be considered.

14. Add the following style to the SkeltaCustomControlDesigner.css file.

    /* Replace <custom_icon> with the file name for the normal icon. */
    /* Replace <namespace.classname> with the custom control namespace and class name. */
    .sktbci[data-skttp="<namespace.classname>"]
    {
    background-image: url(../../images/<custom_icon>.png);
    }
    /* Replace <custom_icon_hover> with the file name for the hover icon. */
    .sktbc:hover > .sktbci[data-skttp="<namespace.classname>"]
    {
    background-image: url(../../images/<custom_icon_hover>.png);
    }

15. Save the SkeltaCustomControlDesigner.css file.

16. Reload the Forms Designer page to see the custom control with the custom icon in the toolbox.