Deuxième épisode de la mini série consacrée au tri dans FileMaker.

Introduction

Configurer les différents tris possibles dans un mode liste, en cliquant sur les libellés en tête des colonnes, peut s’avérer rapidement laborieux à faire, d’autant plus si votre solution comporte de nombreux modèles en mode liste avec le même système de tri.

En effet, FileMaker ne propose malheureusement aucun mécanisme natif permettant de choisir les rubriques de tri de manière dynamique, ce qui force à concevoir des scripts de tri remplis de très nombreuses conditions afin de lancer le bon tri suivant l’en-tête de colonne cliquée, et donc la valeur passée en paramètre au script de tri.

Par bonheur, quelques techniques existent pour contourner partiellement cette limitation et ainsi bénéficier d’un choix dynamique pour les rubriques de tri.

Dans cet article nous allons explorer l’une de ces techniques, elle ne concernera que les développeurs et utilisateurs de FileMaker (FM) sous environnement macOs, car elle est basée sur la technologie AppleScript (AS).

Exécuter du code AppleScript dans et depuis FileMaker Pro est possible depuis les toutes premières versions du logiciel, cela reste encore l’un de ses points forts sous macOS (même si, pour des raisons de compatibilité avec d’autres plate-formes, il est hélas souvent délaissé dans les projets professionnels).

Nous allons donc voir comment mettre rapidement en place un script de tri dynamique et générique, utilisable tel quel dans tous vos modèles liste, avec juste un zeste de code AppleScript.

Préparation

Pour commencer, de quoi allons nous avoir besoin ?

De très peu de choses : juste de deux rubriques globales de travail, qui peuvent être crées dans n’importe quelle table, mais qui trouveraient une place naturelle dans une table “Paramètres” (ou “Settings”).

Voici quelques explications à propos de ces deux rubriques (le suffixe “_g” est pour signaler leur portée globale) :

1. Tout d’abord, une rubrique de type texte, nommée par exemple “tri_rubrique_g”, qui contiendra le nom complet (table::rubrique) de la rubrique de tri ;
2. Ensuite, une rubrique de type nombre, nommée “tri_ordre_g” par exemple, qui contiendra une valeur booléenne indiquant l’ordre de tri : 0 = ordre descendant , 1 = ordre ascendant (pour s’assurer d’avoir toujours une valeur booléenne, on peut activer une entrée auto calculée avec le code suivant : ObtenirCommeBooleen ( Contenu ) ) ;

Le principe est simple : on passe le nom complet (table::rubrique) de la rubrique à trier en paramètre au script FileMaker de tri, si ce nom est identique à celui déjà mémorisé dans la rubrique globale “tri_rubrique_g”, alors on inverse tout simplement l’ordre de tri de la rubrique “tri_ordre_g”.

Si le nom passé en paramètre est différent de celui mémorisé, alors on mémorise ce nouveau nom dans la rubrique “tri_rubrique_g” et on règle la valeur de l’ordre de tri “tri_ordre_g” à 1 (tri ascendant par défaut).

Bon, pas trop compliqué jusqu’à là… voyons maintenant quel code AppleScript nous allons utiliser et comment l’exécuter…

AppleScript

FileMaker propose deux mécanismes pour exécuter un code AppleScript au sein d’un script avec l’action “Exécuter AppleScript” (présent dans la section “Divers” de la liste des actions) :

1. “AppleScript Calculé” : il s’agit d’y inscrire le code AppleScript comme si c’était du simple texte, FileMaker fera une interprétation puis une compilation à la volée du code avant son exécution, à chaque fois que le script FileMaker sera lancé. Dans ce mode, le passage de paramètres au code AppleScript est plutôt simple, il se fait par simple concaténation à l’intérieur du code ;
2. “AppleScript Natif” : il s’agit d’y inscrire le code AppleScript brut, qui sera compilé une seule fois à la validation du dialogue, puis il sera prêt à être exécuté tel-quel à chaque lancement du script FileMaker. Ici, le passage de paramètres au code AppleScript est un peu plus compliqué à mettre en place, il faudra par exemple prévoir des rubriques dédiées (nous ne verrons pas ce cas de figure ici).

Nous allons donc utiliser du code AppleScript calculé, plus simple à implémenter avec le passage des paramètres.

Plusieurs techniques sont possibles, comme :

1. Utiliser le code AppleScript directement dans le dialogue de l’action de script (solution la plus directe, souvent suffisante) ;
2. Placer le code AppleScript dans une rubrique globale et utiliser des balises pour être remplacées par les bons paramètres ;
3. Placer le code AppleScript dans une fonction personnalisée, puis utiliser les paramètres de la fonction FileMaker pour passer les paramètres à AppleScript.

Comme ici nous travaillons en local, la solution 2 avec la rubrique globale est celle que nous allons utiliser, plus simple d’accès pour notre démo. En revanche, pour une utilisation avec des fichiers hebergés dans un serveur, la solution 3 avec une fonction personnalisée semble la plus appropriée.

Dans tous les cas, le code AppleScript demeure le même, seule la technique du passage des paramètres diffère.

Voyons donc notre code AppleScript avec quelques commentaires (précédés de deux tirets “–“) pour bien comprendre le rôle de chaque instruction :

-- Structure 'try' de contrôle au cas où une erreur se produisait pendant l'exécution
try
 
    -- On récupère les valeurs de la rubrique et de l'ordre de tri dans des variables AS
    -- Pour ce faire, on utilise deux balises, délimitées par deux caractères dièse "##",
    -- qui seront remplacées par les valeurs issues des rubriques globales de travail

    -- Le nom complet (table::rubrique) de la rubrique de tri
    set sRubrique to "##tri_rubrique##"

    -- Le numéro booléen correspondant à l'ordre de tri
    set nOrdre to ##tri_ordre##
 
    -- On active FileMaker pour lancer le tri
    tell current application
 
        -- On récupère la bonne propriété d'ordre de tri à utiliser
        set pOrdre to contents of item (nOrdre + 1) of {descending, ascending}
 
        -- On lance le tri dans le modèle actif sur la bonne rubrique et le bon ordre
        sort current layout by field sRubrique in order pOrdre
 
    end tell

on error err_mssg number err_num
 
    -- On affiche un dialogue d'infos si une erreur se produit lors de l'exécution
    display dialog ("" & err_num & " : " & err_mssg)
end try

Les deux balises “##tri_rubrique##” et “##tri_ordre##” seront remplacées avec la fonction “Substituer()”, au sein du script FileMaker, par les valeurs issues des rubriques globales de travail “tri_rubrique_g” et “tri_ordre_g” respectivement.

Voyons maintenant de quoi il sera fait le code de notre script FileMaker…

Script FileMaker

Nous allons commencer par initialiser une variable “$rubrique” avec la valeur passée en paramètre au script. En effet, chaque bouton qui fera appel à ce script de tri, passera en paramètre le nom complet (table::rubrique) de la rubrique de tri.

Si le paramètre est vide, alors on annule le tri.

Comme expliqué plus haut, on défini l’ordre de tri selon que la valeur de la variable “$rubrique” et le contenu de la rubrique globale “tri_rubrique_g”, si elles sont identiques, alors on se contente d’inverser l’ordre de tri, sinon, on règle l’ordre de tri à la valeur par défaut = 1 (tri ascendant).

Ensuite on rensigne la rubrique globale “tri_rubrique_g” avec la variable “$rubrique”, on peut désormais faire le remplacement des balises “##” dans le code AppleScript avant de lancer son exécution.

Voici le code du script FileMaker complet avec les commentaires :

# Commandes de contrôle… comme d'hab…
Gestion erreurs [ Oui ]
Autor. annulation utilisateur [ Non ]
# 
# On récupère le paramètre de script et on efface tout éventuel espace de bord inutile
Définir variable [ $rubrique ; Valeur: SupprimerEspace ( Obtenir ( ParamètreScript ) ) ] 
# 
# Si une touche morte est enfoncée ou si la rubrique de tri est vide, alors on initialise les rubriques globales, on annule le tri et on active le premier enregistrement
Si [ ( Obtenir ( TouchesSpécialesActives ) ) Or ( EstVide ( $rubrique ) ) ] 
    Définir rubrique [ Settings::tri_rubrique_g ; "" ] 
    Définir rubrique [ Settings::tri_ordre_g ; 1 ] 
    Annuler tri des enreg.
    Afficher enreg/requête/page [ Premièr(e) ]
    Fin de script [ Résultat de texte: "Annulation du tri…" ] 
