Skip to main content
Version: v19 R7 BETA

Actions

The 4D Mobile Project editor allows you to create actions to include in your mobile app.

You can use preset actions or custom actions and define their parameters.

On the 4D side, you can execute 4D code in the On Mobile App Action database method.

Actions are automatically available in the mobile interface.

Project Editor Side

Create your action

You can create a new action by clicking on the + button at the bottom of the Actions table. A new line will appear in the Actions table.

Next you'll need to define the following:

  • Names: The action name to use in the On Mobile App Action database method to trigger your 4D code.
  • Icons: The icon to choose from your icon library. You can also add your own icon.
  • Short and long Labels: The labels for the actions to display in your app.
  • Table: The table on which you want to apply the action.
  • Scope: Where to use the action, an entity or a table.

Action section

note

You can sort the Names with a drag-and-drop. This operation will set the order in which they will appear in the app's menu.

Add parameters to your action

You can add action parameters and edit data directly from your app.

For each parameter, you can edit the following properties:

  • Name
  • Long label
  • Short label
  • Format
  • Input constraints (define minimum or maximum values)
  • Placeholder
  • Mandatory field definition
  • Default value

Action parameters

You are free to change the order of parameters using drag and drop.

Here are the different Formats you can select for a parameter:

TEXT
FormatDescription
TextCapitalize the first letter of a string
Email AddressOptimized iOS keyboard for email entry
Phone NumberiOS keypad for entering telephone numbers.
AccountOptimized iOS keyboard for username entry
PasswordOptimized to handle passwords
URLOptimized iOS keyboard for URL entry
Zip CodeOptimized iOS keyboard for zip code entry
Text areaIncludes multiple lines of text in a single field
BarcodeExtract barcode associated value. Supported formats : EAN8, EAN13, Code 39, Code 93, Code 128, QR Code, UPC, PDF417
NUMBER
FormatDescription
NumberNumbers with decimals
IntegerNumbers without decimals
ScientificScientific Notation
PercentagePercent Notation
Spell OutConvert numbers into strings
DATE
FormatDescription
DateNov 23, 1937
Short Date 11/23/37
Long DateNovember 23, 1937
Full DateTuesday, November 23, 1937
TIME
FormatDescription
Time3:30 PM
Duration2 hours 30 minutes
BOOLEAN
FormatDescription
Boolean
Check mark
IMAGES
SignatureAllow to sign with the finger

Preset actions

4D mobile projects include the following (predefined) preset actions to manage your app content:

  • Add
  • Edit
  • Delete
  • Share
  • Sort
  • Open URL

Add action

4D mobile projects makes the Add actions creation process very simple.

The only thing you need to do is select the Add action for option, accessible from the + button at the bottom of the Actions table.

Add actions

Then just select the table you want to link to this add action.

This will automatically create all the parameters for you in the Project Editor. In the generated app, this will allow you to edit each field value.

For those kind of action, you will see that all properties are already filled in for your convenience at the right side of the parameter's list.

Edit action

Edit actions creation follows the same process as the Add actions, with the exception that you will not be able to define default values from the Actions section.

Delete action

Delete action creation follows the same process as the Edit action. The only difference is that this action allows you to remove an entity.

To create a Delete action, select the Delete action for option accessible from the + button at the bottom of the Actions table.

This type of action should be used with caution.

Delete actions

Share action

Selecting the Share action will allow your mobile users to share content with other users. You just need to select the scope:

  • entity: to share content from a detail form
  • table: to share a list form

See the Deep Linking page for more details.

Sort action

Sort actions are useful to:

  • define a default sort order for the table list forms
  • allow your mobile users to choose a list sort order

When you create a sort action for a table, you need to select the first field on which the sort will be done:

Docusaurus

The field is added to the Sort Criteria list. An ascending sort order is set by default, but you can change it using the Sort order menu.

You can sort entities in more than one field. Each field you sort is referred to as a sort level. For example, the results of a two-level ascending sort of the lastName and firstName fields would produce a list such as this:

Aardvark, Anthony
Aardvark, Artemis
Aardvark, Arthur
...
Zygote, Elena
Zymosian, Elmer

To add one or more sort level(s) in the Sort Criteria list, select the + button under the list and configure each level:

sort

Sort order menu on the mobile app

When you define more than one sort action for a table, mobile users automatically benefit from a sort menu. It contains all the predefined sort actions:

sort

When only one sort action is defined for a table, the sort menu is not displayed on the mobile app side.

