Modèle d'objet SDOCUM

 

Le modèle d'objet SDOCUM est un modèle spécialement conçu pour saisir des documents de type factures, devis, bons de livraison. Le modèle gère deux tables, une pour l'en-tête du document, l'autre pour les lignes.

Le modèle dérive des modèles SETAPE et SAISIE. Il hérite donc des fonctionnalités classiques suivantes :

- Gestion complète de la table principale (table des en-têtes de documents) avec des possibilités de recherche, consultation, modification, création et suppression des enregistrements.

-         Possibilité de définir des étapes de saisie, afin de guider l'utilisateur lors de la modification et la création.

 

Les fonctionnalités spécifiques au modèle SDOCUM sont les suivantes :

- le modèle gère la saisie des lignes qui constituent le corps du document, avec une numérotation automatique et des possibilités d'insertions et de déplacement.

- à la création d'un enregistrement, le modèle prend en charge la numérotation des en-têtes, en faisant appel à un « composant technique » fourni en standard dans Oxygène++.

- SDOCUM s'occupe de façon quasi-automatique des problèmes de duplication en mémoire des lignes associées à l'en-tête et de leur sauvegarde au moment de l'enregistrement du document. Ainsi, l'utilisateur à la possibilité d'abandonner un ensemble de modifications effectuées sur plusieurs lignes.

Liste des déclarations standards et spécialisées

Liste des variables héritées de SETAPE

Liste des variables héritées du modèle

 

Les variables héritées suivantes sont utiles au composant technique d'attribution des numéros de documents,  consultez le paragraphe « programmation avancée » pour plus informations.

 

 

Les variables héritées suivantes sont relatives à la gestion des lignes. Si elles sont définies sous forme d'extension, elles doivent être rattachées à l'élément « Liste » de saisie des lignes.

 

 

Les variables héritées Prefixe, PrefixeCourant, ModeListe et nDocInstance sont en lecture seule.

 

Liste des méthodes standards

Liste des méthodes spécialisées

 

Exemple d'écran fonctionnant avec SDOCUM

 

Fonctionnement du modèle

Par défaut, le modèle SDOCUM attribue à chaque document créé un numéro qui l'identifie de manière unique. Ce numéro sert ensuite de lien avec les enregistrements de la table des lignes qui constituent le corps du document. Il faut donc que la table d'en-tête et la table des lignes respectent un minimum de règle pour être exploitable par le modèle.

- La table d'en-tête (table principale déclarée par la déclaration TABLE du langage) doit contenir au moins un champ alphanumérique de longueur suffisante pour permettre la numérotation des en-têtes. Le code de ce champ n'est pas imposé par le modèle, le programmeur utilisera la variable héritée CodeNumeroDocument du modèle pour déclarer le code du champ utilisé.

- La table des lignes (table secondaire déclarée par la déclaration TABLE_SECONDAIRE du langage) doit contenir au moins un champ alphanumérique de longueur suffisante pour permettre la numérotation des lignes préfixée par le numéro unique identifiant l'en-tête. Le code de ce champ est fourni par l'intermédiaire de la variable héritée CodeNumeroLigne. Ce champ doit impérativement être de type séquentiel indexé, car il est également utile à la gestion des insertions et des déplacements des lignes.

Le modèle SDOCUM (dérivant du modèle SAISIE) gère de manière classique la table principale des en-têtes de document. La table des lignes est quant à elle entièrement prise en charge par le modèle, avec les caractéristiques suivantes :

- Lorsque un utilisateur visualise un document particulier, le modèle filtre automatiquement les enregistrements de la table des lignes par une requête du type :

            Requete LIGNE.NUM, DebutePar, ENTETE.NUM

- Lorsque l'utilisateur passe en modification d'un document, les lignes qui lui sont rattachées sont dupliquées en mémoire, afin de permettre à l'utilisateur d'abandonner la saisie.

La numérotation des en-têtes de documents

Pour numéroter les en-têtes de document, SDOCUM fait appel à un « composant technique » fourni en standard par Oxygène++. Ce composant n'est rien d'autre qu'un « Objet » de type CALCUL de code OXYNDOC, disponible à la demande. Le composant est appelé depuis la méthode ATTRIBUE_NUMERO_DOCUMENT chaque fois que l'utilisateur passe en création d'un nouveau document, le numéro unique est donc attribué avant que l'utilisateur ne commence à saisir. D'autre part, le modèle prévient le « composant technique » en cas d'abandon, afin de permettre la récupération des « trous » dans la numérotation.

Notez que les mécanismes de numérotation standard peuvent être inhiber, en forçant la variable héritée nDocAuto du modèle ; si tel est le cas, le programmeur doit alors effectuer une attribution de numéro spécifique à son logiciel.

Les variables héritées nDocBase, nDocTable, nDocId, nDocPrefx et nDocLong fournissent des informations directement exploitées par le « composant technique $$-NDOCUM » de numérotation. Pour plus d'informations sur les possibilités de numérotation, consultez la documentation du composant.

Les automatismes de duplication en mémoire des données

Nous l'avons vu, le modèle prend en charge de façon semi-automatique une saisie en mémoire des lignes, afin de permettre à l'utilisateur d'abandonner la saisie. En création ou en modification, les lignes saisies ne sont pas immédiatement stockées sur disque ; elles sont en fait stockées dans une table mémoire de structure identique à la table d'origine.

Le modèle à donc deux modes de fonctionnement bien distincts. En mode visualisation d'un document, les données affichées correspondent réellement aux données stockées sur disque ; alors qu'en mode création ou modification, les lignes du document sont en fait des données temporaires stockées dans une table mémoire gérée par le modèle.

Concrètement, le modèle crée dès le départ, une table mémoire de structure identique à la table des lignes. Lorsque l'utilisateur passe en modification de document, les lignes du document visualisé sont dupliquées dans la table mémoire, alors qu'en mode création, la table mémoire est vidée. L'utilisateur peut ensuite saisir librement sont document, sans que cela n'ait de répercussion sur la cohérence de la base, puisque rien n'est encore enregistré définitivement.

Schéma prédéfini de duplication en mémoire des lignes d'origine

Pendant la duplication en mémoire, le schéma prédéfini du modèle donne la main au programme pour permettre des opérations annexes de cumul ou de lecture de tables en lien.

- appel de la méthode EXTRACTION

 

Pour chaque ligne de la table d'origine,

- appel de la méthode EXTRACTION_DONNEES

- écriture effective de la fiche dans la table mémoire.

Une fois la saisie terminée, l'utilisateur valide son document. Les données en mémoire doivent maintenant être stockées sur disque. Le schéma prédéfini donne la main au programme aux moments opportuns afin qu'il puisse effectuer des opérations complémentaires comme des mises à jour de table en lien.

Schéma prédéfini à la sauvegarde définitive du document

- appel de l'événement composite VALIDATION

Phase 1 :

- Pour chaque fiche de la table des lignes :

- appel de la méthode SUPPRESSION_DONNEES

- suppression de l'enregistrement d'origine.

 

Phase 2 : 

- Pour chaque fiche de la table des lignes en mémoire :

- appel de la méthode VALIDATION_DONNEES

- écriture effective de la fiche dans la table d'origine.

 

Phase 3

- Pour chaque fiche de la table des lignes en mémoire :

- appel de la méthode NETTOYAGE_DONNEES

- suppression de la table mémoire

- appel de la méthode FIN_CREATION ou FIN_MODIFICATION

A tout moment l'utilisateur peut décider d'abandonner le document en cours de saisie, les données en mémoire deviennent inutiles, elles sont donc supprimées.

 

Schéma prédéfini d'abandon de la saisie

- appel de la méthode ABANDON

- pour chaque fiche de la table des lignes en mémoire

- appel de la méthode NETTOYAGE_DONNEES

- puis suppression de la table mémoire

Déclaration des variables héritées

- Un certain nombre d'informations complémentaires doivent être fournies au modèle d'objet SDOCUM pour fonctionner correctement. Ces informations peuvent être fournies soit par programme par l'intermédiaire de variables héritées (*), soit directement dans l'écran sous la forme d'extensions.

Rappels :

-         les variables héritées sont des variables qui ont été définies au niveau du modèle. Dans certains cas le programme à besoin de les manipuler ; il doit pour cela les redéclarer de la façon suivante :

 

 

- les extensions sont définies depuis l'éditeur d'écran sous la forme : <mot clé>:<Valeur> ; il faut pour cela sélectionner le contrôle concerné, et choisir la commande "Extension" disponible dans le menu contextuel (ALT+F10 ou Clic-droit pour accéder au menu-contextuel). Consultez la documentation de l'éditeur d'écran dans le manuel du développeur pour de plus amples informations.