Fin de si
# 
# On défini et mémorise l'ordre de tri dans sa rubrique globale selon la rubrique de tri choisie : si même rubrique, alors on inverse l'ordre de tri, sinon on utilise la valeur par défaut 1 (ordre ascendant)
Définir rubrique [ Settings::tri_ordre_g ; ObtenirCommeBooleen ( Si ( EstEgal ( $rubrique ; Settings::tri_rubrique_g ) ; Not Settings::tri_ordre_g ; 1 ) ) ] 
# 
# On mémorise la nouvelle rubrique de tri choisie dans sa rubrique globale
Définir rubrique [ Settings::tri_rubrique_g ; $rubrique ] 
# 
# On valide tout ça…
Valider enreg./requêtes [ Avec boîte de dialogue: Non ] 
# 
# On initialise une variable avec le code AppleScript à exécuter, en remplaçant au passage les balises par les vraies valeurs de travail
Définir variable [ $applescript ; Valeur: Substituer ( 	Settings::tri_applescript_g ; 	[ "##tri_rubrique##" ; Settings::tri_rubrique_g ] ; 	[ "##tri_ordre##" ; Settings::tri_ordre_g ] ) ] 
# 
# On exécute le tri avec un AppleScript calculé
Exécuter AppleScript [ $applescript ] 
# 
# À la fin du tri, on active le premier enregistrement
Afficher enreg/requête/page [ Premièr(e) ]
# 
Fin de script [ Résultat de texte: "Tri effectué…" ] 
# 
# Code récupéré grâce au plugin MBS

Petite subtitilité ergonomique, nous avons ajouté un test sur les éventuelles touches spéciales actives lors du clic sur les boutons de tri, cela permet d’annuler le tri par simple clic d’un en-tête de colonne avec une touche morte enfoncée (commande, contrôle, option ou shift), cela évite de passer par un bouton dédié (même si cela reste toujours intéressant à proposer, surtout nécessaire si votre solution est utilisée avec FileMaker Go).

Voyons maintenant comment implémenter tout ceci dans notre modèle…

Implémantation

Nous allons donc construire un modèle liste, dans notre fichier de démo (communes de France), nous avons placé 4 rubriques, à savoir :

1. Code postal de la commune ;
2. Nom de la commune ;
3. Une date calculée aléatoirement entre les années 2000 et 2020 ;
4. Un numéro d’index aléatoire de 1 à 999.

Nous disposons donc, pour nos tests de tri, de deux rubriques de type texte (1 et 2) et de deux rubriques de type nombre (3 et 4).

Chaque en-tête de colonne sera donc un bouton qui lancera notre script FileMaker de tri, en passant comme paramètre le nom complet (table::rubrique) de la rubrique à trier (nous utilisons ici la fonction native ObtenirNomRubrique ( table::rubrique ) pour s’assurer d’avoir toujours le nom correct, quelque soient les modifications ultérieures).

Nous pouvons ajouter une mise en forme conditionnelle qui, en comparant le nom de la rubrique à trier avec celui existant dans la rubrique globale “tri_rubrique_g”, pourra changer l’aspect du bouton pour bien visualiser sur quelle colonne le tri a bien été effectué.

Nous pouvons également ajouter un indicateur de l’ordre de tri, dans notre fichier de démo nous utilisons la valeur de la rubrique globale “tri_ordre_g” comme affichage booléen avec deux caractères unicode représentant des flêches, une vers le haut “▲” (tri ascendant), l’autre vers le bas “▼” (tri descendant). L’affichage de cet indicateur sera géré par un masquage conditionnel sur le même principe, mais inversé, que celui de la mise en forme conditionnelle.

Voilà, nous avons pratiquement fini, il suffit d’ajouter des sous-récapitulatifs après tri sur les rubriques dont nous désirons faire des regroupements, tel qu’illustré par Tanguy dans le premier opus de cette mini série sur le tri.

Conclusion

AppleScript offre beaucoup de possibilités avec FileMaker, comme celle présentée ici, même si d’autres solutions de tri dynamiques existent pour ce type d’utilisations en mode liste, certains natives FileMaker.

En tout cas, n’hésitez-pas à décortiquer le fichier de démo en pièce jointe ci-dessous, pour bien visualiser et comprendre toutes les techniques décrites ici, vous pourrez ensuite nous faire part de toutes vos questions et remarques dans les commentaires ci-dessous.

Téléchargez le fichier de démo ici :  1MT_Tri_S02E01.fmp12

[vc_row bg_color=””][vc_column][vc_column_text]Voici peut-être un sujet un peu pointu, mais il ne fait jamais de mal d’interroger parfois les fondamentaux… essayons ici de faire le tour complet de la problématique de la casse en FileMaker.

D’abord, pour ne pas se perdre tout de suite, qu’est-ce que la “casse” ?

Ici, je parierais que beaucoup de ceux qui savent déjà ce qu’est la sensibilité à la casse ne savent pas d’où vient le mot.

Ce terme nous vient de l’imprimerie, et plus précisément de la typographie : pour composer une page, il fallait attraper très rapidement des caractères en plomb. On les rangeait alors dans une sorte de caissette en bois compartimentée et que l’on appelait casse. Chaque compartiment contenait les plombs pour un caractère de la fonte (ou police). Or on ne les rangeait pas par ordre alphabétique mais par fréquence d’utilisation. Les minuscules étant bien plus employées que les majuscules, leurs compartiments devaient être proches du typographe, et donc en “bas-de-casse”, les majuscules en “haut-de-casse”.

Pour ceux que cela amuse, je vous invite à réfléchir aux termes encore employés à l’ère de l’informatique : casse, fonte, valise de police…

FileMaker comporte des fonctions de calcul qui nous permettent de manipuler la casse d’un texte :

• Minuscule ( Texte ) pour convertir un texte en minuscules
• Majuscule ( Texte ) pour convertir un texte en majuscules
• NomPropre ( Texte ) pour convertir la première lettre de chaque mot en majuscules et les autres lettres en minuscules

Ainsi que des fonctions qui permettent d’ajouter ou de retirer un style (dont la casse) :

• AjoutStyleTexte ( Texte ; Styles ) – avec les paramètres Uppercase, Lowercase, Titlecase et SmallCaps
• SupprimerStyleTexte ( Texte ; Styles ) – avec les mêmes paramètres

Mais… qu’est-ce donc que la sensibilité à la casse ? C’est très simple : selon les environnements et le contexte, on considérera qu’une majuscule a la même valeur qu’une minuscule (insensibilité à la casse) ou au contraire qu’elle a une valeur différente (sensibilité à la casse)

Par exemple dans un dictionnaire français comprenant des noms propres, comme par exemple le Larousse, on ne fera pas de différence de classement entre une majuscule et une minuscule, ainsi un nom propre avec une majuscule se retrouvera parmi des noms communs, adjectifs ou autre adverbes en minuscules.

Dans d’autres contextes, on fera nettement la différence.

Bien souvent dans les langages informatiques, la plupart des traitements sont effectués avec sensibilité à la casse. Cela vient notamment du fait que les premiers ordinateurs travaillaient sur des jeux réduits de caractères (ASCII), et ne pouvaient se permettre de s’encombrer de considérations telles que a = A à chaque fois qu’ils devaient analyser un a.

Mais FileMaker, qui comme vous le savez a été pensé pour des humains normaux (ou presque), fait l’effort depuis très longtemps de l’insensibilité à la casse. Ainsi, vous pouvez comparer des chaînes de caractères telles que “Milan” (la ville) et “milan” (le rapace), et constater une égalité :

"Milan" = "milan"

Ceci fonctionne aussi bien dans les calculs que dans les index (utilisés dans les liens, listes de valeurs ou recherches).

D’ailleurs, on peut noter qu’il en est de même avec les caractères accentués : “à” = “a”, si toutefois la langue d’indexation est le français (en russe par exemple, le E (yé) et le Ë (yo) sont bien deux lettre différentes, avec chacune sa place dans l’alphabet et dans le dictionnaire. Mais il s’agit de caractères différents de l’alphabet latin, bien que visuellement similaires)

On pourrait donc penser que “FileMaker n’est pas sensible à la casse”, un point c’est tout.

Or ce serait bien ennuyeux si on en restait là.

Il existe un nombre limité de cas où FileMaker est sensible à la casse (case sensitive en anglais), essayons d’en faire le tour.

Tout d’abord, certaines fonctions de calcul le sont. On en cite souvent trois en oubliant que FileMaker continue d’évoluer et que ça n’est pas parce qu’en 1914 il y en avait trois qu’il y en a forcément trois aujourd’hui.

Voici donc les trois “connues” :

• Filtre ( TexteAFiltrer ; TexteFiltre ) – Filtre ( “AaBbZ” ; “aZ” ) retournera “aZ” et non “AaZ” : le A majuscule est éliminé par le filtre
• EstEgal ( TexteOrigine ; TexteComparaison ) – EstEgal ( “monMotDePasseSuperSecret” ; “monmotdepassesupersecret” ) retournera 0 car les deux chaînes ne sont pas identiques, alors que, rappelons-le, “monMotDePasseSuperSecret” = “monmotdepassesupersecret” retournera 1 (l’opérateur de comparaison = n’est pas sensible à la casse). Soit dit en passant, si votre mot de passe est super secret, préférez une comparaison de hash MD5 plutôt que de stocker le mot de passe en clair dans la base de données !
• Substituer ( Texte ; ChaîneRecherchée ; ChaîneRemplacée ) – Substituer ( “Bébé” ; “b” ; “d” ) retournera “Bédé” et non “dédé”; car B et b sont deux caractères différents pour cette fonction sensible à la casse.

