Advanced Customization > Using Reusable Components > Available Reusable Components > Action Bar
  
Action Bar
Definition and Usage
The Action Bar reusable component is a widget that displays a range of actions available to the user. The actions appear as a row of buttons and in an accompanying drop-down menu. The component configuration and the size of the user’s screen determine the number of actions that appear as buttons. Any actions that do not appear as buttons are visible in the drop-down menu. You can configure the Action Bar reusable component in the following ways:
• Define the actions that are included in the Action Bar
• Set the maximum number of actions to show as buttons
• Set visibility options for the actions depending on their availability
• Define the order of the actions
• Define whether inputs are required for an action
• Select the desired style for the Action Bar
Actions are designed to activate either a service or a popup. The service or the popup mashup must be configured separately in ThingWorx. Any additional features, such as toast messages, must be configured in the appropriate service or mashup in ThingWorx.
An Action Bar is included inside the Item List and Item Identity reusable components.
The following is a sample image showing the Action Bar reusable component:
There are no predefined configurations available for the Action Bar reusable component.
Binding Properties
There are eight properties for the Action Bar component that are available for binding:
• Disabled— Boolean that disables the widget in the mashup.
• EventTriggered— Event that is triggered when a service finishes running or a popup is displayed, if the action is configured with fireEventOnFinish as true.
• Input— JSON that is the input ID for which data needs to be fetched from the backend system. This information is provided in a CCO (Common Communication Object) format.
• PopupClosed— Event that is triggered when a popup that was opened is closed.
• ServiceActionId— String that is updated with the action ID of a service action when the action is clicked.
• ServiceActionIdChanged— Event that is triggered when the value in ServiceActionId is changed, meaning that a service invoked by the Action Bar has finished running.
• SubComponentConfiguration— JSON that can be bound to the configuration JSON if the configuration JSON changes in runtime. Use the configuration fields described in the following section if the configuration does not change in runtime.
Configuration Fields
The following tables show the JSON fields that you can use to configure this component.
Property Name
Description
Type
Default Value
Required or Optional
maxItemsToShow
The maximum number of action buttons that are shown. if there are more action buttons than the value specified, additional actions will be populated in the drop-down menu.
Integer
2
Required
modelThingName
The name of a Thing that contains a service with the following signature:
public JSONObject GetActions(@ThingworxServiceParameter(name = "ccoJson", baseType = "JSON") JSONObject ccoJson)
This service takes input in CCO format containing a single item. It then returns a JSONObject containing an array that maps the ID of an available action to its label as received from the back-end. See example in Sample JSON Configuration below.
String
"PTC.ActionBar Model.Thing"
Required
actions
Actions available in the Action Bar.See sub-property:
String
N/A
Required
id
The ID of the action, as received from the backend system. See the following table for subproperties.
String
N/A
Required
objectType
Object type for which the actions are to be fetched.
String
N/A
Required
adapter
Source configuration for the backend system. See subproperties:
String
N/A
Required
instanceName
Connector instance, meaning which connector to use to connect to the backend system.
String
"windchill"
Required
thingName
Name of the backend system or adapter from which data is retrieved.
String
"PTC.WCAdapter"
Required
Configuration Fields under id
Property Name
Description
Type
Default Value
Required or Optional
overrideLabel
The value set here is shown as the action button’s label, overriding the value that comes from the backend system. To localize, put double brackets around the value.
String
N/A
Optional
actionButtonVisibility
Determines under what conditions the action buttons are shown, and in what state. Options: AlwaysShown, DisableUnavailable, HideUnavailable. For AlwaysShown, button is always visible and enabled. For DisableUnavailable, button is always visible, but disabled when action is unavailable for given selection. For HideUnavailable, button is only visible when action is available for the given selection.
Note: There are other configurations that affect whether a button is be enabled or disabled.
String
N/A
Required
buttonStyle
Determines the visual style of the button. Options: primary, secondary, tertiary, danger, transparent.
String
N/A
Required
overrideSetDisabled
If this field is set, then its value is the only factor in determining if a button should be enabled or disabled. Options: true, false. True ensures that the button is disabled, and false ensures that the button is enabled.
Boolean
N/A
Optional
activityType
Determines the if this action runs a service or displays a popup mashup. Options: popup, service. See the tables below for the required subproperties for popup and for service.
String
N/A
Required
fireEventOnFinish
If this field is set to true, when a service finishes running, the event EventTriggered is triggered, and when a popup is closed, the event PopupClosed is triggered.
Boolean
N/A
Optional
inputConstraints
Determines the input constraint for the action. Options: InputRequired, SingleInputOnly, and NoInputRequired.
InputRequired: This action must receive input to operate. If the input is empty and doesn't contain any items, this action's button is disabled.
SingleInputOnly: This action must receive a single input in order to operate. If the input is empty or contains more than a single item, this action's button is disabled.
NoInputRequired: This action can operate without any input, or with input.
String
N/A
Optional
ordinal
The order in which action buttons appear. The action with the lowest ordinal is shown in the initial leftmost position. Negative values are allowed.
Integer
N/A
Required
iconWhenEnabled
If this field is specified, the action's button contains an icon to the left of the label when the action button is enabled.
String
N/A
Optional
entityName
The name of the Media Entity to use as an icon.
String
N/A
Optional
iconWhenDisabled
If this field is specified, the action's button contains an icon to the left of the label when the action button is disabled.
String
N/A
Optional
entityName
The name of the Media Entity to use as an icon.
String
N/A
Optional
Subproperties for activityType of popup
Property Name
Description
Type
Default Value
Required or Optional
mashupName
The name of the mashup that appears as a popup.
String
N/A
Required
redirectAfterPopupSuccess
Redirects to another mashup when the popup is closed after a successful operation.
To inform the Action Bar whether the operation performed by the popup was completes or does not complete successfully, you need to set the session parameter named PTC.ActionBar.popupCloseParameters to indicate success or failure. For example, in the popup mashup there can be an expression that is executed after the operation performed by the popup finishes, and in that expression the session parameter is set. In the following example, the JSON attribute operationSuccessful is set to true since the operation was successful:
sessionStorage.setItem("PTC.ActionBar.popupCloseParameters", JSON.stringify( { operationSuccessful: true } ));
String
N/A
Optional
popupWidth
Specifies the width of the popup that appears. If this field is left blank, the popup will have the default width of 1024.
Integer
N/A
Optional
popupHeight
Specifies the width of the popup that appears. If this field is left blank, the popup will have the default width of 640.
Integer
N/A
Optional
Subproperties for activityType of service
Property Name
Description
Type
Default Value
Required or Optional
thingWithService
The name of the Thing that contains the service to run.
String
N/A
Required
serviceName
The name of the service to run.
String
N/A
Required
parameters
This optional field allows us to pass hard-coded parameters to the service. The parameters are defined in a JSONObject but must be formatted as a string of a JSON object, with escaped-quotations. Parameters should be input into the configuration file in the form "{\"myParamName\": \"hardcodedValue\"}" . See additional information below.
StringRepresentationOfJSONObject
N/A
Optional
Using parameters to Configure a Service Action
Assume there is a service named MyService with this signature:
@ThingworxServiceDefinition(name = "MyService", category = "MyCategory")

