Overview
This document outlines the steps in Drive Axle needed to link to a Custom Screen within an application. This document highlights some known issues with token replacement in Custom Screens, including using underscores for token replacement, and what is required for token replacement to function when the screen is set up to be launched from a Menu item or launched by an Action.
How to Create and Link to Custom Screens
Create A Custom Screen
First log into Drive Axle and navigate to the App Manager, by pulling down the “Document Hub” tab, or by going directly to https://dashboard.driveaxleapp.com/.
To start creating a custom screen, navigate to the “Custom Screens” page found in the “App Configuration” tab, or go directly to https://dashboard.driveaxleapp.com/#screens.
Click the “Add a screen” button as shown below being pointed to by the red arrow. Next, choose a screen code (in all capital letters, conventionally) and enter it into the “Code” box highlighted in a red box below. Similarly, choose a descriptive title for this new screen and enter it into the “Title” box highlighted in a green box below. From here, build the screen by adding actions using the “Add an action” button as shown below being pointed to by the blue arrow, and adjusting the type and the fields of those actions by manipulating the items highlighted in a blue box below. Click the blue “Save” button in the upper right-hand corner to finish building the new screen and it will be added to the list of Custom Screens.
Note 1: The screen code and the screen title do not have to match, but for clarity that is often preferred.
Note 2: There are several types of actions including but not necessarily limited to:
- Document Scan
- Launch App
- Logout
- New Message
- Screen
- Telephone
- Text
- Web Browser
Prefilled Values
If a Custom Screen has an Action Type that is Document Scan or New Message, there can be a form associated with that Action. Like Actions, the Custom Screen Action can have pre-filled field values configured to pre-populate values on the form fields that exist within the associated form:
If token replacement is being used to pre-fill a value on the form launched by the custom screen, the token replaced value will need to be specified on the Action or the Menu item that is launching the Custom Screen. The following sections go through setting up a Custom Screen with token replaced values, using the example of a Custom Screen that is launched by a Menu Item and one that is launched by an Action. Our Drive Axle - Emailing Form Data Through Drive Axle document has more information on how token replacement works in a form and the different replacement locations that can be used.
There is also a known issue with Eleos where token replaced values that have underscores fail when being used on custom screens. To correct this, the underscore needs to be removed from the field withing the database and within the token used for the Pre-filled Field Values on the custom screen for the form to function as expected. For example, the "{{user.custom.mgr_email}}" token would need to be changed to "{{user.custom.mgrEmail}}" and "mgr_email" would need to be changed to "mgrEmail" in the ELEOS.udf_UserCustom function (Note this may be ELEOS.usp_UserCustom for some clients).
Create an Action that Links to a Custom Screen
Now that the new custom screen exists, the next step is to create an action (a button in the application) that when used it will navigate the application to the custom screen.
First, navigate to the “Actions” page under the “App Configuration” tab, or go directly to https://dashboard.driveaxleapp.com/#actions.
Next, Click the “Add an action” button shown below being pointed to by the red arrow. Choose a code (in all caps by convention) and enter it into the “Code” box highlighted in a red box below. Similarly, choose a title for the action button and enter it in the “Title” box highlighted in a green box below.
Select “Screen” from the dropdown “Type” list shown below being pointed to by a blue arrow. Now choose and add a label in the Label field, an optional icon to appear to the left of that label, and the color that the button should be on the application, all of which can be found in the section highlighted in a blue box below.
Finally, select the screen you’d like the button to link to from the “Screen” drop down list shown below being pointed to by an orange arrow. Finish by clicking the blue “Save” button.
Token Replacement On Actions
When launching a Custom Screen from an Action, the Action that launches the screen needs to do the token replacement on the form field code names that need the custom values (such as "{{user.custom.mgrEmail}}") and the Custom Screen needs to use a similar double token replacement characters for signifying the form field code that will be replaced. The example below shows how this would be configured on the Custom Screen:
The screenshot below shows how the Action that launches the Custom Screen is configured to handle the token replacement for the EMAILTO field:
Once changes are made, be sure to save them by clicking the Save button. The following section shows an example of adding the Action to the Dashboard and how it would appear within the application.
Add the Action to a Dashboard
Next, under the “App Configuration” Tab, click on the “Dashboards” button to navigate to the list of available dashboards.
Here you will begin by clicking on the dashboard that contains the card that you wish to change or add a new card for the Action.
In the fields to the right of the card list, locate the list of actions towards the bottom. In that “Actions” list, locate the action that was created earlier that links to the new custom screen. In the screenshot below, the “SCAN-DOCUMENTS” action highlighted in blue is the one that links to the custom screen, but the name should match the title chosen for the action in the “Create an Action That Links to a Custom Screen” step. After the card and Action are added, ensure to save changes by clicking the Save button, so that the action will be visible within the application.
Below is an example of a new card that is added to the Dashboard with the Action that was created to link to a Custom Screen.
Note: The list of actions has somewhat unintuitive behavior. Any action clicked on will be highlighted to show that it is selected, and the selected actions will appear in that card in the application. Hold the Ctrl key and click on a selected action to de-select it and remove it from that card.
At this point, the action has been added to the Dashboard and should be visible the next time the application is refreshed. In the screenshot below, it shows the new card that was added to the Dashboard.
The Custom Screen appears when the new Action button is pressed.
Create a Menu Item that Links to a Custom Screen
As an alternative to an Action launching a Custom Screen, a menu item could also be used to launch a Custom Screen. Our Drive Axle – Managing Your App Document has a section on what Menus are and how to set them up.
1. Navigate to Menus withing Drive Axle:
2. Select the appropriate Menu from the list of Menus.
3. Add a new Menu item is added using the “Add a menu item” button.
4. Select “Screen” for the Type, and then select the Custom Screen that was created from the list of Screens. The screen code and title will show within the drop-down list.
5. Add a Label for the Menu item. This is what drivers will see on the Menu in the application, so drivers will be able to click the name to bring up the Custom Screen within the application. An icon can also be configured for the Menu Item to make it more identifiable.
6. Save changes made by clicking the blue Save button.
Token Replacement on Menu Items
Like token replacement on Actions, when launching a Custom Screen from an Menu, the Menu that launches the screen needs to do the token replacement on the form field code names that need the custom values (such as "{{user.custom.mgrEmail}}") and the Custom Screen needs to use a similar double token replacement characters for signifying the form field code that will be replaced. Within the Pre-filled Field Values on the Custom screen the user custom token (such as "{{user.custom.mgrEmail}}") can be used for the EMAILTO field:
The screenshot below shows how the Menu Item that launches the Custom Screen is configured to handle the token replacement for the EMAILTO field:
OR the form field token {{EMAILTO}} can be used within the Custom Screen Pre-filled Field Values to replace the value in the EMAILTO field:
When configuring the Menu Item the Pre-filled Data needs to get the token for the custom value that needs to replace the form field. In the below example it shows the {{user.custom.mgrEmail}} token is used within the Menu if {{EMAILTO}} was used as the Pre-filled Field Value in the Custom Screen. The screenshot below is of the Menu item configuration:
OR, if the {{user.custom.mgrEmail}} token was used in the Custom Screen, then the Menu item configuration would still have the {{user.custom.mgrEmail}} used within the Pre-filled Data for user.custom.mgrEmail:
After making changes to a Menu item, hit the blue Save button to save changes to the application. Below is an example of how to get to the screen within the Menu of the application:
 |  |