Et donc on aurait ainsi fait le tour de la question ? Que nenni…

Depuis FileMaker 12, la fonction ExecuterSQL ( RequêteSQL ; séparateurRubrique ; séparateurLigne{; arguments…} ) –  entrouvre la porte au langage de requête SQL au sein de FileMaker (d’un point de vue strict, cette porte était déjà entrouverte pour les connexions ODBC ou les plugins). Or SQL est en grande partie sensible à la casse, même si là encore, l’implémentation de FileMaker est assez tolérante.

Soit une table “maTable” contenant les colonnes “champ1” avec les valeurs A1, A2, A3, et “Champ2″ et les valeurs  B1, B2, B3 :[/vc_column_text][ish_table align=”center” header_bg_color=”color7″ header_text_color=”color4″ border_color=”color7″]

[/ish_table][vc_column_text]La formule suivante :

ExecuteSQL ( "SELECT champ1 from matable where champ2 = 'B3'" ; "" ; "" )

retournera bien “A3”. Autrement dit, le nom des tables et des colonnes n’est pas sensible à la casse, mais c’est maintenant le cas de la plupart des implémentations SQL. Les mots clef comme SELECT, FROM ou WHERE dans cette requête sont toujours insensibles à la casse. Par convention, on les écrit en majuscules, sauf ici où j’ai voulu illustrer l’insensibilité à la casse.

en revanche, la même formule dans laquelle on changera le critère ainsi :

ExecuteSQL ( "SELECT champ1 from matable where champ2 = 'b3'" ; "" ; "" )

retournera du vide, car “b3” n’est pas égal à “B3” dans une requête SQL.

Astuce : si ce comportement vous dérange, vous pouvez utiliser la fonction SQL lower :

ExecuteSQL ( "SELECT champ1 from matable where lower ( champ2 ) = 'b3'" ; "" ; "" )

Donc il y a bien quatre et non trois fonctions sensibles à la casse…

… est-ce tout ?

Non ! depuis FileMaker 16, de nouvelles fonctions sont apparues :

• SortValues ( valeurs {; typeDeDonnée ; locale } )
• UniqueValues ( valeurs{; typeDeDonnée ; locale} )

Au passage, on remarquera que FileMaker a apparemment décidé de ne plus traduire le nom des fonctions de calcul. Le traducteur a dû être sensible à la casse… sociale.

Donc essayons cette formule :

Uniquevalues ( list ( "a" ; "b" ; "B" ; "A" ; "à" ; "À" ) ; 1 ; "" )

le résultat est :

a
b

donc aucune sensibilité à la casse.

en modifiant légèrement, pour explorer :

Uniquevalues ( list ( "A" ; "a" ; "b" ; "B" ; "A" ; "à" ; "À" ) ; 1 ; "" )

le résultat est

A
b

donc on voit que le A majuscule est retourné à la place du a minuscule parce qu’il est trouvé en premier, mais comme on n’est pas ici sensible à la casse, le a minuscule n’est pas retourné en plus.

Mais… n’avais-je pas sous-entendu que ces fonctions étaient justement sensibles à la casse ?

Et bien… c’est qu’elles peuvent l’être !

Le dernier paramètre (facultatif) de ces fonction est locale, et il permet justement de préciser dans quelle “langue” on veut trier ou dédoublonner.

Or s’il est une langue que nous parlons vous et moi couramment, c’est bien… l’Unicode.

Dans l’aide, vous constatez que deux variantes peuvent être utilisées : Unicode_Raw et Unicode_Standard.

Uniquevalues ( list ( "a" ; "b" ; "B" ; "A" ; "à" ; "À" ) ; 1 ; "Unicode_Raw" )

retourne

a
b
B
A
à
À

autrement dit chaque caractère est différent (accentué, non accentué, majuscule, minuscule…). Voici donc deux nouvelles fonctions (SortValues et UniqueValues) sensibles à la casse !

Uniquevalues ( list ( "a" ; "b" ; "B" ; "A" ; "à" ; "À" ) ; 1 ; "Unicode_Standard" )

retourne

a
b
à

on voit qu’on perd la sensibilité à la casse mais pas celle aux accents.

Je crois que nous avons fait le tour de la question de la sensibilité à la casse dans FileMaker. J’espère que vous aurez appris quelque chose. N’hésitez pas à prolonger la discussion dans les commentaires ci-dessous.[/vc_column_text][/vc_column][/vc_row]

Tableau est un puissant outil d’analyse des données et depuis peu, il est devenu possible d’y connecter nos bases de données FileMaker à l’aide d’un connecteur dédié livré avec la version 16 de FileMaker Server.

Alors que nous testions ses possibilités dans le but d’en faire profiter nos clients, nous avons eu une mauvaise surprise : les statistiques que nous obtenions étaient fausses…

Après une recherche en profondeur, nous avons fini par en découvrir la cause : le séparateur de décimal.

Contre toute attente, et ce, malgré la norme du standard JSON, FileMaker Server renvoie des nombres formatés selon les paramètres du système. Or dans nos contrées, c’est la virgule alors que le standard JSON attend un point.

Résultat : tous les nombres décimaux sont ignorés par Tableau et les statistiques que vous obtenez sont faussées

Que faire ? Changer le format du système pour le forcer à renvoyer des nombres justes ? Cette option ne nous enchante guère, elle pourrait de plus avoir des conséquences inattendues.

Heureusement, nous sommes parvenu à trouver un moyen de contournement bien plus simple et efficace !

Tout se passe au niveau du connecteur FileMaker pour Tableau, dans un petit fichier javascript répondant ou doux nom de “fm_connector_util.js” que vous trouverez dans le dossier “/Library/FileMaker Server/Web Publishing/publishing-engine/node-wip/public/tableau/js”.

Dans ce fichier se cache une fonction qui permet de convertir à la volée les dates “FileMaker” dans un format de date compatible avec Tableau et il s’est avéré très facile d’étendre son champ d’action aux nombres !

En attendant un correctif officiel de la part de FileMaker nous avons décidé de partager ce fix avec la communauté par ce qu’il n’y a pas de raison pour que nous soyons les seuls à pouvoir utiliser Tableau en Europe !

Voici le fichier en question : fm_connector_util.js

Placez le simplement dans le dossier “FileMaker Server/Web Publishing/publishing-engine/node-wip/public/tableau/js” (remplacez le fichier existant), rechargez votre source de donnée dans Tableau et le tour est joué !

NB : Pensez à faire une copie de sauvegarde du fichier original avant d’appliquer le correctif !

Version française

Is the FileMaker PHP API at end of life? This is a question that could arise since a new technology appeared in FileMaker Server 16 to allow us to share data from a FileMaker database through a website: the REST API. However, although this new API (still in beta version – [EDIT: in final version with FileMaker 17]) brings a real wind of freshness and offers beautiful prospects of evolution, it remains nonetheless limited for the instant and less adapted to a classic web architecture where the web server occupies a central role.

Therefore XML publishing combined with the FileMaker PHP API is still often the best way to share and use a solution directly on the Web.

It still suffers from some shortcomings: developed to be compatible with PHP 4 at its release (a version still widespread at the time), the original PHP API (download) has hardly changed since (except for some minor corrections) ).

Anyone who has used it, certainly remember many alerts indicating the use of deprecated methods as soon as they were run with a newer version of PHP. Although these errors have since been corrected, the advent of PHP 7 has unfortunately brought them up to date.

This lack of evolution has made its code obsolete, it is not at all in step with the new development methods that have emerged in recent years in the PHP universe, and in fact this update delay makes its integration complicated in any project using a framework or a “modern” CMS.

An update of this library had become more and more necessary to ensure its durability. But here, although PHP still has a bright future ahead of time given its steady improvements and popularity, FileMaker has decided to take a good look at the more popular technologies such as JavaScript frameworks. No need therefore to hope for any evolution on this side (the XML publication is and will never be available on FileMaker Cloud for example).

So there was only one solution: roll up his sleeves and put his hands in the grease to give a little makeover to our dear PHP API!

Methodology

Obviously, before touching any line of code, one had to dive first, like a Cistercian monk, into a long and thorough study of the original source code, to understand its structure, its functioning and its particularities in order to grasp well the magnitude of the upcoming work.

Very quickly, two requirements were imposed: simplifying the source code as much as possible (while trying to optimize it), and modernizing it to bring it into line with current development standards, especially those recommended by the PHP-FIG group, in the goal of ensuring better interoperability with most modern PHP frameworks and CMSs.

