Custom controls

  • This feature is available to advanced users with extensive knowledge of Cascading Style Sheets and JavaScript. Use this feature only if you fully understand CSS and JS, as using these programming languages may affect the way the control display and behave on your view or form.
  • You need to be part of the Control Administrators role to create, edit, or delete a custom control.
  • If you create custom controls, you're fully responsible for maintaining them.
  • We do not recommend editing controls that are already configured and in use in production. Modifying a control alters its definition and may affect how it renders at runtime. To safely make changes, first remove all instances of the control from every view and form, then edit the control as needed, and finally re-add it to the desired views and forms.

You can create your own custom controls in Management providing more flexibility and extensibility to the K2 product. Once created, these controls are available in the Designer for use in views and forms.

To upload a custom control, a zipped file is required including the following:

  • JavaScript files (runtime and design-time)
  • Icons
  • CSS files
  • Manifest file called manifest.json

The following is a simplified manifest scaffold illustrating the top-level fields, properties, events, methods, and parameters.

Copy 
{
                                "icon": "icon.svg",
                                "displayName": "Your Control Name",
                                "tagName": "your-control-name",
                                "description": "A brief description of what this control does and its main features.",
  
                                "designtimeScriptFileNames": ["designtime_logic.js"],
                                "runtimeScriptFileNames": ["runtime_logic.js"],
                                "designtimeStyleFileNames": ["designtime_style.css"],
                                "runtimeStyleFileNames": ["runtime_style.css"],
  
                                "supports": [
                                "Width",
                                "Height",
                                "Value",
                                "IsVisible",
                                "IsEnabled",
                                "IsReadOnly",
                                "DataBinding"
                                ],
  
                                "properties": [
                                {
                                "id": "TextProperty",
                                "refreshdisplay": "true",
                                "friendlyname": "Text Property",
                                "type": "string",
                                "inputlength": "255",
                                "initialvalue": "",
                                "changesdisplay": true,
                                "description": "Example string property"
                                },
                                {
                                "id": "BooleanProperty",
                                "refreshdisplay": "true",
                                "friendlyname": "Boolean Property",
                                "type": "bool",
                                "initialvalue": false,
                                "changesdisplay": true,
                                "description": "Example boolean property"
                                },
                                {
                                "id": "DropdownProperty",
                                "refreshdisplay": "true",
                                "friendlyname": "Dropdown Property",
                                "type": "drop",
                                "initialvalue": "option1",
                                "changesdisplay": true,
                                "description": "Example dropdown property",
                                "dropitems": [
                                { "value": "option1", "text": "Option 1" },
                                { "value": "option2", "text": "Option 2" }
                                ]
                                }
                                ],
  
                                "events": [
                                {
                                "id": "OnChanged",
                                "friendlyname": "Changed"
                                },
                                {
                                "id": "OnCustomEvent",
                                "friendlyname": "Custom Event"
                                }
                                ],
  
                                "methods": [
                                {
                                "id": "simpleMethod",
                                "displayname": "Simple Method",
                                "returntype": "None",
                                "description": "Example method without parameters",
                                "parameters": []
                                },
                                {
                                "id": "methodWithParameters",
                                "displayname": "Method With Parameters",
                                "returntype": "string",
                                "description": "Example method that accepts multiple parameters and returns a value",
                                "parameters": [
                                { "name": "textParam", "type": "text" },
                                { "name": "numberParam", "type": "number" },
                                { "name": "boolParam", "type": "bool" }
                                ]
                                }
                                ]
                                }
                            

To allow the control to interact with rules, you must create the control's events, properties, methods, and files that will be exposed in the rule designer and properties panel in the Designer.

The rules that are available for a control depend on the events and methods specific to your control. The following code snippet is an excerpt of the manifest.json file and the entries used to create the events and methods for the rules.

Example of a control containing two events and two methods:

Copy 
"events": [ 

    { "id": "OnChanged", "friendlyname": "Changed" }, 

    { "id": "OnButtonClick", "friendlyname": "Button Clicked" } 

  ], 

 

