Home | Action Functions | Listener Functions | UI Components
This library provides a number of custom elements with their own unique tags and attributes. Each element connects to ROS, either to provide a graphical interface for requesting an action on the connected robot, or to continuously display the latest data from a topic published by said robot.
Note: Action components should each be assigned a unique ID using their HTML tag's data-id
attribute. On top of allowing individual CSS styling of these components, these IDs are used by this library to track the state of components, such as if each component is enabled or disabled.
-
Description: A red button with the text 'cancel action' which is automatically added to the bottom-left corner of the page. When the button is clicked the most recently started action is cancelled.
-
Example:
Note: Should you want to hide or modify the cancel button, you can access it via the global JS variable stopButton
. To hide it for example you can use the following JS code:
stopButton.hidden = true;
If you then wish to place your own custom cancel button somewhere other than the default location in which this library automatically places it, you can insert it using either HTML or JavaScript.
HTML example:
<div class="cancel-button rwc-button-action-start"
style="z-index: 9999;" onmousedown="cancelCurrentAction();">
<span>Cancel action</span>
</div>
JavaScript example:
var myCancelButton = document.createElement("div");
myCancelButton.setAttribute("class", "cancel-button rwc-button-action-start");
myCancelButton.setAttribute("style", "z-index: 9999;");
myCancelButtonSpan = document.createElement("span");
myCancelButtonSpan.innerHTML = "Cancel action";
myCancelButton.appendChild(myCancelButtonSpan);
if(isPhone){
myCancelButton.addEventListener('touchstart', function(event){
cancelCurrentAction();
});
} else {
myCancelButton.addEventListener('click', e => {
cancelCurrentAction();
});
}
document.body.appendChild(myCancelButton);
- Description: A button which calls an action function when clicked.
-
Example:
<rwc-button-action-start data-id="speakActionStart" data-text="Say hello!" data-action="say" data-action-parameters="Hello everyone!"> </rwc-button-action-start>
A button with the text 'Say hello!', which calls the
rwcActionSay
action function with the parameter "Hello everyone!", resulting in the robot speaking the phrase when the button is clicked. -
Attributes:
- data-id
- Description: Specifies an ID to be assigned to the button's child
div
for CSS styling - Example:
data-id="myActionButton"
- Description: Specifies an ID to be assigned to the button's child
- data-class
- Description: Specifies a custom class to be assigned to the button's child
div
for CSS styling, overriding the default styling instyles/rwc-styles.css
. Custom CSS should be defined instyles/rwc-user-styles.css
. - Example:
data-class="customButtonClass"
- Description: Specifies a custom class to be assigned to the button's child
- data-disabled-class
- Description: Specifies a custom class to be assigned to the button's child
div
when the button is disabled, for CSS styling, overriding the default styling instyles/rwc-styles.css
. Custom CSS should be defined instyles/rwc-user-styles.css
. - Example:
data-disabled-class="customDisabledButtonClass"
- Description: Specifies a custom class to be assigned to the button's child
- data-disabled
- Description: Set this to
true
to have the button load in a disabled state. Otherwise the button is enabled when loaded, by default. - Example:
data-disabled="true"
- Description: Set this to
- data-action
- Description: The name of the action function to be called when the button is clicked. The name should be specified in camelCase without the
rwcAction
prefix, as in the example. - Example:
data-action="setPoseRelative"
- Description: The name of the action function to be called when the button is clicked. The name should be specified in camelCase without the
- data-action-parameters
- Description: The parameter(s) of the action function specified by the
data-action
attribute. Though tag attributes areString
data, numerical data, and comma seperated parameters are handled by the API before calling the action function. It should be noted that at this time the optional quaternion in the parameters of thesetPose...
action functions cannot be defined in this attribute. - Example:
data-action-parameters="WayPoint20"
- Example:
data-action-parameters="1, 0, 0"
- Example:
data-action-parameters="-100"
- Example:
data-action-parameters="Hello world!"
- Description: The parameter(s) of the action function specified by the
- data-text
- Description: Defines the text which is displayed inside the button.
- Example:
data-text="Click me!"
- data-id
-
- Description: Bold and underlined text which calls an action function when clicked.
-
Example:
<rwc-text-custom-action-start data-id="moveActionStart" data-text="Forward 0.5m!" data-action="setPoseRelative" data-action-parameters="0.5, 0, 0"> </rwc-text-custom-action-start>
Bold and underlined text that reads: 'Forward 0.5 meters!', which calls the
rwcActionSetPoseRelative
action function with the parameters x: 0.5, y: 0, z: 0, resulting in the robot moving forward half a meter when the text is clicked. -
Attributes:
- data-id
- Description: Specifies an ID to be assigned to the tag's child
div
for CSS styling - Example:
data-id="myActionText"
- Description: Specifies an ID to be assigned to the tag's child
- data-class
- Description: Specifies a custom class to be assigned to the tag's child
div
for CSS styling, overriding the default styling instyles/rwc-styles.css
. Custom CSS should be defined instyles/rwc-user-styles.css
. - Example:
data-class="customTextClass"
- Description: Specifies a custom class to be assigned to the tag's child
- data-disabled-class
- Description: Specifies a custom class to be assigned to the tag's child
div
when the button is disabled, for CSS styling, overriding the default styling instyles/rwc-styles.css
. Custom CSS should be defined instyles/rwc-user-styles.css
. - Example:
data-disabled-class="customDisabledButtonClass"
- Description: Specifies a custom class to be assigned to the tag's child
- data-disabled
- Description: Set this to
true
to have the tag load in a disabled state. Otherwise the interaction is enabled when loaded, by default. - Example:
data-disabled="true"
- Description: Set this to
- data-action
- Description: The name of the action function to be called when the text is clicked. The name should be specified in camelCase without the
rwcAction
prefix, as in the example. - Example:
data-action="setPoseRelative"
- Description: The name of the action function to be called when the text is clicked. The name should be specified in camelCase without the
- data-action-parameters
- Description: The parameter(s) of the action function specified by the
data-action
attribute. Though tag attributes areString
data, numerical data, and comma seperated parameters are handled by the API before calling the action function. It should be noted that at this time the optional quaternion in the parameters of thesetPose...
action functions cannot be defined in this attribute. - Example:
data-action-parameters="WayPoint20"
- Example:
data-action-parameters="1, 0, 0"
- Example:
data-action-parameters="-100"
- Example:
data-action-parameters="Hello world!"
- Description: The parameter(s) of the action function specified by the
- data-text
- Description: Defines the text which is displayed inside the tag.
- Example:
data-text="Click me!"
- data-id
-
- Description: An image which calls an action function when clicked.
-
Example:
<rwc-img-action-start src="images/lcas-logo.png" data-action="say" data-action-parameters="You have clicked the L-CAS logo!"></rwc-img-custom-action-start>
An image which calls the
rwcActionSay
action function with the parameter "You have clicked the L-CAS logo!", resulting in the robot speaking the phrase when the image is clicked. -
Attributes:
- src
- Description: Specifies the path of the image to be displayed.
- Example:
src="images/lcas-logo.png"
- data-id
- Description: Specifies an ID to be assigned to the tag for CSS styling.
- Example:
data-id="myActionImage"
- data-class
- Description: Specifies a custom class to be assigned to the tag for CSS styling, overriding the default styling in
styles/rwc-styles.css
. Custom CSS should be defined instyles/rwc-user-styles.css
. - Example:
data-class="customImageClass"
- Description: Specifies a custom class to be assigned to the tag for CSS styling, overriding the default styling in
- data-disabled-class
- Description: Specifies a custom class to be assigned to the tag when interaction is disabled, for CSS styling, overriding the default styling in
styles/rwc-styles.css
. Custom CSS should be defined instyles/rwc-user-styles.css
. - Example:
data-disabled-class="customDisabledImageClass"
- Description: Specifies a custom class to be assigned to the tag when interaction is disabled, for CSS styling, overriding the default styling in
- data-disabled
- Description: Set this to
true
to have the image load in a disabled state. Otherwise the interaction is enabled when loaded, by default. - Example:
data-disabled="true"
- Description: Set this to
- data-action
- Description: The name of the action function to be called when the image is clicked. The name should be specified in camelCase without the
rwcAction
prefix, as in the example. - Example:
data-action="setPoseRelative"
- Description: The name of the action function to be called when the image is clicked. The name should be specified in camelCase without the
- data-action-parameters
- Description: The parameter(s) of the action function specified by the
data-action
attribute. Though tag attributes areString
data, numerical data, and comma seperated parameters are handled by the API before calling the action function. It should be noted that at this time the optional quaternion in the parameters of thesetPose...
action functions cannot be defined in this attribute. - Example:
data-action-parameters="WayPoint20"
- Example:
data-action-parameters="1, 0, 0"
- Example:
data-action-parameters="-100"
- Example:
data-action-parameters="Hello world!"
- Description: The parameter(s) of the action function specified by the
- src
-
- To create an action component, e.g. a button, which sends a user-specified goal with a user-specified message to a user-specified action server when clicked, you must first define your own name for this custom action, as well as the name of the action server and action in rwc-config.json.
Example JSON in rwc-config.json, inside
actions.actionServers
:"move_base_custom_example": { "actionServerName": "/move_base", "actionName": "move_base_msgs/MoveBaseAction" }
- Next you must define a goal message to send to your custom action server, in JSON format, and save this in a
.json
file somewhere within your website. Here's an example, forward-half-m.json, amove_base_msgs/MoveBaseActionGoal
which moves the robot 0.5m forward from its current position:{ "target_pose":{ "header":{ "frame_id":"base_link" }, "pose":{ "position":{ "x":0.5, "y":0, "z":0 }, "orientation":{ "x":0, "y":0, "z":0, "w":1 } } } }
- Lastly, in the HTML tag of the action component which you want to use to send your custom action goal to your custom action server, you must define the following additional attributes:
data-action
- Description: The name which you have given to your custom action server in rwc-config.json.
- Example:
data-action="move_base_custom_example"
data-goal-msg-path
- Description: The path to the JSON file which defines the message of the goal to be sent to the action server when the action component is pressed / clicked.
- Example:
data-goal-msg-path="json-msgs/forward-half-m.json"
- Here's an example of a full HTML tag for a button which sends a custom action goal when clicked, moving the robot forward 0.5m:
<rwc-button-action-start data-id="moveActionStartCustom" data-text="Forward 0.5m!" data-action="move_base_custom_example" data-goal-msg-path="json-msgs/forward-half-m.json"> </rwc-button-action-start>
Load page components are identical to action components, except that when clicked, they load a given HTML page, as opposed to sending an action goal. The major differences are:
- Any attributes that begin with
data-action
will not apply. - The relative or full URL of the page you want to load when the button is pressed is defined with the
data-href
attribute.
Names of 'load page' components tags are:
rwc-button-load-page
rwc-text-load-page
rwc-img-load-page
Example HTML for a button which loads the page foo.html
when pressed:
<rwc-button-load-page
data-id="loadPageFooButton"
data-text="To foo"
data-href="foo.html">
</rwc-button-load-page>
- Description: Text which displays the data returned by a listener function, updating continuously to reflect changes in the returned data.
-
Example:
Current node: <rwc-text-listener data-listener="getNode"></rwc-text-listener>
Text that reads: 'Current node: WayPoint33', calling the
getNode
listener function and displaying the returned value as text after 'Current node: '. -
Attributes:
- data-listener
- Description: Specifies the name of the listener function to display data from. The name should be specified in camelCase without the
rwcListener
prefix, as in the example. - Example:
data-listener="getNode"
- Description: Specifies the name of the listener function to display data from. The name should be specified in camelCase without the
- data-live
- Description: If set to false then the value returned by the chosen listener function will displayed when the element is loaded, and will not be updated thereafter.
- Example:
data-live="false"
- data-listener
-
To create an rwc-text-listener
which subscibes to a custom topic for which this library does not provide a listener function, you must first define this topic in the listeners
field of rwc-config.json, specifying the topic name and topic message type, for example:
"odom_custom_example": {
"topicName": "/odom",
"topicMessageType": "nav_msgs/Odometry"
}
Then you simply have to use the name you have given this topic, e.g. odom_custom_example
as the value for the data-listener
attribute of your rwc-text-listener
's HTML tag, and define the attribute data-field-selector
: the selector for the particular part of the topic's message that you wish to display. Here's an example which displays the robot's position:
Robot position custom: <rwc-text-listener
data-listener="odom_custom_example"
data-field-selector="pose.pose.position"></rwc-text-listener>
When data-field-selector
selects a single variable within a topic's message, the variable will be displayed as expected, but it should be noted that for collections of variables, these collections will be displayed in JSON format. To illustrate this, here is what the above example displays: