Working with Web App Control Projects

You can use the Web App Control Project project type to extend X4 Web Apps with custom JavaScript functions in order to access the data and actions of the web app via JavaScript API functions. You can use <CustomControls> to incorporate your own JavaScript code into a web app and call actions in order to interact with the web app. In addition, you can control the layout by setting property parameters. In order to use a custom control in a web app, you just have to reference the Web App Control Project in a Web App Project. A Web App Control Project contains the content which is displayed in the Web App.

Creating a Web App Control Project

To create a new Web App Control Project:

1. In the X4 Designer, right-click in the Projects view and choose New from the context menu. 

2. Choose Web App Control Project....

   

   Alternatively, you can click New in the File menu and choose Web App Control Project....

3. Enter a project name in the Project Creation Wizard dialog.

4. Choose Finish.
   
   

Web App Control Projects have a pre-defined and non-modifiable folder structure which is created automatically when creating a new Web App Control Project. 

Sources

Once a project has been created, this folder contains three files: index.html: This file contains a basic HTML structure which you can extend by the desired elements. x4-webapp-api.d.ts: This file contains the current API declarations (needed by TypeScript developers).  x4-webapp-api.js: This file contains the current JavaScript API. See Available API Functions for a list of the available API functions with a description. The Sources folder cannot be deleted, moved, or renamed. You can, for example, also create a .css file in the Sources folder.

<Project>.webcontrol

Project-related file which is created automatically when creating a project. The first part of the file name is the project name. If needed, you can add a definition for the cookie consent in this file. To do so, you can enter any text in the fieds or provide information for a third-party service.  Each Web App Control Project contains exactly one .webcontrol file. If you would like to reference more than one Web App Control Project in a Web App Project, you create a new .detail component in the Components folder of the Web App Project for every additional Web App Control Project.

Note:

Using the developer tools, you can display all files from a Web App Control Project in the browser without authentication.

Using Custom Controls in a Web App

Prerequisite

You have a Web App Project containing at least one technical process. For more information on creating Web App Projects, see  Creating a new Web App Project.

The following sections explain how to connect a Web App Control Project with a Web App Project in order to use one or more custom controls in the Web App. 

To embed a custom control:

1. Open the Web App Project and double-click on the <Project>.wac file. Choose SAMEORIGIN in the X-Frame-Options drop-down in the HTTP Security Header section.

2. Add the desired properties in the Dashboard.detail file in the Components folder.                          
   In this file, you insert the desired custom controls using the <CustomControl> element and reference the Web App Control Project you have created previously via the mandatory project attribute.
   
   
   

   

   You can create additional detail components in the Components folder which you use, for example, to set layout properties.

   
    In addition, you can define the following attributes for the <CustomControl> element:
   

   Attribute	Description
   horizontalAlign	Direction of the element flow. The order of the elements corresponds to their declaration. Possible values: left(default) center right
   textOverflow	Specifies which action is to be performed when the control is full. Possible values: ellipsis: Use ... to indicate that the text is continued hidden: truncate text, do not break whole words wordBreak: break within words allow (default): wrap text within words
   visible	Specifies whether the control is visible. Data binding (boolean) possible Possible values:   true/false or string for data binding
   Attributes with description for iframe settings in sandbox mode
   allowForms	Allows the page to submit forms. Possible values: true (default): Forms can be submitted. false: Forms may not be submitted.
   allowModals	Allows the page to open modal windows. Possible values: true (default): Modal windows can be opened. false: Modal windows may not be opened.
   allowPointerLock	Allows the page to use the Pointer Lock API, an API that provides input methods based on the movement of the mouse over time. Possible values: true: The Pointer Lock API is used. false (default): The Pointer Lock API is not used.
   allowPopups	Allows the page to open popups. Possible values: true: Popups can be opened. false (default): Popups may not be opened.
   allowTopNavigation	Lets the resource navigate the top-level browsing context (named _top). Possibles values: true: Navigation in the the top-level browsing context is possible. false (default): Navigation in the the top-level browsing context is not possible.

   
   Within the <CustomControl> element, you  use the <APIAction> element to specify the API functions to be used in the web app. The name of the function to be called is specified with the mandatory name attribute.
   
   In addition, you can define the following attributes for the  <APIAction> element: 
   

   Attribute	Description
   componentName	Name of the component which is the target of the navigation at the end of the action. Possible values: any string
   externalLink	Specifies an URL here. Possible values: any URL
   externalLinkTarget	Specifies an external link. Possible values: new (default): The page is opened in a new tab. same: The page is opened in the same tab.
   process	Path to the .wrf file. The technical process must be contained in the Services/Processes folder. The path is specified relatively to the Services/Processes folder. Possible values: any string (URI)

   
   

3. In the Web App Control Project, adjust the index.html file in the Sources folder and add the desired elements. 
4. Open the web app in the browser. You will find a list of the supported browsers here.