"methods": [ 

     { 

      "id": "clearSelection", 

      "displayname": "Clear Selection", 

      "returntype": "None", 

      "description": "Clear the current selection", 

      "parameters": [] 

    }, 

    { 

      "id": "selectById", 

      "displayname": "Select By ID", 

      "returntype": "None", 

      "description": "Select a button by its ID (value property)", 

      "parameters": [ 

        { "name": "id", "type": "text" } 

      ] 

    } 

  ], 

Certain rules such as transfer data and set control properties depend on the properties of your control and whether they have get/set methods.

The following code snippet is an excerpt of the manifest.json file and the entries used to create properties.

Example:

Copy 
"properties": [ 

    { 

      "id": "Value", 

      "refreshdisplay": "true", 

      "friendlyname": "Value", 

      "type": "string", 

      "inputlength": "255", 

      "initialvalue": null, 

      "changesdisplay": true 

    }, 

    { 

      "id": "List", 

      "refreshdisplay": "true", 

      "friendlyname": "List Items", 

      "type": "listdata", 

      "category": "Detail", 

      "initialvalue": "[{\"display\": \"Item 1\", \"value\": \"1\"},{\"display\": \"Item 2\",\"value\": \"2\"}]" 

    } 

] 

The CSS must be correctly scoped using the appropriate tag name in each selector, for example: Text-control.label. The tag name used in the CSS must match the tag name defined in the manifest.json, as both the CSS and the runtime will reference this tag. While the tag name should follow the standard rules for custom HTML elements, the system allows tag names to begin with capital letters.

Copy 
Text-control .container {
    display: flex;
    justify-content: stretch;
    position: relative;
    padding-top: 20px;
}

Text-control .input {
    flex-grow: 1;
    outline: none;
    border: none;
    padding: 0px;
    padding-bottom: 5px;
    background-color: #3CBCFF;
    color: white;
}

Text-control .label {
    pointer-events: none;
    position: absolute;
    top: 0px;
    bottom: 0px;
    left: 0px;
    right: 0px;
    border-bottom: solid 1px #777777;
}

Supported control icon file types:

  • SVG
  • JPG
  • JPEG
  • PNG

Supported control image file types:

  • SVG
  • JPG
  • JPEG
  • PNG
  • GIF

A custom control inherits the styling used on a view or a form. You can use style profile variables when creating the stylesheets to apply styles to your custom control. This styling is limited to the Dynamic theme. Custom variables for style profiles are not supported

Check out the Nintex Gallery for examples of custom controls in the K2 section. See also the following resources for a modern web-based development environment for K2 custom controls with both debugging and control generation capabilities.

To create, edit, or delete a custom control, you must be part of the Control Administrators role in Management. Navigate to Management>Users>Roles, then add a user to the Control Administrators role.

  1. In the Roles page, search for Control Administrators, using the Search function if necessary.
  2. Select Edit from the menu to update the properties of Control Administrators.
  3. Use the Search bar to find the required user, select the user, then click Add to include the user as a control administrator.

Refresh Management to see the Custom Controls node.

Manage custom controls in Management>Custom Controls.

The Custom Controls node in Management is only available after a user is added to the Control Administrators role.

Add the zipped file containing your custom JavaScript, icons (SVG, JPEG, JPG) , CSS, and manifest,json files to Management>Custom Controls.

Follow the steps below to upload the zipped file:

  1. Navigate to Management>Custom Controls.
  2. Click New.
  3. Drag the zipped file into the Upload file box of the Add control dialog box or click the link to upload a file.
  4. The zipped file is uploaded and decompressed to populate the necessary fields in the Custom Controls page. Click Next.
  5. The Add control page shows the display name, the description, and the display icon. This page is populated from the information provided in the uploaded file.
  6. Click Save.

The list is updated with the custom control name, description, file name, and the icon, similar to the example below.

When a new custom control is added, it is available to all users.

Custom controls in forms and views

