Développement des composants

4D v16.3

Développer et installer des composants 4D

Un composant se présentant sous la forme d’une base de données 4D, le développement d’un composant est semblable au développement d’une fonctionnalité dans une base. Il existe toutefois des restrictions et des règles spécifiques liées à la nature des composants.

Objets utilisables et non utilisables

Un composant peut faire appel à la plupart des objets de 4D : méthodes projet, formulaires projet, barres de menus, énumérations, images de la bibliothèque, etc.

Seuls les objets suivants ne peuvent pas être utilisés par un composant :

tables et champs 4D standard (mais vous pouvez créer et utiliser des tables et champs via les bases externes),
formulaires table et leurs méthodes formulaire associées (en revanche un composant peut appeler un formulaire table de la base hôte),
formulaires utilisateurs,
méthodes base et triggers.

Il n’est pas nécessaire de supprimer ces éléments s’ils existent dans les bases matrices. Lorsqu’un objet “non utilisable” est présent, il est simplement ignoré une fois le composant installé.

Note : Les utilisateurs et groupes ainsi que les éventuels droits d’accès définis dans la base matrice sont ignorés dans la base hôte.

Seules les méthodes projet “partagées” par le composant seront visibles et sélectionnables en mode Développement dans la base hôte. A l’inverse, les méthodes projet “partagées” de la base hôte peuvent être appelées par le composant. Pour plus d’informations sur ce point, reportez-vous au paragraphe Partage des méthodes projet.

Seuls les formulaires "publiés" par le composant peuvent être visibles et intégrables dans les formulaires de la base hôte en tant que sous-formulaires. Pour plus d’informations sur ce point, reportez-vous au paragraphe Partage des formulaires.

Les autres objets du composant (formulaires projet non publiés, énumérations, menus, etc.) pourront être utilisés par le composant mais ne seront pas accessibles en tant qu’objets de développement depuis la base hôte. A noter que certains objets sont cloisonnés et d’autres sont partagés entre la base hôte et le(s) composant(s). Pour plus d’informations sur ce point, reportez-vous au paragraphe Objets partagés et objets non partagés.

Un composant peut utiliser les plug-ins installés dans l’application 4D ou dans la base hôte. Il n’est pas possible d’installer des plug-ins dans le dossier du composant.

Les méthodes base et les paramètres génériques des bases matrices (dossier Web, préférences, etc.) ne sont jamais pris en compte.

Commandes non utilisables

Les commandes suivantes ne sont pas compatibles avec une utilisation dans le cadre d’un composant car elles modifient le fichier de structure — ouvert en lecture. Leur exécution dans un composant provoque l’erreur -10511, “La commande NomCommande ne peut pas être appelée depuis un composant” :

ON EVENT CALL
Method called on event
SET PICTURE TO LIBRARY
REMOVE PICTURE FROM LIBRARY
SAVE LIST
ARRAY TO LIST
EDIT FORM
CREATE USER FORM
DELETE USER FORM
CHANGE PASSWORD
EDIT ACCESS
Set group properties
Set user properties
DELETE USER
CHANGE LICENSES
BLOB TO USERS
SET PLUGIN ACCESS

Notes :

La commande Current form table retourne Nil lorsqu’elle est appelée dans le contexte d’un formulaire projet. Par conséquent, elle ne peut pas être utilisée dans un composant.
Les commandes SQL de définition de données (CREATE TABLE, DROP TABLE, etc.) ne peuvent pas être utilisées dans le cadre des composants.

Gestion des erreurs

Une méthode de gestion d'erreurs installée par la commande ON ERR CALL s'applique à la base en cours d'exécution uniquement. En cas d'erreur générée par un composant, la méthode d'appel sur erreur de la base hôte n'est pas appelée, et inversement.

Utilisation de formulaires

Seuls les formulaires projet (formulaires non associés à une table en particulier) peuvent être exploités directement dans un composant. Tous les formulaires projet présents dans la base matrice peuvent être utilisés par le composant.

Un composant peut faire appel à des formulaires table de la base hôte. A noter qu’il est nécessaire dans ce cas d’utiliser des pointeurs plutôt que des noms de table entre [] pour désigner les formulaires dans le code du composant.
Note : Si un composant utilise la commande ADD RECORD, le formulaire Entrée courant de la base hôte sera affiché, dans le contexte de la base hôte. Par conséquent, si le formulaire comporte des variables, le composant n’y aura pas accès (cf. section Interaction entre les composants et les bases hôtes).

Vous pouvez publier des formulaires de composants comme sous-formulaires dans les bases hôtes. Avec ce principe, vous pouvez notamment développer des composants proposant des objets graphiques. Par exemple, les Widgets proposés par 4D sont basés sur l’emploi de sous-formulaires en composants. Ce point est détaillé dans le paragraphe Partage des formulaires.

Utilisation de tables et de champs

Un composant ne peut pas utiliser les tables et les champs définis dans la structure 4D de la base matrice. En revanche, il peut créer et utiliser des bases externes, et donc utiliser des tables et des champs en fonction de ses besoins. Les bases externes sont créées et gérées via le langage SQL. Une base externe est une base 4D indépendante de la base 4D principale, mais qui est manipulée depuis la base 4D principale. Utiliser une base externe signifie désigner temporairement cette base comme base courante, c’est-à-dire comme base cible des requêtes SQL exécutées par 4D. Les bases externes sont créées à l'aide de la commande SQL CREATE DATABASE.

Pour plus d'informations sur les bases externes, reportez-vous au paragraphe A propos des bases externes.

Exemple

Le code suivant est inclus dans un composant et effectue trois actions élémentaires avec une base de données externe :

création de la base de données externe si elle n'existe pas déjà,
ajout de données dans la base de données externe,
lecture de données depuis la base de données externe.

Création de la base de données externe :

 <>MyDatabase:=Get 4D folder+"\MyDB" // (Windows) stocker les données dans un répertoire autorisé

 Begin SQL

        CREATE DATABASE IF NOT EXISTS DATAFILE :[<>MyDatabase];

        USE DATABASE DATAFILE :[<>MyDatabase];

        CREATE TABLE IF NOT EXISTS KEEPIT

        (

        ID INT32 PRIMARY KEY,

        kind VARCHAR,

        name VARCHAR,

        code TEXT,

        sort_order INT32

        );

 

        CREATE UNIQUE INDEX id_index ON KEEPIT (ID);

 

        USE DATABASE SQL_INTERNAL;

 

 End SQL

Ecriture dans la base de données externe :

 $Ptr_1:=$2 // récupération des données de la base hôte via des pointeurs

 $Ptr_2:=$3

 $Ptr_3:=$4

 $Ptr_4:=$5

 $Ptr_5:=$6

 Begin SQL

 

        USE DATABASE DATAFILE :[<>MyDatabase];

 

        INSERT INTO KEEPIT

        (ID, kind, name, code, sort_order)

        VALUES

        (:[$Ptr_1], :[$Ptr_2], :[$Ptr_3], :[$Ptr_4], :[$Ptr_5]);

 

        USE DATABASE SQL_INTERNAL;

 

 End SQL

Lecture dans une base de données externe :

 $Ptr_1:=$2 // accès aux données de la base hôte via des pointeurs

 $Ptr_2:=$3

 $Ptr_3:=$4

 $Ptr_4:=$5

 $Ptr_5:=$6

 

 Begin SQL

 

    USE DATABASE DATAFILE :[<>MyDatabase];

 

    SELECT ALL ID, kind, name, code, sort_order

    FROM KEEPIT

    INTO :$Ptr_1, :$Ptr_2, :$Ptr_3, :$Ptr_4, :$Ptr_5;

 

    USE DATABASE SQL_INTERNAL;

 

 End SQL

Utilisation de ressources

Les composants peuvent utiliser des ressources (anciennes ressources Mac OS “classiques” ou fichiers de type XLIFF).

Conformément aux principes de gestion des ressources (cf. paragraphe Architecture des bases), les fichiers de ressources des composants doivent être placés dans un dossier Resources, situé à côté du fichier .4db ou .4dc du composant. Si le composant est d’architecture .4dbase (architecture conseillée), le dossier Resources doit être placé à l’intérieur de ce dossier.

Les mécanismes automatiques sont opérationnels : les fichiers XLIFF présents dans le dossier Resources d’un composant seront chargés par ce composant. Un composant utilisera aussi automatiquement les ressources Mac OS “classiques” situées dans le fichier .rsr à côté du fichier .4db ou .4dc. Les fichiers de ressources “classiques” situés dans le dossier Resources devront être explicitement chargés dans le composant à l’aide des commandes du thème “Ressources”.

Dans une base hôte contenant un ou plusieurs composant(s), chaque composant ainsi que la base hôte dispose de sa propre “chaîne de ressources”. Les ressources sont cloisonnées entre les différentes bases : il n’est pas possible d’accéder aux ressources du composant A depuis le composant B ou la base hôte (cf. paragraphe Objets partagés et objets non partagés).

Aide en ligne des composants

Un mécanisme spécifique a été mis en place afin de permettre aux développeurs d’ajouter des aides en ligne à leurs composants. Le principe est semblable à celui proposé pour les bases de données 4D (cf. section Annexe A : Aide en ligne personnalisée) :

l’aide du composant doit être fournie sous le forme d’un fichier suffixé .htm, .html ou (Windows uniquement) .chm,
le fichier d’aide doit être placé à côté du fichier de structure du composant et porter le même nom que le fichier de structure,
l’aide est alors automatiquement chargée dans le menu Aide de l’application avec le libellé “Aide de...” suivi du nom du fichier d’aide.