public void MyService(
@ThingworxServiceParameter(name = "exampleInt", baseType = "INTEGER") Integer exampleInt,
@ThingworxServiceParameter(name = "ExampleString", baseType = "STRING") String exampleString,
@ThingworxServiceParameter(name = "ExampleBoolean", baseType = "BOOLEAN") Boolean exampleBoolean)
This is what the parameter values look like for MyService:
{
\"exampleInt\": 123,
\"exampleString\": \"Hello\",
\"exampleBoolean\": true
}
* 
There are two parameters that your service gets automatically, if you define the service signature to receive them: serviceParam_InputCco and serviceParam_ActionId. The parameter serviceParam_InputCco is a JSONObject, and is the input that was provided to the Action Bar. The parameter serviceParam_ActionId is a string that contains the ID of the action that was clicked. If your service doesn't include these parameters in its signature, you cannot use them. If you would like to use them, define your service signature to use either or both of them, using the following:
@ThingworxServiceDefinition(name = "MyService", category = "MyCategory")

public void MyService(
@ThingworxServiceParameter(name = "serviceParam_InputCco", baseType = "JSON")
JSONObject serviceParam_InputCco,
@ThingworxServiceParameter(name = "serviceParam_ActionId", baseType = "STRING")
String serviceParam_ActionId)
Sample Configuration
{
"maxItemsToShow": {
"value": 3
},
"modelThingName": {
"entityName": "PTC.ActionBarModel.Thing"
},
"actions": {
"selectedValues": {
"data": [{
"itemListsData": [{
"items": [{
"id": "Approve",
"additionalData": {
"actionConfiguration": {
"overrideLabel": {
"value": ""
},
"actionButtonVisibility": {
"selectedKey": "HideUnavailable"
},
"buttonStyle": {
"selectedKey": "primary"
},
"activityType": {
"selectedKey": "popup"
},
"mashupName": {
"mashupName": "PTC.AccessApp.WindchillServices.RoutingOptionMashup"
},
"fireEventOnFinish": {
"value": false
},
"inputConstraints": {
"selectedKey": "SingleInputOnly"
}
}
},
"ordinal": 1
}, {
"id": "Reject",
"additionalData": {
"actionConfiguration": {
"overrideLabel": {
"value": ""
},
"actionButtonVisibility": {
"selectedKey": "HideUnavailable"
},
"buttonStyle": {
"selectedKey": "primary"
},
"activityType": {
"selectedKey": "popup"
},
"mashupName": {
"mashupName": "PTC.AccessApp.WindchillServices.RoutingOptionMashup"
},
"fireEventOnFinish": {
"value": false
},
"inputConstraints": {
"selectedKey": "SingleInputOnly"
}
}
},
"ordinal": 2
}, {
"id": "Analyze",
"additionalData": {
"actionConfiguration": {
"overrideLabel": {
"value": ""
},
"actionButtonVisibility": {
"selectedKey": "HideUnavailable"
},
"buttonStyle": {
"selectedKey": "primary"
},
"activityType": {
"selectedKey": "popup"
},
"mashupName": {
"mashupName": "PTC.AccessApp.WindchillServices.RoutingOptionMashup"
},
"fireEventOnFinish": {
"value": false
},
"inputConstraints": {
"selectedKey": "SingleInputOnly"
}
}
},
"ordinal": 3
}, {
"id": "Reassign",
"additionalData": {
"actionConfiguration": {
"overrideLabel": {
"value": "Reassign"
},
"actionButtonVisibility": {
"selectedKey": "AlwaysShown"
},
"buttonStyle": {
"selectedKey": "primary"
},
"activityType": {
"selectedKey": "popup"
},
"mashupName": {
"mashupName": "PTC.AccessApp.WindchillServices.ReassignActionMashup"
},
"fireEventOnFinish": {
"value": false
},
"inputConstraints": {
"selectedKey": "InputRequired"
}
}
},
"ordinal": 4
}
],
"objectType": "WT.WorkItem.Actions"
}
],
"adapter": {
"instanceName": "windchill",
"thingName": "PTC.WCAdapter"
}
}
]
}
}