On the simplification side, the changes mainly focused on a new error management strategy and rewriting part of the code in order to comply with the PSR-2 standard (source code writing conventions).

The new error handling is to overcome the occasional conditional tests for the benefit of a single general test structure by exception, with a block of type “try / catch” encompassing the main work instructions (see a sample code lower). The original method still remains functional, however, to ensure backward compatibility.

This first step was completed, it was now necessary to consolidate compatibility with the most recent versions of PHP and make the most of it to modernize the code as much as possible.

Therefore, concerning the modernization of the source code, the addition of namespaces, on all the classes of the API, coupled with a “self-loading” system, as recommended by the PSR-4 specification, have imposed themselves, ensuring de facto compatibility with the most popular PHP frameworks of the moment.

This technique has resulted in a profound change in the file structure, without changing the original operation of the API, in order to ensure full compatibility with projects based on the API-PHP of Original FileMaker.

Open to the World

We were there ! the PHP API of FileMaker was finally modernized! Then remained open to the rest of the free world!

Indeed, for some years now, PHP projects have been structured around a multitude of third-party libraries, like many other languages ​​such as java, javascript, …

In order to simplify the management of these multiple source codes and to ensure their updating without effort (the code being maintained by other developers), a very popular tool has now been created: Composer. It allows to manage, with the help of a simple configuration file (json) all the third libraries of a project, ensuring the installation and the update.

Obviously, our API had to join the community to complete its mutation, which necessitated some adaptations not without consequences: that led to abandon the original configuration file of the API (in the world of Composer, a third library should never be modified to keep the benefit of updates). This implies that it is now delivered with a “default” configuration, which you must modify at the moment of instantiation.

Evolutions

Our new API ready, we were eager to integrate it into a large project to measure its potential, which was quickly the case! A project requiring the use of a Framework (yii2) was quickly presented.

This first test run highlighted some deficiencies that did not necessarily appear during the rewrite, including the need to facilitate debugging during development and improve communication with third-party libraries.

Thus, a certain number of new features have been implemented over the water, of which here is a non-exhaustive list (some developed specifically, others resulting from functions already existing in FileMaker API-XML, but not implemented in the original FileMaker PHP-API):

• Choice of date format input and output of the API;
• Support for “paging” when running a script;
• Definition of global at the execution of a search;
• Method to retrieve the last request (URL) sent to the FileMaker server (extremely useful for debugging in the development phase);
• The “Layout” object can now return the name of the source table (in addition to the name of the table instance) via the $ $layout->table property, allowing easier management of execution contexts;
• Method for retrieving a list of values ​​associated with a field on a model (lists can be renamed without impact on your website).

Installation and configuration

Here are some of the main steps to install and implement this new FileMaker PHP API.

There are two methods of installing this API:

1. Via the “Composer” solution, adding "airmoi/filemaker" : "*" to your configuration file;
2. Manually by downloading the latest sources from the dedicated GitHub website and installing the uncompressed files in your project: GitHub Repository

For the loading and the activation of the API, it is very simple, it is enough to include the file “autoload.php” which is at the root of the project (optional in case of installation via Composer):
require ('/path/to/API/autoload.php');

You must then declare the class to use using its namespace (the autoloader is responsible for automatically finding the files to load for the proper functioning of the API):
use airmoi\FileMaker\FileMaker;

Since the configuration file was removed, two methods are available to configure your project:

1. Using the FileMaker PHP method: setProperty('name', $value), which can be used to individually configure the different parameters of the project;
2. Use a parameter array directly when creating the FileMaker object, for example: new FileMaker($db, $host, $user, $pass, ['dateFormat' => 'd/m/Y']) to configure the project in one single instruction.

Here is an example code illustrating all this:

[code language=”php”]
// Load the API
require_once (‘/path/to/API/autoload.php’);

// define name space
use airmoi\FileMaker\FileMaker;

// configuration options
$options = [
‘errorHandling’ => ‘default’,
‘locale’ => ‘fr’,
‘prevalidate’ => true,
‘dateFormat’ => ‘d/m/Y’,
];

// FileMaker object w/ parameter array
$fm = new FileMaker($db, $host, $user, $pass, $options);

// List all layouts and view as types
$layouts = $fm->listLayouts();
foreach ($layouts as $layout) {
echo $layout . ‘
‘;
}
[/code]

Usage

Error trapping: the ‘old’ way

[code language=”php”]
// Configuration
$options = [
‘errorHandling’ => ‘default’,
];

$fm = new FileMaker($db, $host, $user, $pass, $options);

// Get a layout and test
$layout = $fm->getLayout(‘sample’);
if (FileMaker::isError($layout)) {
echo "Error: " . $layout->getMessage();
exit;
}

// Execute query
$result= $fm->newFindAnyCommand(‘sample’)->execute();
if (FileMaker::isError($record)) {
echo "Error: " . $record->getMessage();
exit;
}

// Get a record
$record = $result->getFirstRecord();
if (FileMaker::isError($record)) {
echo "Error: " . $record->getMessage();
exit;
}

// Modify a record
$record->setField(‘text_field’, str_repeat(‘a’, 51));
$record->commit();
if (FileMaker::isError($record)) {
echo "Error: " . $record->getMessage();
exit;
}
[/code]

The old error management system is obtained by setting the “errorHandling” parameter to the “default” value.
As you can see, it forces you to repeat your controls for virtually every instruction.

Error Management: The Exception Method

[code language=”php”]
// Exception mode is configured by default
// no need to specify it
$fm = new FileMaker($db, $host, $user, $pass);

try {
// Try to get a layout
$layout = $fm->getLayout(‘sample’);

// Get a record (in 1 line)
$record = $fm->newFindAnyCommand(‘sample’)->execute()->getFirstRecord();

// Modify record
$record->setField(‘text_field’, str_repeat(‘a’, 51));
$record->commit();
} catch (FileMakerException $e) {
// Trap errors that can have occurred on any line
printf (‘Error %d : %s ‘, $e->getCode(), $e->getMessage());
}
[/code]

As you can see, exception handling via the try / catch block can significantly reduce the number of lines of code.
All its logic can be centralized, which simplifies the reading of the code, improves its reliability and its maintenance.

Limit the results of a script

[code language=”php”]
$fm = new FileMaker($db, $host, $user, $pass);
$result = $fm->newPerformScriptCommand(‘sample’, ‘create sample data’, 50)
->setRange(5, 20)
->execute();

echo $result->getFetchCount() . ‘/’ . $result->getFoundSetCount();
[/code]

Now, with this new API, you can ask which data interval to retrieve. For example, you can request to have the data corresponding to the records from 5 to 25. This allows to obtain a pagination on a script result, which was impossible before.

Set a global field on executing a query

[code language=”php”]
$fm = new FileMaker($db, $host, $user, $pass);
$result = $fm->newFindCommand(‘sample’)
->setGlobal(‘global_field’, date(‘m/d/Y’))
->addFindCriterion(‘test_field’, 1)
->execute();

echo $result->getFetchCount() . " enregistrements trouvés.";
[/code]

Very handy feature because it now allows to define a global field at the time of the execution of a query, which will allow you for example to recover, in your results, related data through a global field.

Conclusion

As explained at the beginning of the article, FileMaker’s PHP API really needed a fresh start to adapt to the evolution of the latest technologies, especially regarding the interaction with modern PHP frameworks.

This rewriting required many hours of work and countless tests. The result is more than encouraging as this new version is now used daily in production on several professional projects managed by the 1-more-thing team.

But, although it is in the stable and mature state to be used in production, this rewrite is not yet finished, many other improvements are in progress and others to predict. If you want to contribute to its evolution, you are obviously welcome: GitHub Repository.

Many thanks to all those who participated, directly or indirectly, in the realization of this project, and a special thanks to Matthias Kühne for all his contributions.

English version

L’API PHP de FileMaker est elle en fin de vie ? C’est une question que l’on pourrait se poser depuis qu’une nouvelle technologie est apparue dans FileMaker Server 16 pour nous permettre de partager les données d’une base FileMaker au travers d’un site web: l’API REST. Cependant, bien que cette nouvelle API (encore en version beta – [EDIT : en version finale avec FileMaker 17]) apporte un vrai vent de fraîcheur et offre de belles perspectives d’évolution, elle n’en demeure pas moins limitée pour l’instant et moins adaptée à une architecture web classique où le serveur web occupe un rôle central.

Aussi, la publication XML couplée à l’API PHP de FileMaker reste encore à ce jour le meilleur moyen pour partager et utiliser une solution directement sur le Web.

Elle souffre malgré tout de certaines lacunes : développée pour être compatible avec PHP 4 à sa sortie (une version encore répandue à l’époque), l’API PHP originale (téléchargement) n’a quasiment pas évolué depuis (à part quelques corrections mineures).

