Appel des tables et des méthodes 4D

Le mode d'accès aux tables 4D référencées dans l’application Wakanda dépend du type d'intégration du catalogue externe, défini sur Wakanda lors de la connexion à l'application distante (cf Intégrer au modèle actif ou utiliser un modèle dédié) :

• fusion au modèle actif (option par défaut) : dans ce cas, les tables distantes sont utilisées exactement comme les classes locales via l'objet ds.
• utilisation d'un modèle dédié : dans ce cas, les tables distantes sont des propriétés de l'objet model dédié.

En cas de fusion au modèle actif, les tables 4D référencées dans l’application Wakanda peuvent être utilisées directement dans le code JavaScript server-side (SSJS) comme propriétés de l’objet ds, tout comme les datastore class locales. 

Note : L’objet ds contient le datastore courant de l’application Wakanda. 

Par exemple pour effectuer une recherche parmi les enregistrements de la table [Employees], vous pouvez écrire :

var emp = ds.Employees.query("age > :1",30);
        //récupérer la collection des enregistrements de la table Employees 
        //dont l’âge est supérieur à 30 dans la variable emp

Côté client, vous pouvez également bénéficier des mécanismes automatiques des datasources basées sur des datastore class et associées à des widgets. Par exemple, si vous associez la datasource 'employés' à un widget de type 'Grid', vous pouvez afficher automatiquement la liste des employés :

Lorsque la table est associée à une datasource, vous pouvez également accéder à ses données via cette datasource. Par exemple pour trier la collection d’enregistrements de la datasource 'employés', vous pouvez écrire :

sources.employés.orderBy("age");
    //trier la collection d’employés en fonction de l’age

Pour plus d’informations sur la manipulation des datastore class, reportez-vous à la documentation de Wakanda.

Les tables 4D référencées sont utilisées dans le code JavaScript server-side (SSJS) comme propriétés du catalogue dans lequel elles ont été placées au moment de la création de la liaison. Le nom du catalogue est celui que vous passez dans le paramètre de connexion Remote datastore name (dialogue de connexion de Wakanda Studio) ou nomLocal (méthodes JavaScript).

Par exemple, si vous avez créé une liaison appelée "my4Dstore" et souhaitez effectuer une recherche parmi les enregistrements de la table [Employees], vous pouvez écrire :

var emp2 = my4Dstore.Employees.query("age > :1", 30);
    // chercher parmi les enregistrements de la table Employees
    // dans la liaison nommée "my4Dstore"

Note d'implémentation : Côté client, l'utilisation d'un modèle dédié dans la version actuelle de 4D Mobile n'autorise pas pour l'instant l'accès aux classes distantes.

Les méthodes 4D référencées dans l’application Wakanda peuvent être utilisées directement dans le code JavaScript comme propriétés des objets datastore class, entity collection ou entity, en fonction de leur portée définie côté 4D (cf. paragraphe Table parente et Portée des méthodes projet). Voici la correspondance entre les objets Wakanda et la portée des méthodes projet :

Note : Les méthodes 4D peuvent également être appelées côté client via des datasources (cf. ci-dessous), dans ce cas toutes les méthodes sont disponibles, la datasource les appliquant automatiquement à la collection courante ou l’entity courante en fonction du contexte. 

Par exemple, si vous effectuez une recherche avec la méthode query (cf. paragraphe précédent), Wakanda retourne une entity collection. Vous pouvez exécuter sur cette collection toute méthode projet 4D dont la portée déclarée est "sélection courante".

Les méthodes 4D peuvent être appelées par du code JavaScript de trois manières :

• depuis du code JavaScript exécuté sur le serveur (SSJS), via l’API SSJS Datastore. Dans ce cas, les méthodes 4D sont appelées en tant que propriétés des objets datastore class, entity collection ou entity, comme décrit ci-dessus.
  Exemples :
  

  var vTot = ds.Emp.raiseSalary(param))
      //raiseSalary est une propriété de datastore class
      //le catalogue est fusionné au modèle actif
  var vTot2 = my4DStore.Company.first().capital(param)) 
      //capital est une propriété d'entity car first() retourne une entity
      //utilsation du modèle dédié my4DStore

• depuis du code JavaScript exécuté sur le client (c’est-à-dire le navigateur) via le Framework Ajax Wakanda (WAF). Deux possibilités s’offrent à vous :
  Note d'implémentation : Dans la version actuelle de Wakanda Enterprise, l'accès client aux méthodes de la base 4D est disponible uniquement lorsque la base distante est connectée avec fusion au modèle actif.
  
  • utiliser l’API WAF Datasource : cette API de haut niveau propose de nombreux automatismes pour gérer les données. Avec cette API, les méthodes 4D sont appelées en tant que propriétés des datasources associées aux datastore class et seront automatiquement appliquées à la datastore class, l’entity collection courante ou l’entity courante en fonction du contexte. Vous pouvez gérer les valeurs de retour des méthodes ou les éventuelles erreurs en utilisant la syntaxe asynchrone (requise pour le code exécuté sur le client).
    Exemple :
    

    sources.employee.raiseSalary(param,
        {onSuccess: function(event)
        { ... //code à exécuter lorsque la méthode a terminé}
    }))

    
    Il n’est pas obligatoire d’utiliser une fonction de callback car les objets datasources proposent des automatismes prenant en charge par exemple la mise à jour des données affichés dans la collection courante à l’issue d’une recherche.
  • utiliser l’API WAF Dataprovider : cette API cliente de bas niveau permet de manipuler directement les objets. Comme pour l’API SSJS Datastore, les méthodes 4D sont appelées en tant que propriétés des objets datastore class, entity collection ou entity. Vous devez toutefois gérer les valeurs de retour des méthodes ou les éventuelles en utilisant la syntaxe asynchrone (requise pour le code exécuté sur le client). Exemple :
    

    ds.Employee.raiseSalary(param, // la syntaxe ressemble à un appel SSJS
        {onSuccess: function(event)    // mais c’est du code client, il faut gérer
        // la méthode callback de l’appel asynchrone
        { ... //code à exécuter lorsque la méthode 4D a terminé}
    }))

Le choix d’un emplacement (serveur ou client) et de l’API dépend des besoins de l’application et est détaillé dans la documentation de Wakanda.

Comme pour les méthodes standard, vous pouvez passer des paramètres lors de l’appel, ils seront reçus dans l’ordre dans les paramètres $1, $2, etc. De même, la méthode peut retourner un résultat dans la variable $0.

Exemple : Vous souhaitez augmenter de 5% les employés dont le salaire est inférieur à 1500.

• Côté 4D, la méthode projet AugmentSalaire a été exposée via 4D Mobile et sa portée est "Sélection courante". Son code est le suivant :
  
   C_REAL($1)
 READ WRITE([Employees])
 FIRST RECORD([Employees])
 While(Not(End selection([Employees])))
    [Employees]salary:=[Employees]salary*$1
    SAVE RECORD([Employees])
    NEXT RECORD([Employees])
 End while
 UNLOAD RECORD([Employees])

• Côté Wakanda, vous exécutez le code suivant sur le serveur :
  

      var emp = ds.Employees.query("salary < :1",1500); 
          // emp contient la collection des employés dont le salaire 
          // est <1500
      emp.AugmentSalaire(1.05);
          //exécuter la méthode AugmentSalaire sur la collection
          //Vous pourriez également écrire 
          //"ds.Employees.query("salary < :1",1500).AugmentSalaire(1.05)

Vous pouvez également retourner une sélection 4D directement comme une collection Wakanda à l'aide de la commande MOBILE Return selection. Par exemple :

Lors de l’appel d’une méthode 4D via la liaison Wakanda :

• si la méthode s’applique à une sélection (entity collection), celle-ci devient la sélection courante et 4D se positionne sur le premier enregistrement de la sélection sans le charger ni activer les liens. Si la sélection est vide, la commande Selected record number retournera 0 au lieu de 1.

• si la méthode s’applique à un enregistrement (entity), celui-ci devient l’enregistrement courant. La sélection courante est réduite à cet enregistrement et la commande Selected record number retourne 1.   
  Note : Pour des raisons d'optimisation et pour éviter des verrouillages inutiles, l'enregistrement est chargé en mode lecture seule. Cependant, la table est en mode lecture-écriture et il suffit d'appeler la commande LOAD RECORD pour forcer le chargement de l'enregistrement en lecture-écriture lorsque c'est nécessaire.

• si la méthode s’applique à une table (datastore class), la sélection courante et l’enregistrement courant ne sont pas affectés.

A noter qu’après l’exécution d’une méthode via 4D Mobile, le contexte 4D est réinitialisé :

• les sélections sont réduites à 0,
• les enregistrements sont dépilés et déchargés,
• les sélections et ensembles locaux au process sont détruits,
• les transactions ouvertes pendant l’exécution de la méthode sont annulées,
• les configurations de liens automatiques par champs, destinations de recherches ou recherches sur le serveur sont réinitialisées,
• les impressions sont annulées,
• les fenêtres sont fermées,
• les éventuelles connexions SQL, PHP ou HTTP sont fermées.

Vous devez veiller à ce que la portée de la méthode 4D corresponde au type d’objet Wakanda appelant, sinon une erreur "TypeError: 'undefined' is not a function" sera retournée par Wakanda.

Par exemple, soit la méthode 4D "getcursel" qui contient le code suivant:

Soit la méthode run côté Wakanda :

var tt = ds.Table_1.query("Field_2 = 'a*'").getcursel();

La méthode query( ) retourne une collection. Si la portée de la méthode getcursel a été définie comme "Enregistrement courant", Wakanda retournera l’erreur suivante :
TypeError: 'undefined' is not a function (evaluating 'ds.Table_1.query("Field_2 = 'a*'").getcursel()')".