Once a control is created in Management, it's available in the Custom section in the Toolbox of a view and form. The custom control can be dragged into the design canvas of either a view or form.

To view new custom controls, you must refresh the Designer.

  • We do not recommend editing controls that are already configured and in use in production. Modifying a control alters its definition and may affect how it renders at runtime. To safely make changes, first remove all instances of the control from every view and form, then edit the control as needed, and finally re-add it to the desired views and forms.
  • When a custom control is edited, it is available in its updated state to all users.

To edit a custom control navigate to Management>Custom Controls and select the custom control to update.

  1. Click Edit, then update the control as required.
  2. Click Save to save the changes.

To delete a custom control navigate to Management>Custom Controls.

  • Deleting a control from the list of available controls in Management>Custom Controls removes the control for all users.
  • A custom control cannot be deleted if instances of the control appear in an existing view or form. Ensure you delete all instances of the control from all views and forms before you delete it from Management.

Select the custom control to remove, then click Delete.

Click Refresh to refresh the list of custom controls.

A custom control can be downloaded for storage or deployment to another environment. Select a control, then click Download.

The Details option allows you to view the details of the control such as contact person, who uploaded the control, and who last modified the control. You can also see the views and forms containing the control. Click the link to open the view or form in the Designer. Use the search and filter to view specific views, forms, or controls.

You can specify how you want to filter and sort the results by configuring the Filter and Sort options. You can also use the quick search function to refine your search.

When creating a new filter, remember to set it as the default to apply the filter to the results.

When you click the Configure a new filter icon, the Configure User Filters page opens. You can type a value or use the Context Browser to drag and drop a value in the Value field.

Feature Description
Add Adds a new line for you to apply a filter
Remove Removes a filter line
Remove All Removes all the filter lines
Advanced See the Advanced Filter Options section below
Field The field to use in the filter
Operator Operator to be used in the filter
Value Value to be used in the filter. Type a value or drag and drop a value from the context browser

When you click Advanced on the Configure Filter Options page, the Advanced Filter Configuration page opens. You can configure advanced expressions such as the one shown in the image below. When you use fields to filter data, you must match the value on the right side with the data type of the SmartObject field. For example, the region ID of 2 filter matches the data type of the ID field, which is number. The filter would not work if you specified a region name using text or a field containing text.

Feature Description
Conditions

You can specify conditions containing a value on the left, an operator, and a value on the right. You can type a value or use the context browser to drop a field. As you add conditions, they are listed and given a number on the left. You can use this number to build or edit your expression using the Expressions section. To remove a condition, select the entire condition and click Remove. The following operators are available:

  • Equals or Not Equals
  • Greater Than or Less Than
  • Greater Than Equals or Less Than Equals
  • Contains
  • Starts With or Ends With
  • Is Empty or Is Not Empty

For more information about building expressions see Expression Builder.
Expressions Combines the conditions using logical operators such as And and Or. You can:
  • edit the logical operators by clicking on the down arrow.
  • change the order of the conditions by clicking on the down arrow next to the number and select another condition.
  • add brackets by clicking on the white spaces between each condition to group conditions as shown in the image above. If you do not apply brackets, the Or and And operators have the same precedence. By applying brackets, you can control the order of execution.
Make sure that your expression is valid when you change items such as condition order, logical operators, and brackets. The expression pattern is validated for items such as missing brackets, but not the validity of the expression itself.
Preview Shows the expression in preview mode

When you click Sort on the Configure User Filters page, the Available Sort Mappings section opens. Select a field to sort on, then whether it must be sorted ascending or descending.

Feature Description
Add Adds a new line for you to sort
Remove Removes a sort line
Remove All Removes all sort lines
Move Up Moves a sorting column one position up
Move Down Moves a sorting column one position down
Ascending/Descending Enables sorting a column in a ascending or descending order

Symptom: When you try to access the Custom Controls node in Management, the "You do not have access to this page. To gain access, please contact your administrator." error message occurs.

Explanation/Solution: To create a custom control, you must be part of the Control Administrators role and refresh Management to see the Custom Controls node.