Tous ceux qui l’ont utilisée, se rappellent certainement des nombreuses alertes indiquant l’utilisation des méthodes dépréciées dès lors qu’elles étaient exécutées avec une version plus récente de PHP. Bien que ces erreurs aient été corrigées depuis, l’avènement de PHP 7 les a malheureusement remises au goût du jour.

Ce manque d’évolution a rendu son code vétuste, il n’est plus du tout en phase avec les nouvelles méthodes de développement qui ont émergé ces dernières années dans l’univers de PHP, et de fait ce retard d’actualisation rend son intégration compliquée dans tout projet utilisant un framework ou un CMS “moderne”.

Une mise à jour de cette bibliothèque était devenue de plus en plus nécessaire pour assurer sa pérennité. Seulement voilà, bien que PHP ait encore de beaux jours devant lui au vu de ses améliorations régulières et de sa grande popularité, FileMaker a décidé de faire les yeux doux aux technologies plus en vogue actuellement, telles que les frameworks JavaScript. Inutile dès lors d’espérer une quelconque évolution de ce côté-là (la publication XML n’est et ne sera a priori jamais disponible sur FileMaker Cloud par exemple).

Il ne restait donc qu’une seule solution : retrousser ses manches et mettre les mains dans le cambouis afin de prodiguer une petite cure de jouvence à notre chère API PHP !

Méthodologie

Évidemment, avant de toucher à la moindre ligne de code, il fallait se plonger d’abord, tel un moine cistercien, dans une longue et approfondie étude du code source original, pour comprendre sa structure, son fonctionnement et ses particularités afin de bien saisir l’ampleur du chantier à venir.

Très vite, deux exigences se sont imposées : simplifier au mieux le code source (tout en essayant de l’optimiser), et le moderniser afin de le rendre conforme aux standards de développement actuels, notamment ceux recommandés par le groupe PHP-FIG, dans l’objectif d’assurer une meilleure interopérabilité avec la plupart des frameworks et CMS PHP modernes.

Côté simplification, les changements se sont portés principalement sur une nouvelle stratégie de gestion des erreurs et sur la réécriture d’une partie du code afin de respecter la norme PSR-2 (conventions d’écriture du code source).

La nouvelle gestion d’erreurs consiste à s’affranchir des tests conditionnels ponctuels au bénéfice d’une seule structure générale de test par exceptions, avec un bloc de type “try / catch” englobant les principales instructions de travail (voir un exemple de code plus bas). La méthode originale reste cependant toujours fonctionnelle afin d’assurer une compatibilité descendante.

Cette première étape terminée, il fallait maintenant consolider la compatibilité avec les versions les plus récentes de PHP et en tirer le meilleur parti pour moderniser au maximum le code.

Dès lors, concernant la modernisation du code source, l’ajout des espaces de noms, sur l’ensemble des classes de l’API, couplé à un système “d’auto-chargement”, comme le préconise la spécification PSR-4, se sont imposés, assurant de facto la compatibilité avec les frameworks PHP les plus en vogue du moment.

Cette technique a entraîné un changement en profondeur de la structure des fichiers, sans pour autant modifier le fonctionnement d’origine de l’API, et ce, dans le but de garantir une parfaite compatibilité avec les projets basés sur l’API-PHP de FileMaker originale.

S’ouvrir au reste du monde

Nous y étions ! l’API PHP de FileMaker était enfin modernisé ! Ne restait plus alors qu’à l’ouvrir au reste du monde libre !

En effet, depuis quelques années maintenant, les projets PHP se sont structurés autour d’une multitude de bibliothèques tierces, à l’instar de beaucoup d’autres langages tel que java, javascript, …

Afin de simplifier la gestion de ces multiples codes source et d’assurer leur mise à jour sans effort (le code étant maintenu par d’autres développeur), un outil désormais très populaire a été créé : Composer. Celui-ci permet de gérer, à l’aide d’un simple fichier de configuration (json) l’ensemble des bibliothèques tierces d’un projet, en assurant l’installation et la mise à jour.

De toute évidence, notre API se devait de rejoindre la communauté pour achever sa mutation, ce qui nécessita quelques adaptations non sans conséquences : cela a conduit à abandonner le fichier de configuration original de l’API (dans le monde de Composer, une bibliothèque tierce ne doit jamais être modifiée pour garder le bénéfice des mises à jour). Cela implique qu’il est désormais livré avec une configuration « par défaut », qu’il vous appartient de modifier au moment de son instanciation.

Evolutions

Notre nouvelle API fin prête, il nous tardait de l’intégrer dans un projet d’ampleur pour en mesurer son potentiel, ce qui fut rapidement le cas ! Un projet nécessitant l’emploi d’un Framework (yii2) s’étant rapidement présenté.

Ce premier galop d’essai a permis de mettre en lumière certaines lacunes qui n’étaient pas forcément apparues lors de la réécriture, notamment le besoin de faciliter le débogage lors des développements et d’améliorer la communication avec des bibliothèques tierces.

Ainsi, un certain nombre de nouvelles fonctionnalités ont été implémentées au fil de l’eau, dont voici une liste non exhaustive (certaines développées spécifiquement, d’autres issues des fonctions déjà existantes dans l’API-XML de FileMaker, mais non implémentées dans l’API-PHP de FileMaker d’origine) :

• Choix du format de date en entrée et sortie de l’API ;
• Prise en charge de la « pagination » lors de l’exécution d’un script ;
• Définition de globales à l’exécution d’une recherche ;
• Méthode permettant de récupérer la dernière requête (URL) envoyée au serveur FileMaker  (extrêmement utile pour le debogage en phase de développement);
• L’objet “Layout” peut désormais renvoyer le nom de la table source (en plus du nom de l’occurrence de table) via la propriété $layout->table, permettant une gestion plus simple des contextes d’exécution ;
• Méthode permettant la récupération d’une liste de valeurs associée à un champ sur un modèle (les listes peuvent ainsi être renommées sans impact sur votre site web).

Installation et configuration

Voici, en quelques lignes, les principales étapes pour installer et mettre en service cette nouvelle API-PHP de FileMaker.

Il y a deux méthodes d’installation de cette API :

1. Via la solution “Composer”, en ajoutant "airmoi/filemaker" : "*" à votre fichier de configuration ;
2. Manuellement en téléchargeant les dernières sources sur le site de GitHub dédié et en installant les fichiers décompressés dans votre projet : Dépot GitHub

Pour le chargement et l’activation de l’API, c’est très simple, il suffit d’inclure le fichier “autoload.php” qui se trouve à la racine du projet (facultatif en cas d’installation via Composer):
require ('/path/to/API/autoload.php');

Vous devez ensuite déclarer la classe à utiliser à l’aide de son espace de nom (l’autoloader se chargeant de trouver automatiquement les fichiers à charger pour assurer le bon fonctionnement de l’API) :
use airmoi\FileMaker\FileMaker;

Le fichier de configuration ayant disparu, deux méthodes sont disponibles pour configurer votre projet :

1. Utilisation de la méthode PHP de FileMaker : setProperty('name', $value), qui peut servir pour configurer individuellement les différents paramètres du projet ;
2. Utilisation d’un tableau de paramètres directement à la création de l’objet FileMaker, par exemple :
   new FileMaker($db, $host, $user, $pass, ['dateFormat' => 'd/m/Y'])
   permettant de configurer le projet en une seule instruction.

Voici un code d’exemple illustrant tout ceci :

[code language=”php”]
// Chargement de l’API
require_once (‘/path/to/API/autoload.php’);

// Définition de l’espace de noms
use airmoi\FileMaker\FileMaker;

// Réglage des options de configuration
$options = [
‘errorHandling’ => ‘default’,
‘locale’ => ‘fr’,
‘prevalidate’ => true,
‘dateFormat’ => ‘d/m/Y’,
];

// Création de l’objet FileMaker avec le tableau de paramètres
$fm = new FileMaker($db, $host, $user, $pass, $options);

// Récupération de la liste de tous les modèles et leur affichage
$layouts = $fm->listLayouts();
foreach ($layouts as $layout) {
echo $layout . ‘
‘;
}
[/code]

Exemples d’utilisation

Gestion des erreurs : l’ancienne méthode

[code language=”php”]
// Réglage des options de configuration
$options = [
‘errorHandling’ => ‘default’,
];

$fm = new FileMaker($db, $host, $user, $pass, $options);

// Récupération d’un modèle et test sur une éventuelle erreur
$layout = $fm->getLayout(‘sample’);
if (FileMaker::isError($layout)) {
echo "Error: " . $layout->getMessage();
exit;
}

// Execution de la requete
$result= $fm->newFindAnyCommand(‘sample’)->execute();
if (FileMaker::isError($record)) {
echo "Error: " . $record->getMessage();
exit;
}

