A Keyboard Rule is executed when the user presses a key on their keyboard and no field is in focus. When your user presses a key on their physical keyboard, that keyboard event is sent to whatever part of your configurator is "in focus" – or selected to receive input. Usually, a field is in focus, so the keypress appears in the field. When no field is in focus, then the keypress is passed to either the entire configurator or the scene shown in the configurator viewer. Keyboard rules can capture these keypresses.
Keyboard rules are rarely used. Because it relies on a keyboard, it may prevent your configurator from being used on a mobile device, touch-screen kiosk, or other devices without physical keyboards. Keep in mind your user audience: if you anticipate users interacting without a keyboard, try using pop-up buttons or other UI components to accomplish the same tasks.
Arguments
Arguments are data passed in to the rule. You can find arguments by using the Get/Set variable Snap blocks. In this rule type, the Get block exposes these arguments:
Name |
Type |
Description |
|---|---|---|
| clientLanguage | text | the two-character code representing the current user's preferred language. |
| configurator | Configurator | the current running configurator. |
| environment | string | "dev" if you are in the development environment, "test" if you are in the test environment, and "prod" if you are in the production environment. |
| isMobile | boolean | true, if the viewport seems to have the size of a mobile device. Use this flag to show something differently on screen if required by a smaller device. |
| user | User | the current user. |
| parameters | map | a map of GET or POSTparameterspassed into the configurator when it was launched. |
| keyArgs | map | a map of parameters describing the keypress that just happened: |
| keyArgs.Key | text | a text name of the key pressed. It can be a single character, such as "X" or "y", or multiple characters such as "PageDown", "Control", or "Escape". See the example below for a handy utility that will show you the Key text for any keyboard action. |
| keyArgs.KeyCode | number | a number identifying the key pressed. Since this property returns different values for different keyboard layouts, the Key property is more reliable. |
|
keyArgs.altKey keyArgs.ctrlKey keyArgs.shiftKey |
boolean | returns true if the keystroke pressed includes the alt, control, or shift keys. This can be useful when creating special commands for your configurator. For example, if you have built an "undo" function, and want it to fire when the user presses Control-Z. See the example below. |
Example
If your configurator has multiple pages, you can use this code to move from one page to another with your keyboard.
- Note the initial writelog statement: it will add to the web browser's debug console the Key text for anything pressed on your keyboard. You can easily discover any Key text with this one line. Learn more about your web browser's debug console.
- Note how the final if block combines two properties to look for a specific keypress. This can be useful, especially in 3D scene keyboard rules, to help your user add a new mesh to the scene with a CTRL-N, or reset the position and rotation of a mesh with a CTRL-R.
Understanding keyboard rule details
Keyboard rules don't capture all keypresses. If a field has focus, then the keyboard rule will not run.
For more details, consider the following series of steps a user might take with a configurator, and learn when the a specific key press can be seen by a keyboard rule.
| Step | What object has the focus? | What happens when any keys are pressed? | Details |
|---|---|---|---|
|
The user launches the configurator. The configurator UI appears, and a 3D scene appears in the configurator viewer.
|
The configurator has focus. | Configurator keyboard rules are run. | The configurator has focus by default when it is launched. |
|
The user clicks on a field in the configurator. The field highlighting changes, showing it has the focus.
|
The selected field has focus. | No keyboard rules are run. | Keyboard rules cannot see keypresses going to a field. So this keypress will not be seen by any keyboard rule. |
| The user presses the TAB key. | The next field is selected. | No keyboard rules are run. | Since a second field now has the focus, all keypresses are passed directly into that second field. As before, keyboard rules cannot see the keypress going to a field. |
|
The user clicks on the configurator, but not on any field. For example, they click on a group name, or an empty area. No field is highlighted.
|
The configurator has focus. | Configurator keyboard rules are run. | |
|
The user clicks on the 3D scene within the configurator viewer.
|
The scene has focus. | Scene keyboard rules are run. | The scene has focus, so it runs keyboard rules stored in the scene. Keyboard rules stored in the configurator are not run. |