Les variables héritées du modèle

CodeNumeroDocument

La variable héritée CodeNumeroDocument indique le code du champ de la table principale qui sera utilisé pour numéroter les documents. Le champ correspondant doit être de type Alphanumérique et de longueur suffisante pour recevoir le numéro attribué.

L'attribution des numéros de document est (par défaut) assuré par le « composant technique » OXYNDOC fourni en standard dans Oxygène++.

 

CodeListe

La variable héritée CodeListe est obligatoire, elle fournit le code de la liste saisissable de saisie des lignes (corps du document). Le modèle SDOCUM attache automatiquement à ce contrôle un menu-contextuel contenant les commandes standard de création, suppression ou modification d'une ligne.

SeparateurNumero

Caractère utilisé comme séparateur par la numérotation définitive des lignes. SeparateurNumero vaut "|" par défaut (1 seul caractère). C'est le séparateur utilisé en mode VISUALISATION.

SeparateurTempo

Caractère utilisé comme séparateur par la numérotation temporaire des lignes. SeparateurTemporaire vaut "~" par défaut (1 seul caractère). C'est le séparateur utilisé en mode CREATION ou MODIFICATION.

MenuContextuel

(facultatif) Indique le nom du menu contextuel qui est ajouté dynamiquement à l'objet de code <CodeListe>. Par défaut le modèle ajoute le menu contextuel SDOCUM.CTX.

nDocAuto

La variable héritée nDocAuto permet d'inhiber la numérotation automatique des documents effectués par SDOCUM. nDocAuto vaut 0 si la numérotation de l'entête est traitée par le programmeur, 1 dans le cas contraire.

nDocBase et nDocTable

Si nDocAuto vaut 1, les variables héritées nDocBase et nDocTable indiquent impérativement le code de la base et de la table de gestion de la numérotation. Cette table de travail de structure imposée est décrite dans la documentation du composant technique « $$-NDOCUM ».

nDocId, nDocPrefx, nDocLong 

Les variables héritées nDocId, nDocPrefx et nDocLong  fournissent des informations complémentaires à la numérotation des entêtes. Elles indiquent respectivement l'identifiant de la numérotation, le préfixe de numérotation et la longueur maximale du numéro obtenu. Ces informations sont transmises directement au composant technique « $$-NDOCUM ».

 

CodeTableListe

La variable héritée CodeTableListe indique le code du contexte de table associé à la liste.

CodeNumeroLigne

La variable héritée CodeNumeroLigne indique le code du champ de la table de saisie des lignes qui sera utilisé par la numérotation. Le champ correspondant doit être de type alphanumérique, séquentiel indexé et de longueur suffisante.

La longueur du champ peut être évaluée de la façon suivante :

Longueur = Longueur du numéro du document+Longueur du séparateur de numérotation (toujours 1) + longueur de la numérotation des lignes (dépend de vos besoins).

CaractereMini et CaractereMaxi

La numérotation des lignes étant faite sur un champ de type Alphanumérique, le modèle effectue en standard une numérotation en base 76 en utilisant les caractères de "0" à "z" (ce qui permet un nombre de ligne plus important). Si la plage de caractères utilisée en standard ne convient pas (pour des problèmes propres au logiciel), le concepteur peut redéfinir ici, sa propre plage de caractères.

LongueurMaxNumero

Longueur de  la numérotation des lignes, préfixe et séparateur temporaire non compris. Cette information est facultative car par défaut la numérotation utilise l'espace disponible en fonction de la longueur du champ CodeNumeroLigne.

Prefixe

La variable héritée Prefixe contient à tout moment le numéro unique identifiant l'en-tête. Il est également utilisé pour préfixer les numéros de la table des lignes.

PrefixeCourant

La variable héritée PrefixeCourant contient le préfixe complet utilisé pour préfixer les numéros de la table des lignes. Le préfixe courant est constitué du numéro identifiant l'en-tête et du caractère séparateur défini par SeparateurNumero et SeparateurTempo (”|” ou ”~”).

ModeListe

La variable héritée ModeListe indique le mode opératoire en cours pour l'élément « Liste » associé aux lignes du document. ModeListe vaut « V » en mode « Visualisation », « M » en mode « Modification » et « C » en mode « Création ».

