Adding New Functionality with Dino Script XCommand™
Updated
by Dale Mandeville
Topics In this Article
- Introduction to XCommand
- Command Attribute Reference
- Parameter Attribute Reference
- Using Functions in Attributes
Introduction to Dino Script® XCommand™
XCommand™ is a mini-programming language that is used to define actions and events that are specific to your company's needs in Wheelhouse™. They may be functions that run when an a new order is created (an event) or they may be actions that are user initiated from a custom menu item.
This article provides an introduction to XCommand as well as the full list of command attributes and parameter attributes that are available.
Prerequisites: Creating new XCommand functions requires developer permissions. Contact your administrator.
Walkthrough: Creating an Action Menu item with XCommand
- Navigate to System > Scripts and Logging > Business Rule
- Create a new Business Rule by clicking on the new button.
- Give your Dino Script a Name. HINT: For this example, use "XCommand Test".
- Decide what menu you want the action to appear in and select the appropriate Type Key. For example, if you want the menu item to appear in the context of employees, then select the Type Key "Employee" from the list.
- Click Save. You will now be looking at a blank Code Editor screen.
- The simplest example of an Dino Script is one that only adds a menu item. Add this code to the editor.
def sayHello() {
$$
<command>
</command>
$$
return "Hello World!";
} - Click Save & Reload
- Look for the new menu item in the Action (Lightening Bolt) menu. Try running the command!
- It worked! Now, let's ask the user for a little more information, their name and age, and do something with it. We need to add parameters to the function definition.
def sayHello(name, age) {
$$
<command>
</command>
$$
var message = "Hello " + name +"! Age:" + age;
return message;
} - Save. Then run the 'Say Hello...' action again. This time, you should see input boxes for name and age.
- Note that both name and age are treated as text strings so we are able to enter 'abcd' in the age box... not good! We haven't told the system that age should be a number. We need to expand the XCommand section by adding some parameter attributes.
Try this:def sayHello(name, age) {
$$
<command label="Say Hi To Me"
help="Please tell us more about yourself!">
<param name="name"
label="First Name"
help="Enter your first name."/>
<param name="age"
type="num"
help="Enter your age."/>
</command>
$$
var message = "Hello " + name +"! Age:" + age;
return message;
} - We made several display and behavior changes with a small amount of script. In order of appearance in the script, here are the changes we made:
- Renamed the Action menu item to "Say Hi To Me"
- Added help text to the command input dialog box "Please tell us more about yourself!"
- Changed the label above the input box for name to "First Name"
- Added help text below the name input box
- Added type="num" to the age input parameter
- Added help text below the age input box
- You completed the walkthrough!
Here are some additional things to try: Reference the list of command attributes and parameter attributes that appear later in this article. Test out the different parameter types and command options. Try adding a parameter such as birthDate with type="Date".
Walkthrough: Capturing an Event with XCommand
We'll write this section soon. If you need help, please contact us!
Command Attributes:
Attribute (case sensitive) | Value (case insensitive) | Description and Usage | Example | Included in |
acl | Comma-Separated String or Function | Access Control List, limit who can see this command Future Release: This will be a synonym of role. | acl="AdminOnly" | released |
activeFrom | Date Or Function | Makes function available starting on a certain date. | activeFrom="2020-12-31" | released |
activeThru | Date Or Function | Makes function unavailable starting on a certain date. | activeThru="2020-12-31" | released |
autoRun | true | false | If the function has no parameters, it will, by default, run without showing a dialog since autoRun defaults to true. To prevent the function from running without a prompt, set autoRun to false. | autoRun="false" (default is true) | released |
cancelBtn | text or function | Use to specfiy the text for the cancel button. If empty, only the icon will be displayed | cancelBtn="Exit" | released |
cancelBtnIcon | text or function | Use to specify the icon for the cancel button. If empty, only the text will be displayed | cancelBtnIcon="fa-ban" | released |
columns | int, number of columns (1, 2, 3, 4, 6) | Smart Default | columns="1" | released |
context | Single | List | None, custom string | Define where the command will be available | context="List, Single" | released |
closeBtn | text or function | Use to specify the text for the close button. If empty only the icon will be displayed | closeBtn="Done" | released |
closeBtnIcon | text or function | Use to specify the icon for the close button. If empty only the text will be displayed | closeBtnIcon="fa-times" | released |
cmdBtns | RunOnly | RunCancel | RunRepeatCancel | CancelOnly | Buttons to show in command window | cmdBtns="RunCancel" | depreciated. Default is now RunCancel. Define repeatBtn to display repeat option. |
description | String or Function | synonym of help, appears at top of window | description= "Provide some additional information about this command." | released |
formTop | String or Function | Text or Beads object to be shown above the commands input parameters and below the help text | formTop="Above the Form" | released |
formBottom | String or Function | Text or Beads object to be shown below the commands input parameters | formBottom="Below the Form" | released |
help | String or Function | synonym of description, appears at top of window | help="Provide some additional information about this command." | released |
helpIcon | String or Function | define icon to show with the help text | helpIcon="fa-info" | released |
hidden | true | false or Function | Defaults to false if not specified. Used to hide commands from the action menu when they aren't designed to be called directly, for example, in multi-command wizards. | hidden="true" or hidden="isHidden()" | released |
icon | String | define icon to show for command in menu | icon="fa-green-circle" | released |
isLink | true | false | links are opened in a browser immediately | isLink="true" | released |
label | String or Function | label to use in menu | label="Menu Item Name" | released |
name | automatically set to function name | duplicate definition will be ignored | name is assigned based on function name and does not need to be defined as a command attribute. | released |
nextCmd | String or Function | Function may be used to get name of nextCmd | on roadmap Currently not active but host.nextCommand (host, 'functionName') will accomplish the same thing. | |
refresh | true | false | Refresh the screen after command is complete | released | |
refreshBtn | String or Function | Use to specify the text for the "Run Again" button. If empty only the icon will be displayed | refreshBtn="Back" | released |
refreshBtnIcon | String or Function | Use to specify the icon for the "Run Again" button. If empty only the text will be displayed | refreshBtn="fa-redo" | released |
repeatBtn | String or Function | Use to specify the text for the "Run Again no Prompt" button. If empty only the icon will be displayed | repeatBtn="Refresh" | released |
repeatBtnIcon | String or Function | Use to specify the icon for the "Run Again no Prompt" button. If empty only the text will be displayed | repeatBtnIcon="fa-repeat" | released |
resultBtns | CloseOnly | RepeatClose | RepeatRefreshClose | RefreshClose | Buttons to show in results window | released | |
resultColumns | int, number of columns (1, 2, 3, 4, 6) | Smart Default | columns="1" | released |
role | Comma-Separated String or Function | synonym of acl. Access Control List, limit who can see this command | role="hr,sales" | on roadmap |
runBtn | text or function | Used similarly to "Run". Use to specify the text for the run button. | runBtn="Do It!" | released |
runBtnIcon | text or function | Use to specify the icon for the "Run" button. If empty only the text will be displayed | runBtnIcon="fa-running" | released |
target | Dialog | Modal | Blank | type of window to use for command | on roadmap |
Parameter Attributes
Attribute (case sensitive) | Value (case insensitive) | Description and Usage | Example | Included Rev 0 |
colSpan | Full | int | Number of columns that the rendered control for the parameter should span. | colspan="2" | on roadmap |
control | Function only | Allows for modification or creation of the control during runtime. | on roadmap | |
description | String or Function | Synonym of help; displays below input box | description= "Enter your value in the box above." description="getParamDesc()" | released |
exclude | true | false of Function | Setting to 'true' hides the parameter from display in the command dialog. | exclude="true" exclude="excludeParam()" | released |
help | String or Function | Synonym of description; displayed below the input box | help= "Enter your value in the box above." help="getParamHelp()" | released |
inputRows | Text | LongText | Memo | integer | Synonym of textLength | inputRows="Memo" or inputRows="5" | on roadmap |
label | String or Function | Shown above the the input box | label="Label Above Input Box" help="getParamLabel()" | released |
name | String | Name of the param as defined in the function definition | name="ParamName" | released |
placeholder | String | Text Field Behavior: the placeholder is displayed in light text in the textbox as an example of the data expected Bool Field Behavior: the placeholder is displayed next to the checkbox for the boolean as alternative text to the textbox name | placeholder="First Name" | released |
required | true | false | Required params are starred (*), and an error is returned if the required param is not entered | required="true" | released |
selections | Comma-Separated String or Function | Provides selection list. If selections are set then selectType will default to "Select" | selections= "First Option, Second Option, Third Option" OR selections= "getMyList()" | released |
selectType | Select | Browse | MultiSelect | MultiBrowse | Use an alternative select list type. Browse only works for type="File" | selectType ="MultiSelect" | released On RoadMap: ComboBox |
textLength | Text | LongText | Memo | Specifies the type of text box for an input box. | textLengh="LongText" | released |
type | String | Int | Num | Decimal | Bool | Text | LongText | Memo | Date | DateTime | Time | File | Signature, custom type Do not use types Float or Single. Use Decimal instead. | Defines the parameter type. The type may also be defined in the function definition. For example: | type="Bool" | released |
typeFilter | Search string for custom type | Use to limit selection lists within certain types such as "Customer" | depreciated | depreciated |
validation | Function | Checks value at runtime using a function. | on roadmap | |
value | Any Text or Function | Define default value of the parmeter. May also be defined in the function definition. For example: | value="Initial Value" value="getParamValue()" | released |
Using Functions in Attributes
Some attributes allow functions. The function name is passed inside the attribute as a string.
For example, a value can be retrieved from a function to set the initial input box value with: value="getDateFrom()"
For a dropdown list of customers, we might use a function called getCustomers() to populate the list. When XCommand sees a list, it will automatically set the parameter's attribute to selectType="Select" unless you specifically set it to selectType="MultiSelect". Below is an example of a getCustomers() function that could be called to populate a customer list.
private def getCustomers(){
var custRepo = Customer.GetRepository();
return custRepo.OrderBy(c => c.Name).ToList();
}Example showing more attributes and use of functions
This example is not set up for direct copying to your system. It is intended for formatting reference only. It requires several supporting function definitions which are not included here.
def WorkOrdersReport(From, Thru, Customers, Items, Completion, OutputTo) {
$$
<command
cmdBtns="RunCancel"
context="List"
label="Work Orders Report">
<param
name="From"
label="Start Date"
type="Date"
value="getDateFrom()" />
<param
name="Thru"
type="Date"
label="End Date"
value="getDateThru()" />
<param
name="Customers"
type="String"
value="getCustSelections()"
selections="getCustomers()"
selectType="MultiSelect"
help="Leave blank to select all customers." />
<param
name="Items"
type="String"
value="getItemSelections()"
selections="getItems()"
selectType="MultiSelect"
help="Leave blank to select all items." />
<param
name="Completion"
type="String"
value="getCompletion()"
selections="All,Complete,Incomplete" />
<param
name="OutputTo"
type="String"
value="getOutput()"
selections="Download,Screen"
help="Choose how to output results." />
</command>
$$
// write Dino Script here to do something with the information collected.
var message = "Test Message";
return message;
}