// Récupération d’un enregistrement
$record = $result->getFirstRecord();
if (FileMaker::isError($record)) {
echo "Error: " . $record->getMessage();
exit;
}

// Modification de l’enregistrement
$record->setField(‘text_field’, str_repeat(‘a’, 51));
$record->commit();
if (FileMaker::isError($record)) {
echo "Error: " . $record->getMessage();
exit;
}
[/code]

L’ancien système de gestion d’erreur s’obtient en réglant le paramètre “errorHandling” à la valeur “default”.
Comme on peut le constater, elle vous oblige à répéter vos contrôles pour pratiquement chaque instruction.

Gestion des erreurs : la technique des exceptions

[code language=”php”]
//Le mode de gestion par Exception est configuré par défaut
//il n’est donc pas nécessaire de le préciser dans les options
$fm = new FileMaker($db, $host, $user, $pass);

try {
// Récupération d’un modèle
$layout = $fm->getLayout(‘sample’);

// Récupération d’un enregistrement en 1 ligne
$record = $fm->newFindAnyCommand(‘sample’)->execute()->getFirstRecord();

// Modification de l’enregistrement
$record->setField(‘text_field’, str_repeat(‘a’, 51));
$record->commit();
} catch (FileMakerException $e) {
//Gestion des erreurs ayant pu survenir à n’importe quelle ligne
printf (‘Erreur %d : %s ‘, $e->getCode(), $e->getMessage());
}
[/code]

Comme vous pouvez le constater, la gestion d’erreur par exception via le bloc try/catch permet de réduire de façon considérable le nombre de lignes de code.
Toute sa logique peut être centralisée, ce qui simplifie la lecture du code, améliore sa fiabilité et sa maintenance.

Limiter les résultats d’un script

[code language=”php”]
$fm = new FileMaker($db, $host, $user, $pass);
$result = $fm->newPerformScriptCommand(‘sample’, ‘create sample data’, 50)
->setRange(5, 20)
->execute();

echo $result->getFetchCount() . ‘/’ . $result->getFoundSetCount();
[/code]

Désormais, avec cette nouvelle API, on peut demander quel intervalle de données récupérer. Par exemple, on peut demander d’avoir les données correspondant aux enregistrements de 5 à 25. Cela permet d’obtenir une pagination sur un résultat de script, ce qui était impossible auparavant

Définir une globale à l’exécution d’une requête

[code language=”php”]
$fm = new FileMaker($db, $host, $user, $pass);
$result = $fm->newFindCommand(‘sample’)
->setGlobal(‘global_field’, date(‘m/d/Y’))
->addFindCriterion(‘test_field’, 1)
->execute();

echo $result->getFetchCount() . " enregistrements trouvés.";
[/code]

Fonctionnalité très pratique, car elle permet désormais de définir une globale au moment de l’exécution d’une requête, ce qui vous permettra par exemple de récupérer, dans vos résultats, des données liées au travers d’une globale.

Conclusion

Comme expliqué au début de l’article, l’API PHP de FileMaker avait bien besoin d’un sacré coup de jeune pour s’adapter à l’évolution des technologies les plus récentes, notamment concernant l’interaction avec les frameworks PHP modernes.

Cette réécriture a nécessité de nombreuses heures de travail et d’innombrables tests. Le résultat est plus qu’encourageant puisque cette nouvelle version est désormais utilisée quotidiennement en production sur plusieurs projets professionnels gérés par l’équipe de 1-more-thing.

Mais, bien qu’elle soit en l’état assez stable et aboutie pour être utilisée en production, cette réécriture n’est cependant pas encore terminée, bien d’autres améliorations sont en cours et d’autres à prévoir. Si vous souhaitez contribuer à son évolution, vous êtes évidemment les bienvenus : Dépot GitHub.

Un grand merci à tous ceux qui ont participé, directement ou indirectement, à la réalisation de ce projet, et un remerciement tout particulier à Matthias Kühne pour toutes ses contributions.

Lors de la sortie de FileMaker 14, nous avions déjà publié un article sur ce sujet, car nous avions un début de solution à l’éternel problème des fins de ligne (LF, CR, CRLF) dans les fichiers exportés par FileMaker.

Mais FileMaker 16 met un terme à cette éternité : le problème est désormais résolu de manière propre.

Voici donc une petite vidéo qui explore la fonction TextEncode

[Version française]

In this blog post, I will share a technique that Laurent Spielmann (@laurent_at_joes) and I developed together and that greatly simplifies imports. It uses ODBC import.

Have you never been bothered by inconsistent database structures between a data source and your own application?

Have you never cursed the SQL developer who uses as a unicity key a concatenation of several columns?

Have you never felt anxiety before renaming a field because it could break an import order?

Have you never lost your temper in front of a progress bar during a sync operation on a ESS table?

If you answered no to all of these, I’m jealous. This article is for the rest of us. 🙂

Some technical background for a start

FileMaker has had a great friend for a long time: ODBC.

ODBC is implemented in 3 very different manners in FileMaker. Let’s avoid confusion:

1. FileMaker can be defined as an ODBC data source. It is not our topic today but it’s interesting because a FileMaker source interrogated via ODBC will act as any other database. An ODBC driver is provided with FileMaker Pro and FileMaker Server.
2. FileMaker can access ODBC data in the context of ESS (External SQL Source). The purpose is here to interact with external data as if they were FileMaker data, through table occurrences, layouts, scripts…). Since FileMaker 9, we used to be able to play with mysql, Oracle and SQL Server. Since the release of FileMaker 15, Postgresql and DB2 have joined the game. Note that on Mac, a third party driver is required (Actual Technologies). Since the release of ESS in FileMaker 9, developers tend to use it for all interactions with SQL sources. And that is a very bad idea. I admit that the fact that you can interact with external data just as if they were FileMaker data is great, but the cost in terms of performance is huge. ESS performance is well below ODBC potential.
3. Finally, and that is often forgotten -and therefore our today topic— the capability to communicate with a SQL source by script.

What script steps are we talking about?

Two script steps allow interaction with ODBC sources:

1. READ: Import records.
2. WRITE: Execute SQL (I’m not talking about the ExecuteSQL calculation function, that can only read (SELECT), but of the Execute SQL script step, for good)

Note that it is not possible, at least to my knowledge, to read data from an external source without writing to a FileMaker table (import). One could expect that Execute SQL would return the result of a SELECT statement to a variable, but it doesn’t.
Tip: Execute SQL can also modify the structure of a database. (CREATE, DROP, ALTER…). Come back to this tip after reading this article. Could give you ideas.

Driver ? DSN ? what’s this?

The main reason why these features are somehow neglected is that they require a DSN (Data Source Name) to be installed at the operating system level, and sometimes, depending on the database, a specific driver.

A DSN is needed for the operating system to give applications access to an ODBC data source. ODBC is a standard that allows different databases to communicate using SQL. (Open DataBase Connectivity).

On the Mac, you have to setup a DSN using ODBC Manager, that used to be installed by default in /Applications/Utilities/ before Apple decided it was too good for you. Fortunately, unlike MagSafe connector and other great hardware and software features removed by Apple, ODBC Manager can still be downloaded here.

While it is true that setting up a DSN on each client machine is complex, it’s a snap to install it once on the server.

As a matter of fact, we’ve been able since FileMaker Server 9 to schedule scripts on server, and since FileMaker 13 to perform script on server from the client.

What’s more, and while Import Records [ ODBC data ] has always been server compatible, Execute SQL has become server compatible only with FileMaker Server 15. Enough to re-think some stuff!

To sum up: you can now set up a DSN only on the server and benefit from it on all clients, including Pro, Go, WebDirect and CWP.

However, the developer (that’s you) will also need to access the SQL sources in order to write scripts (namely to configure import orders). To address this you’ll simply have to set up the same DSN on your computer, paying attention to using exactly the same name. So you will be able to edit your scripts and the server can perform them.

We’re done with the technical setup. Now let’s focus on what’s interesting.

The plot

Here is a short summary of the situation we had to address. We have to import a massive amount of data stored in mysql.
Performance is a key here, and this excludes ESS immediately. By the way, we had really no reason to consider ESS: this technology is good at one thing only: present and manipulate external data as if they were FileMaker data. Nothing else. It’s really NOT designed to import or run synchronization operations.
So we go for ODBC imports, but refinements are to come later.

First challenge: unicity and performance

So here we are with the following script configuration:

As you can see, the Import records script steps is talking to a DSN with a query that we define as a variable for the sake of readability.

But among the numerous imports we have to make, some are of ‘update’ type (the third option checked in the import order dialog)

The problem is that the unicity criteria does not fit in a single column. To decide wether a record matches and must be updated, 3 columns had to be used as matching keys.

FileMaker allows this, but with dramatically poor performance. Since the number of records was huge, this simply wasn’t an option.

Imagine the query:

SELECT a, b, c, d FROM myTable