Il ne faut pas confondre la variable système Mode (cf : modèle saisie) qui indique le mode opératoire général et le mode de saisie de la ligne en cours. On peut être en mode modification d'un document, tout en étant en cours de création d'une ligne !

Les méthodes standard du modèle

SDOCUM dérive des modèles d'objets SETAPE et SAISIE d'Oxygène++, il dispose donc des méthodes de ces modèles. Rappelons simplement les principales méthodes de gestion de l'en-tête du document :

DEBUT_FICHE

DEBUT_MODIFICATION

DEBUT_CREATION

FIN_CREATION

FIN_MODIFICATION

SUPPRESSION

VALIDATION

ABANDON

Les méthodes spécialisées du modèle

ATTRIBUE_NUMERO_DOCUMENT

Cette méthode est appelée au moment du passage en création d'un nouveau document. Elle est destinée à attribuer le numéro de document qui identifiera de façon unique l'en-tête. Ce numéro est très important, car il est également utilisé comme préfixe de numérotation des lignes. Ainsi pour retrouver les lignes d'une facture de numéro F9612001 il suffit d'utiliser la requête :

Requete LIGNE.NUMERO, DebutePar, ENTETE.NUMERO

Par défaut le modèle SDOCUM prend en charge la numérotation des documents en faisant appel au composant technique $$-NDOCUM qui gère l'incrémentation du numéro et la récupération des trous en cas d'abandon.

Le programme peut intervenir dans ATTRIBUE_NUMERO_DOCUMENT pour changer dynamiquement le préfixe de numérotation.

Les méthodes spécialisées de gestion des lignes

DEBUT_VISUALISATION_LIGNE

Evénement : arrivée sur une ligne en mode VISUALISATION.

Action par défaut : Appel de la méthode DEBUT_FICHE_LIGNE

La méthode est déclenchée à chaque fois que la ligne en cours doit être réactualisée. En particulier lorsque l'utilisateur passe d'un enregistrement à un autre en utilisant les fonctions de déplacement.

La variable héritée ModeListe indique le mode de saisie en cours dans la liste. Elle contient : V pour Visualisation, M pour Modification, C pour Création. Elle est particulièrement utile dans l'événement VALIDATION_LIGNE et ABANDON_LIGNE qui sont communs aux opérations de création et de modification.

 

DEBUT_MODIFICATION_LIGNE

Evénement : arrivée sur une ligne en mode MODIFICATION.

Action par défaut : Appel de la méthode DEBUT_FICHE_LIGNE.

Même remarque que DEBUT_VISUALISATION_LIGNE

Ne pas confondre l'arrivée sur une fiche en mode MODIFICATION et le début d'une modification réelle. En effet, le début d'une modification réelle est associée à l'événement CTRL_DEBUT_MODIF_LISTE.

 

Le programmeur n'a pas le droit d'affecter les champs de la table des lignes dans cet événement, car cela est contraire à la logique du modèle. Rappelons simplement, que le début d'une modification est une opération relativement complexe, qui effectue des modifications de l'état des options du menu-déroulant et de certaines variables systèmes.

 

DEBUT_CREATION_LIGNE

Evénement : Passage en mode CREATION d'une nouvelle ligne.

Action par défaut : Appel de la procedure DEBUT_FICHE_LIGNE

Il est absolument indispensable d'initialiser dans cette méthode les champs qui ne sont pas saisis par l'utilisateur, comme par exemple des champs de cumuls, l'initialisation de ces champs peut également être faite dans le méthode VALIDATION_LIGNE.

DEBUT_FICHE_LIGNE

Evénement : arrivée sur une ligne en mode VISUALISATION, MODIFICATION ou CREATION.

Action par défaut : aucune.

Cette méthode est appelée par les méthodes DEBUT_VISUALISATION_LIGNE, DEBUT_MODIFICATION_LIGNE, et DEBUT_CREATION_LIGNE. Le programmeur peut ainsi regrouper le code commun de ces méthodes dans cet événement générique. On utilisera la variable héritée ModeListe pour connaître le mode en cours (V,M ou C).

 

VALIDATION_LIGNE

Evénement : validation d'une création ou d'une modification de ligne

Action par défaut : aucune.