Open URL action

The Open URL action allows your mobile users to open an url from their mobile app. This action will display a web page served by 4D Server in a web area from within the mobile app.

When you select this action, you have to define the path that will be opened:

open url

You can only define a path starting with /, i.e. relative to the current 4D web folder.

This action can be set for any table and any scope (Table or Current entity). Like other actions, the Open URL action will be automatically available in the mobile app interface (short or long label).

note

To close the web page and get back to the mobile app interface, use the $4d.mobile.dismiss() function from within the page (see below).

Web Server Side

The request sent to the server contains the context of the app (current entity and/or dataclass) in the X-QMobile-Context header. The content of this header is formatted in JSON and encoded in base64.

tip

You can get the context information already decoded as object using the 4D Mobile App Server component and its WebHandler class.

Context information can be processed in the web page to return through standard 4D web server features:

Web Area Side

For your page to interact with the mobile app, some javascript code is automatically provided in the $4d.mobile object. This object contains the following properties and functions:

PropertyTypeDescription
$4d.mobile.action.namestringname of the action
.labelstringlabel of the action
.shortlabelstringshort label of the action
.dismiss()Functioncloses the native web view
.status(message)Functionshows a message in native app for the user
message: string
message: object with "message" (or "statusText") and "success" (or "level") keys
.logger.log(level, message : string)Functionshows a message in native app for the developer
.info(message : string)Functionshows a message in native app for the developer
.info(message : string)Functionshows a message in native app for the developer
.warning(message : string)Functionshows a message in native app for the developer
.error(message : string)Functionshows a message in native app for the developer
.debug(message : string)Functionshows a message in native app for the developer
.verbose(message : string)Functionshows a message in native app for the developer

On Mobile App Action

The On Mobile App Action database method is available to call all of your 4D methods.

After creating all of your actions, just click on the Create button from the Actions table to automatically generate a Case of code block that includes all your action names in the On Mobile App Action method.

notes
  • You can refresh the selection after executing an action using $result.dataSynchro:=True.
  • You can notify the app user when action has been executed using $result.statusText:="Message you want to display".
  • You can also decide to force close the Edition form using $result.close:=True.

Action input controls

You can easily interact with native apps by using custom input controls, which follow the same logic as Labels & Icons custom formatters with native code.

To do so, you can create your own input controls with native code, or you can download a few input controls from our gallery, depending on what you need for your app. Drop them into a specific “inputControls” folder (mybase/Resources/mobile/inputControls), unzip them and drag them into this newly created folder. They will then be available and selectable from the project editor input controls menu, in the parameter properties of the action.

For example, if you want to get a client's phone number from your mobile contact list, the phoneContact input control template enables you to automatically fill your client's phone number field.

Architecture EditEdit screenEdit screen

Bear in mind that all input controls from the gallery are open source and available on Github. So feel free to share your own input controls or your feedback on the 4D Forum.

Input control selection

Action input controls display formatted elements (values, pictures) in your mobile apps. These elements are automatically included in your action form, more specifically in a choice list, in order to select one of the values and to use it as a parameter. These choice lists can be either static or dynamic:

  • Static choice lists (predefined choices hard coded in json) that are located in an 'inputControls' folder (mybase/Resources/mobile/inputControls) in a manifest.json file. They are defined by several elements, as follows:
PropertyTypeDescription
"name"textaction input control name
Optional "binding"text"imageNamed" to bind on images (Images must be in a subfolder "images" in the action formatter folder)
"choiceList"objectan object or collection to define a list of key(data sent to server)/value(displayed value to the user)
"type"text or collectionone text or a collection of text to define a type (text, integer, boolean) of input control
Optional "format"textto select interface: push(default if not defined)/segmented/popover/sheet/picker

Here is an example of a manifest.json file containing the contact information of a company's subsidiaries, that can be used as a static choice list:

{
"name": "choiceListSheet",
"type": [
"text"
],
"format": "sheet",
"choiceList": {
"1":"Paris",
"2":"Tokyo",
"3":"Sydney",
"4":"San Jose",
"5":"Rabat",
"6":"Eching"
}
}
  • Dynamic choice lists based on datasource (choices depending on the database content). This method enables you to get data very fast by filling a form field using helper modules. Not only will your lists be directly accessible from your mobile app, they will also be constantly updated. The manifest.json file is composed of the following elements:
PropertyTypeDescription
"name"textinput control name
"choiceList"objectan object that contain "dataSource" (see table below)
"type"text or collectionone text or a collection of text to define a type (text, integer, boolean) of input control
Optional "format"textto select interface: "push"(default if not defined), "segmented", "popover", "sheet", "picker"
PropertyTypeDescription
"dataSource"objectan object that contain "dataClass", "field" and optional "entityFormat"
"dataClass"texttable name
"field"textused to extract data to send to server
Optional "sort"object / collection / textcan be an object that contains "field"(sort criteria/fieldName), and optional "order" (sort order ascending by default)
Optional "search"boolean / arraycan be an array that contain field to use for search
Optional "entityFormat"textfor the display value (if no format we use the extracted data from field)

Note: When the choice list is extensive, the optional "search" element becomes available.

Here is an example of a dynamic choice list:

{
"name": "datasourcePush"
"type": [
"text"
],
"format":"push",

"choiceList": {
"dataSource": {
"dataClass": "Contact",
"field": "LastName",
"entityFormat": "%FirstName% %LastName% - %Job%",
"search": "LastName",
"order": "descending"
}
}
}

On the Project editor side, once you select your Input control format, the dataSource will be selectable from a filtered list based on the format you have selected. Your app will then be updated and ready-to-use!

Here is an example with the push format:

customInput customInput2

Here are the different formats available on the generated application:

  • Push format:

customInput2

  • Segmented & picker formats:

customInput2

  • Popover format:

customInput2

  • Sheet format:

customInput2

Note: You can access your input control using the arrow icon next to the "Input Control" field.

Offline mode actions

The user of an app can draft, store and queue action requests, even if they are working offline (adding a customer's phone number, uploading a picture, printing an invoice or a quote, deleting an address, etc.). All these tasks are placed in the Pending actions list until the network is accessible. Once the user is online, all pending actions are consistently synchronized, executed and then visible in the Completed actions list.

Pending tasks can be visualized and opened from:

The Settings screen

It displays a summary and a history of all pending and completed tasks.

Action section

The List & Detail forms

They display all the tasks related to the table or to the entity that you are currently viewing.

Action section

notes
  • The "Share" predefined action is only executable online
  • Actions are editable while pending, but they can no longer be modified once they switch to the "Completed" mode.

Update pending tasks that failed

Due to your server business logic, some tasks could be rejected. For mobile users, it is then possible to edit and to retry sending the relevant pending tasks. To do so, you can display a status text describing, in the "Complete" actions history, the reason of the failure. For example, you can reject an action sent by a mobile user to the server and inform him that the operation has failed. In that case, you can set the success value to False and provide a message in statusText, as follows:

 $response:=New object("success"; False; "statusText"; "Operation failed"))

You can even add some errors by action parameters for the alphaField parameter, for example:

$response.errors:=New collection(New object("parameter"; "alphaField"; "message"; "Alpha field must contains a valide value")

Mobile app Side

In your mobile app, actions are available in different ways in your List and Detail forms, depending on the templates you select in the Forms section.

Table List forms

  • Entity action: Swipe left on a cell to display the available actions in a List form. A "More" button is displayed if you've defined more than three actions per entity.

Entity Lisform Tableview

  • Table actions: A generic actions button is available in the navigation bar to display a list of available table actions.

Table Listform Tableview

tip

Actions will be displayed in the same order as defined in the Action section.

Collection List forms

  • Entity action: Depending on the template, actions are displayed by clicking on a generic button or by maintaing the pressure on a cell.

Entity Listform Collectionview

  • Table actions: Like the Table List forms, a generic Actions button is available in the navigation bar to display a list of availble table actions.

Table Listform Collectionview

Detail forms

As with Table actions in List forms, a generic Actions button is available in the navigation bar to display all your entity actions in a list.

Entity Detailform

Edition forms

If you have created an Edit or an Add action, as soon as you select it from the action list, an Edition form will appear.

Send task comment

From here, you can:

  • edit all of your fields by selecting them, and
  • validate or cancel your modifications using the Done or Cancel buttons (available in the navigation bar).

For your convenience, the Edition form includes a few special features:

  • The keyboard type depends on the selected parameter type in the Action section.
  • You can go to the next or previous field using the arrow on top of the keyboard.
  • The iOS keyboard can be closed by touching anywhere outside of a field.
  • Indication is given to the user when a value is not valid.
  • The view focuses on empty mandatory fields when the user clicks the Done button.

Where to go from here?

See this tutorial that will guide you through the action definition process.