But although we want to import these 4 columns into 4 FileMaker fields: A, B, C, and D, we must update records if a, b and c are matching A, B, and C.

Let’s define the import order like:

but we know that performance won’t be acceptable.

One way —I’m serious here— would be to ask the SQL developer to update the view and add a column that would concatenate the 3 others. In our situation it would have been a reasonable option, but very often you have simply no control over the source structure.

Let’s see if we couldn’t have mysql do the work for us…

First, let’s create a FileMaker calculation field that will be a unique key on the destination side.

K is a calculated field such as

A & B & C

Now, let’s update the query like:

SELECT CONCAT (a, b, c) AS K, a, b, c, d FROM myTable

Some explanations:

• a 5th column is created on the fly (concatenation of a, b, and c).
• we move before the others (optional, that’s just to show them who’s the boss.)
• it’s renamed K, just because it looks nice (but you’ll see, that will give us ideas. Beauty IS important.)

By selecting the Matching names options, we end up with this:

and that is way faster!

Second challenge: naming

Wait! that’s interesting, isn’t it? OK, we solved the performance issue, but while doing so we really took control over the left side of the import order dialog (source).
And one of the great issues we face with import records in FileMaker is it’s fragility. The only way to maintain an import order, even if you create or remove fields is to choose Matching names, but then you’re exposed to the consequences of renaming.

As we just saw, we can control the name of the left side columns. Those who already used XSLT to import XML data already knew, but it’s worth mentioning.

In the above example, I simplified the column names in a, b, c, d and the field names in A, B, C, D, but as you probably expect the real world names were a bit more complex.

Imagine that the original request would be:

SELECT name_first, name_last, jobTitle, date_of_birth FROM PEOPLE

and that the target field names would be

firstName, surName, occupation, dob

we can write:

SELECT name_first AS firstName, name_last AS surName, jobTitle as occupation, date_of_birth as dob FROM PEOPLE

and with the concatenation:

SELECT CONCAT (name_first, name_last, jobTitle) AS K, name_first AS firstName, name_last AS surName, jobTitle as occupation, date_of_birth as dob FROM PEOPLE

Fantastic! we can now use the Matching names option!

Still we knew that the SQL developer might want to rename some columns, or even release new views to replace the old ones after some weeks (this is a real case, not fantasy)
So we wanted to build a system that would resist a change on the source side. Not that the change would be entirely automated, but we wanted to be able to switch to a new source in minutes, without coding. That’s where our work began.

The nice little trick

Wouldn’t it be nice if each FileMaker table was able to generate it’s own import query?

We saw that the left side of the import order could be managed on the fly. It is therefore up to the right side (the database structure) to contain the information.

One spot seemed nice for this: field comments.

Let’s create a small syntax that will:

• declare the left side column name. We’ll use a tag, “SOURCENAME:” followed by the source column name.
• allow to modify this name easily: we’ll simply have to change the column name that follows the tag.
• to comment out. If // is found before SOURCENAME:, the tag is ignored
• not interfere with other information you’d like to place in the comments. As you can see on the image, you can combine a source name and some other comments.

Then we need to create a custom function. (the code is available in this text file)

It might look a little complex at first glance but:

• a great part of the work is done by 2 other functions written by Agnès Barouh, CustomList and FilterList, that we renamed list.custom and list.filter. As a side note, Agnès now develops the Ti’Sac, that we sincerely recommend (it’s not simple politeness here, it’s a amazingly clever, unique, patented purse). Christmas is coming, so you should definitely take a look here.
• if it wasn’t a bit complex, you’d be disappointed.

In fact, this function code doesn’t matter. If for the above mentioned table we evaluate the following expression:

sql.query.import.map ( "" ; "contacts AS C" )

the empty parameter indicates “current table”. One can also write:

sql.query.import.map ( "people" ; "contacts AS C" )

the result is:

SELECT "C"."CIE" AS "company", "C"."familyname" AS "name" FROM "contacts" AS "C"

which is exactly the query we need to pass to the script step Import records to have consistent source and destination names.

Here is the same image again:

• Field ‘company’ will receive data from column ‘CIE’
• Field ‘excluded’ won’t receive data
• Field ‘inactive’ won’t either
• Field ‘name’ will receive ‘familyname’

And conflicts with SQL reserved words are avoided using quotes.

The second parameter, “contacts AS C”, could have been “contacts”, but the function supports table aliases. This will allow importing from joints in the future (currently not supported by the function)

Finally, this second parameter is optional, so you can inject SQL functions in the query:

sql.query.import.map ( "" ; "" )

returns:

SELECT "CIE" AS "company", "familyname" AS name

So if you need to do more complex things you can:

sql.query.import.map ( "" ; "" ) & ", CONCAT ( column1, column2 ) AS myField FROM contacts"

As you can see, this techniques opens up a lot of possibilities. Whether you’re importing from an external source or from the FileMaker database itself.

If you combine this with the fact that an import script step is able to create a new table, that Execute SQL is able to delete this table (DROP), that you can now duplicate a record set without being limited because a table cannot import to itself, etc, etc… the potential is huge!

Do not hesitate to leave a comment here, and now it’s up to you to explore!

Intro

Dans nos solutions FileMaker, en général du moins, nous ne soucions pas particulièrement de la taille des données textuelles, en revanche, nous accordons un intérêt certain pour la taille des données “multimédia” à intégrer dans les bases de données au sein des rubriques de type conteneur ou même directement placées sur les modèles.

Les fichiers Pdf que nous pouvons générer à partir de FileMaker occupent une place importante dans cette problématique liée à la taille des données, notamment sur les solutions “métier”, où l’envoi et la sauvegarde des documents administratifs, commerciaux, contractuels, légaux, etc., ont une importance capitale.

Aujourd’hui, nous disposons de nombreuses techniques et solutions, plus ou moins efficaces, pour traiter les fichiers Pdf générés par FileMaker afin de réduire leur taille : plugins, lignes de commande, applications tierces et services en ligne. Malheureusement, la plupart de ces solutions sont souvent assez délicates à intégrer dans un flux de travail quand d’autres s’avèrent tout simplement complexes à implémenter dans nos projets.

Dans cet article je vous propose d’étudier ensemble, par des simples tests empiriques, quels sont les éléments de nos modèles qui, à coup sûr, influencent la taille des fichiers Pdf générés par FileMaker et, par conséquent, quelles solutions adopter pour les optimiser au mieux de manière totalement native, sans recourir à une quelconque technologie annexe.

L’étude exposée ici concerne plutôt les documents administratifs et de gestion, tels que les devis, factures, bons de commande, bons de livraisons, notes de frais, contrats, licences, condition générales, etc., c’est-à-dire, tous les documents où le texte occupe une place prépondérante par rapport aux éventuelles images existantes (généralement des logos ou pictos).

Tests et Solutions

Pour commencer, je vous invite à télécharger le fichier « Optimisation-Pdf.fmp12 » qui se trouve à la fin de cet article. Il s’agit tout simplement d’une base FileMaker issue des ses solutions de démarrage (version 14), à savoir, la solution “Facturation”, qui dispose d’un modèle de facture que nous allons utiliser et modifier pour réaliser tous nos tests.

Tout ce que nous avons à faire, donc, c’est de travailler nos modèles d’impression, ou concevoir des modèles spécialement dédiés aux Pdf, de manière à les simplifier et à les alléger de tout ce qui pourrait impacter la taille des Pdf générés. Trois aspects sont particulièrement à considérer (par ordre croissant d’importance) :

1. Les images
2. La composition (la mise en page des modèles)
3. Les textes

1. Les images

Et oui, ça peut paraître bizarre (voire paradoxal), mais les images ce sont les éléments qui, finalement, posent le moins de problèmes lors de la création des fichiers Pdf avec FileMaker.

Ceci tout simplement parce que, hélas, FileMaker ne dispose d’aucune fonctionnalité native pour travailler directement sur les images, aussi bien lorsqu’elles sont intégrées dans des rubriques de type conteneur que lorsqu’elles sont placées sur les modèles.

Même si, selon mes observations, il semblerait que le moteur de fabrication des Pdf utilisé par FileMaker tente d’optimiser les images, les résultats dépendent évidemment de la nature des images déjà présentes, il convient donc de les traiter en amont, avec des logiciels dédiés, afin d’optimiser leurs poids avec différentes manipulations, comme par exemple :

• en les redimensionnant aux dimensions exactes requises sur les modèles ;
• en supprimant les espaces, marges et bords inutiles ;
• en réduisant le nombre de couleurs ;
• en les passant en niveaux de gris si la couleur n’est pas nécessaire ;
• en adoptant les bons formats de fichiers compatibles FileMaker : Jpeg, Png, Gif, etc. ;
• en utilisant les taux de compression qui offrent le meilleur compromis poids/qualité ;
• etc.

