Aller au contenu principal
Version: v19 R8

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.

Éditeur de projet

Créez votre application

Vous pouvez créer de nouvelles actions en cliquant sur le bouton +, situé en-dessous du tableau d'Actions. Une nouvelle ligne apparaîtra alors dans le tableau.

Vous définirez ensuite les éléments suivants :

  • Names: The action name to use in the On Mobile App Action database method to trigger your 4D code.
  • Icônes : Sélectionnez une icône pour votre action à partir de la librairie d'icônes. You can also add your own icon.
  • Libellés long et court : Définissez les libellés correspondant aux actions que vous souhaitez afficher dans votre application.
  • Table : Sélectionnez la table à laquelle vous souhaitez appliquer une action.
  • Portée : Choisissez d'appliquer l'action à une entité ou à une 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.

Ajoutez des paramètres à votre action

Vous pouvez ajouter des paramètres d'action et éditer des données directement depuis votre application.

Pour chaque paramètre, vous pouvez éditer les propriétés suivantes :

  • Le nom
  • Le libellé long
  • Le libellé court
  • Input control
  • Mandatory option
  • La valeur par défaut

Depending on the selected input control, you can define the following additional properties:

  • Input constraints (minimum or maximum values)
  • Le placeholder
  • Data Source
info

By default, the Input Control menu displays selectionControls. This is a filter for selection controls, depending on their "format" property. To select a format, you must have created at least one selection input control with this format.

Action parameters

Vous êtes libres de choisir l'ordre des paramètres à l'aide du glisser-déposer.

Actions prédéfinies

Les projets 4D mobile comprennent trois actions (prédéfinies) pour gérer le contenu de votre application :

  • Ajouter
  • Editer
  • Supprimer
  • Partager
  • Trier
  • Open URL

Ajouter

Les projets 4D mobile simplifient la création des actions d'ajout.

Vous n'avez qu'à sélectionner l'option Action d'ajout pour, accessible à partir du bouton +, situé en-dessous de la table Actions.

Add actions

Puis, sélectionnez la table que vous souhaitez associer à l'action d'ajout.

Cela créera automatiquement tous les paramètres dans l'éditeur de projets et vous permettra de modifier chaque valeur d'un champ.

Pour ce genre d'actions, vous constaterez que toutes les propriétés sont déjà saisies à des fins pratiques, à droite de la liste de paramètres.

Editer

La création des actions d'édition suit le même principe que les actions d'ajout, à l'exception du fait que vous ne serez pas en mesure de définir des valeurs par défaut à partir de la section Actions.

Supprimer

La création des actions de suppression suit le même principe que les actions d'édition. La seule différence est que cette action vous permet de supprimer une entité.

Pour créer une action de suppression, sélectionnez l'option Supprimer l'action pour, accessible à partir du bouton + en-dessous du tableau d'actions.

Ce type d'actions doit être utilisé avec précaution.

Delete actions

Partager

Sélectionner l'action Partager permettra à vos utilisateurs de partager du contenu avec d'autres utilisateurs. 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.

Built-in input controls

Input controls define how information will be entered by the user in the mobile app, and also how it will be rendered. The Project editor provides basic input controls for regular data types. These controls are built-in and can be directly selected in the "Input Control" menu.

You can also define custom input controls (see below).

Available built-in input controls depend on the data type:

Data typeInput controlsDescription
TextDefaultPremière lettre de la chaîne en majuscule
Mail AddressOptimized keyboard for email entry
Numéro de téléphoneKeypad for entering telephone numbers
CompteOptimized keyboard for username entry
Mot de passeClavier optimisé pour la gestion des mots de passe
URLOptimized keyboard for URL entry
Code postalOptimized keyboard for zip code entry
Zone de texteInclut plusieurs lignes de texte dans un même champ
Code barresExtraire la valeur associée au code-barres. Formats pris en charge : EAN8, EAN13, Code 39, Code 93, Code 128, QR Code, UPC, PDF417
NumériqueDefaultNombres avec décimales
EntierNombres sans décimales
ScientifiqueNotation scientifique
PourcentageNotation en pourcentage
Nombre en lettresConvertit les nombres en chaînes
DateDefaultNov 23, 1937
Date courte11/23/37
Date longueNovember 23, 1937
Date complèteTuesday, November 23, 1937
HeureDefault3:30 PM
Durée2 hours 30 minutes
BooleanDefaultConvertit les nombres en chaînes
HeureDefault3:30 PM
Durée2 hours 30 minutes
HeureDefault
Coche
ImageDefault
SignaturePermet d'effectuer une signature avec le doigt

Custom input controls

You can add custom input controls to your mobile project to highly customize interactions with the user. There are two categories of custom input controls:

  • selection - used to display a list of values to select (static or dynamic).
  • action - contains Swift ot Kotlin code and can do any relevant action.

You can create custom input controls for both categories. Note that you can also download action input controls from the Input control Github gallery.

Defining custom input controls

A custom input control is associated to a manifest.json file and (optionally) Swift or Kotlin source code. The custom input control files must be stored into a subfolder at the following location:

myProject/Resources/Mobile/inputControls/

The manifest.json file contains several attributes such as name, type, format, etc. depending on the input control category (selection or action).

Selection input controls

Selection 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

Static choice lists (predefined choices hard coded in json) must be located in a manifest.json file in the "inputControls" folder. 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"
Optional "assets"objectto adjust the display size (width and height)
"size"object or integerif integer, pass a single value to create a square image; if object, pass the following attributes:
  • "width" (integer)
  • "height" (integer)
  • 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

    Dynamic choice lists are 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 contains "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 contains "dataClass", "field" and optional "entityFormat"
    "dataClass"texttable name
    "field"textused to extract data to send to server
    Optional "sort"object / collection / text(sort order ascending by default) can be an object that contains "field"(sort criteria/fieldName), and optional "order"; or a collection of field names; or a field name
    Optional "search"boolean / arraycan be an array that contains 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",
    "sort": {"field": "LastName", "order":"descending"}
    }
    }
    }

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

    The various formats are illustrated in this animation:

    customInput

    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 input controls from our Github gallery, depending on what you need for your app. Drop them into the "inputControls" folder (mybase/Resources/mobile/inputControls). They will then be available and selectable from the project editor input controls menu, in the parameter properties of the action.

    The manifest.json file is composed of the following attributes:

    PropertyTypeDescription
    "name"textinput control name
    Optional "inject"boolean"inject" to indicate that when generating the app with this formatter, some source code in Sources must be injected in the final project
    "type"text or collectiona text or a collection of text to define the type (text, integer, boolean) of input control
    Optional "capabilities"objectcapabilities elements to add some information, some optional according to the needs (map, photo, location, etc.)
    "target"text or collectionplatform supported by your input control ("ios", "android")

    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 EditerEdit 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.

    info

    An example of Kotlin input control definition is provided in this tutorial.

    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 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.

    Que faire ensuite ?

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

    See this tutorial for an example of custom Kotlin input control definition.