La méthode est déclenchée lorsque l'utilisateur valide sa saisie d'une ligne en cours de modification ou de création.Elle est particulièrement adaptée pour effectuer les opérations de contrôle de cohérence des informations saisies par l'utilisateur ou des contrôles d'homonymie. L'instruction Controler permet notamment de refuser la validation, et redonne la main à l'utilisateur sur l'information incorrecte.

La méthode VALIDATION_LIGNE n'effectue pas les opérations de mise à jour de la table des lignes ; celles-ci sont effectuées plus tard (dans la méthode APRES_VALIDATION). Le programme ne doit pas effectuer lui-même les opérations de lecture et de mise à jour de la table principale (Modifier, ValiderTampon, AnnulerMaj, InitTampon, Ecrire, Annuler, Liberer, Reserver, etc...) car elles entreraient en conflit avec celles prévues par le modèle.

 

ABANDON_LIGNE

Evénement : abandon d'une MODIFICATION ou d'une CREATION de ligne.

Action par défaut : aucune.

On peut placer ici, des opérations de nettoyage de tables mémoires temporaires utiles au moment de la saisie. Le programme ne doit en aucun cas effectuer lui-même les opérations de lecture et de mise à jour de la table des lignes (Modifier, ValiderTampon, AnnulerMaj, InitTampon, Ecrire, Annuler, Liberer, Reserver, etc...), car elles entreraient en conflit avec celles prévues par le modèle.

FIN_MODIFICATION_LIGNE

Evénement : fin de modification d'une ligne.

Action par défaut : aucune.

La méthode est déclenchée après la méthode VALIDATION_LIGNE et après modification de l'enregistrement. Cet événement est particulièrement adapté pour effectuer des mises à jour de tables en lien.

 

FIN_CREATION_LIGNE

Evénement : fin de création d'une nouvelle ligne.

Action par défaut : aucune.

La méthode est déclenchée après la méthode VALIDATION_LIGNE et après création du nouvel enregistrement. Elle n'est pas déclenchée si l'utilisateur abandonne la création.

SUPPRESSION_LIGNE

Evénement : demande de suppression (annulation) d'une ligne.

Action par défaut : aucune.

La méthode est déclenchée lorsque l'utilisateur demande la suppression de la ligne courante. Le programmeur peut refuser la suppression en utilisant l'instruction Controler. Il peut également placer dans cette méthode des actions complémentaires comme la suppression de données en liens.

La méthode SUPPRESSION n'effectue pas les opérations de mise à jour de la table principale ; celles-ci sont effectuées plus tard, dans la méthode APRES_SUPPRESSION. Le programme ne doit en aucun cas effectuer lui-même les opérations de suppression sur la table des lignes (Instruction Annuler) car dans ce cas elles seraient faites en double

 

SELECTION_LIGNE

Cette méthode donne la main au L4G pour pouvoir réaliser des calculs de variables temporaires pour chaque ligne affichée dans la liste.

MONTE_LIGNE

Méthode à appeler pour déplacer la ligne en cours vers le haut dans la liste. La numérotation est automatiquement modifiée pour que l'enregistrement s'insère effectivement avant l'enregistrement qui le suit.

DESCEND_LIGNE:

Méthode à appeler pour déplacer la ligne en cours vers le bas dans la liste.

EXTRACTION_DONNEES 

Méthode appelée pour chaque ligne du document, pendant la phase de duplication en mémoire.

 

SUPPRESSION_DONNEES

Méthode appelée pour chaque enregistrement de la table ligne lors de la suppression d'un document ou pendant la suppression des anciennes lignes d'un document à la validation définitive d'une modification.

VALIDATION_DONNEES 

Méthode appelée pour chaque enregistrement (en mémoire) de la table ligne lors de la validation complète de la saisie d'un document.

NETTOYAGE_DONNEES 

Méthode appelée pour chaque enregistrement (en mémoire) de la table ligne avant destruction de la table mémoire. Cette destruction à lieu après un abandon ou une validation de saisie d'un document.

AJOUTER_LIGNE

Méthode disponible pour le développeur et permettant d'ajouter des lignes dynamiquement (sans saisie de l'utilisateur). La méthode doit être appelée pour chaque ligne ajoutée, après affectation des champs de la table des lignes. Les lignes ainsi créés s'ajoutent en fin de liste, le modèle prend en charge la numérotation.

Cette méthode doit être utilisée avec précaution. Elle ne doit pas être appelée en mode « Visualisation » de document ou lorsque l'utilisateur est déjà en cours de modification ou de création de ligne