Pour illustrer cette optimisation, vous trouverez dans le fichier de test disponible à la fin de l’article, une icône en guise de logo placée dans les modèles d’impression. Le poids du fichier original de cette image, en couleurs, était de pratiquement 3 Ko (2 837 octets), après une optimisation dans un logiciel de traitement d’images, l’icône intégrée (en niveaux de gris) pesait moins de 1 Ko (879 octets).

Au final, ce qu’il faut retenir, c’est qu’une fois les images intégrées dans FileMaker, on ne pourra plus rien faire sur place, de manière native, pour réduire leurs poids respectifs afin d’optimiser nos Pdf, ce travail doit donc être fait en amont.

2. La composition

L’idée est d’optimiser la composition des nos modèles d’impression ou dédiés aux Pdf, avec comme but d’obtenir des mises en pages les plus simples possibles, qui nous permettront d’économiser encore quelques dizaines ou centaines d’octets.

Alors, disons-le tout de suite, ne vous attendez pas à réaliser des gains spectaculaires entre une composition “normale” et une mise en page optimisée, mais aucune économie étant à négliger, autant adopter les bonnes pratiques dès le début de chaque projet.

Évidemment, si vous avez déjà une multitude de modèles déjà réalisés dans vos solutions, la simplification de leur mise en page vous demandera de nombreuses heures de travail pour une optimisation assez minime de vos Pdf au final, je ne vous conseille donc pas de vous lancer dans de telles manipulations si peu rentables.

En revanche, pour tout nouveau projet, vous pouvez suivre les recommendations suivantes (sans ordre particulier d’importance) afin de soigner la mise en page de vos modèles d’impression et ainsi optimiser vos Pdf :

• préférez les rubriques de fusion aux simples rubriques lorsque c’est possible ;
• évitez autant que possible de multiplier les objets, simplifiez vos compositions ;
• évitez également les éléments superposés quand ce n’est pas nécessaire ;
• évitez les effets sur les objets quand ce n’est pas utile : ombres, contours pointillés, bords arrondis, dégradés, transparences, etc.
• tentez de privilégier les attributs de paragraphes pour gérer les alignements et espacements des textes dans les blocs ;
• lorsqu’il faut matérialiser des tableaux avec des colonnes de données, tentez d’utiliser la technique des tabulations pour séparer les données ;
• évitez les couleurs quand ce n’est pas nécessaire, préférez l’utilisation des niveaux de gris pour gérer la mise en valeurs des objets et des textes.

Pour avoir une idée de ce qu’on obtient avec ce type d’optimisation, je vous invite à afficher côte-à-côte, en mode modèle bien-sûr, les modèles “Imprimer/envoyer facturation” et “Pdf-4-Mono-Test” du fichier de test présent à la fin de cet article.

Encore une fois, j’insiste, les gains de poids obtenus avec ces mises en pages simplifiées sont très modestes et ne justifient nullement de reprendre tous vos modèles existants, utilisez plutôt ces techniques pour vos nouvelles réalisations.

3. Les textes

Voilà le chapitre le plus intéressant car c’est en manipulant les textes que nous allons obtenir les optimisations les plus importantes sur nos Pdf.

De nombreux aspects sont à considérer, comme le nombre de polices des caractères utilisés, les choix des ces polices des caractères, la présence des enrichissements typographiques (gras, italique, etc.) et le nombre de caractères différents affichés (ce qui est difficilement maîtrisable). Le principe d’optimisation est très simple (par ordre croissant d’importance) :

– moins il y a de caractères différents affichés,
– moins il y a d’enrichissements typographiques appliqués,
– moins il y a de polices de caractères utilisées et mieux elles sont choisies,
= plus l’optimisation sera importante et donc la taille du Pdf réduite.

Les conseils à suivre sont donc évidents :

• limiter autant que possible la quantité de caractère différents et l’utilisation des caractères hors alphabet classique (pas toujours possible, mais à tenir en compte au besoin) ;
• éviter les enrichissements typographiques quand ils ne sont pas vraiment nécessaires : gras, italique, souligné, petites majuscules, etc., préférez jouer avec la taille des textes ;
• éviter de multiplier les polices des caractères, une seule police de caractères peut souvent suffire à obtenir une mise en page claire et lisible ;
• bien choisir sa police des caractères : suivant la police utilisée, la taille du Pdf peut varier quasiment du simple au triple (imaginez avec plusieurs polices).

Concernant l’impact que peut avoir l’utilisation des caractères différents, voici un simple petit test, que vous pouvez retrouver dans l’archive “Pdf-Caracteres.zip” à la fin de l’article, composé de 5 fichiers Pdf dont voici le détail :

• Fichier “_vide.pdf” : Pdf vide (aucun texte, aucune police de caractères) = 5 Ko (5 110 octets) ;
• Fichier “a.pdf” : juste une lettre “a” avec la police “Arial” = 42 Ko (42 422 octets) ;
• Fichier “aaaaaa_26.pdf” : 26 lettres “a” avec la police “Arial” = 42 Ko (42 454 octets) ;
• Fichier “alphabet_26.pdf” : alphabet de 26 caractères minuscules avec la police “Arial” = 52 Ko (51 586 octets) ;
• Fichier “alphabet_ascii.pdf” : alphabet ASCII de 224 caractères avec la police “Arial” = 119 Ko (118 610 octets) ;

Ce test nous montre clairement que, pour chaque police de caractères utilisée, le nombre de caractères différents présents dans le modèle influence la taille finale des Pdf. Malheureusement, mis à part une bonne information auprès des utilisateurs, il n’y a pas vraiment de technique efficace pour limiter le nombre de caractères différents sans risquer de dénaturer les données.

Dans le fichier FileMaker de tests, vous trouverez, dans la zone de navigation en haut du modèle “Détails facturation”, un petit bouton-popover “PDF” qui vous permettra de générer des fichiers Pdf à partir de différents modèles, tous issus du modèle d’impression original, mais qui ont été modifiés afin de pouvoir visualiser la taille des Pdf produits en changeant un ou plusieurs aspects de cette optimisation des textes.

Deux options possibles :

1. Exemples : permet de générer des Pdf d’exemples, cela produit 7 fichiers Pdf pour illustrer l’impact important qu’ont les polices des caractères et le formatage des textes sur la taille des Pdf ;
2. Polices : permet de générer des Pdf selon une police de caractères choisie, cela produit 3 fichiers Pdf pour comparer leurs tailles respectives avec les Pdf analogues d’une autre police de caractères.

Le choix des polices de caractères de ces tests est volontairement limité à celles qui sont les plus utilisées et compatibles avec les plate-formes Mac et Pc. D’autre part, vous trouverez dans ce panneau popover un petit bouton d’aide “?” vous donnant accès à une description du nommage choisi pour les fichiers Pdf générés et leurs signification.

Pour que vous puissiez avoir une idée de la taille des différents Pdf générés par l’option “Polices”, voici un tableau comparatif qui présente assez bien les polices des caractères les plus légères à privilégier dans vos réalisations :

1. Avec = modèle PDF avec des textes qui ont des enrichissements typographiques (gras ou italique).
2. Sans = modèle PDF avec des textes qui n’ont aucun enrichissement typographiques (gras ou italique).
3. Test = modèle PDF de test avec composition simplifiée et textes sans aucun enrichissement typographiques.

Nous pouvons voir dans ce tableau que la police de caractères “Arial” est la plus “encombrante” dans tous les cas, alors que certaines polices, suivant l’application des formatages ou pas, produisent des Pdf extrêment légers avec des gains très intéressants, il convient donc de bien les choisir dans nos modèles pour une meilleure optimisation de nos Pdf.

Attention tout-de-même, ces valeurs sont rélatives aux polices présentes dans chaque système d’exploitation, dès lors, un modèle réalisé avec la police “Arial”, par exemple, peut produire des Pdf de tailles très différentes d’un ordinateur à un autre, il est donc important d’effectuer des tests lors du développement mais aussi, surtout, chez l’utilisateur final.

Conclusion

Nous avons vu que la taille des Pdf est directement liée aux contenus des nos modèles d’impression et à leur formatage, alors, bien qu’il soit difficile de tout maîtriser, si nous observons les trois préceptes suivants, nous allons pouvoir obtenir nativement des fichiers Pdf de taille très réduite, ce qui n’empêche nullement, au besoin, d’opérer d’autres optimisations avec des technologies annexes :

• Optimiser les images avant de les intégrer dans nos solutions ;
• Simplifier au maximum la mise en page de nos modèles ;
• Utiliser le minimum de polices de caractères et appliquer le minimum de formatages (idéalement : une seule police de caractères et aucun formatage typographique).

Voici le fichier FileMaker de tests à télécharger :  Optimisation-Pdf.fmp12

Voici l’archive avec les tests des caractères :  Pdf-Caracteres.zip

Merci pour votre lecture, toutes remarques, commentaires et questions sont les bienvenues.