Comment écrire le code VBScript code pour M‑Files ?

Cliquez sur les liens ci-dessus pour obtenir des instructions sur l’ajout du code VBScript dans chaque cas.

Vous pouvez accéder aux objets contenus dans le coffre et les gérer au moyen d’API et de VBScript de M‑Files dans les circonstances susmentionnées.

Principes de base VBScript

Vous trouverez ci-dessous quelques rudiments de VBScript pour vous permettre de démarrer. Veuillez noter que nous ne faisons ici qu’effleurer le sujet. Consultez Ressources utiles pour de plus amples instructions. Si vous débutez dans le scriptage et n’êtes pas familiarisé avec les concepts tels que les variables et les fonctions, il peut être utile de lire tout d’abord un guide de scriptage pour débutant comme Learn Beginning Scripting.

Expressions

Dans VBScript, un saut de ligne termine une expression et il n’y a, par conséquent, pas de caractère de terminaison pour mettre fin aux expressions. L’exemple ci-dessous comporte deux expressions :
Dim szPropertyName
szPropertyName = PropertyDef.Name
Si vous souhaitez diviser une expression en plusieurs lignes, vous pouvez utiliser le tiret bas (_) pour indiquer qu’une expression se poursuit à la ligne suivante :
Err.Raise MFScriptCancel, _
    "The document vault already contains an object with the same title. Please choose another title."

Commentaires

Commentez toujours ce que vous êtes en train de faire dans votre code de façon à ce que d’autres personnes lisant votre code sachent ce qui se passe. Vous pouvez ajouter un commentaire dans votre code à l’aide du caractère ' :
' Get the title of the object.
Dim szCurrentTitle
szCurrentTitle = oCurrentTitleProp.GetValueAsUnlocalizedText
Il s’agit d’une bonne approche pour ajouter un commentaire au-dessus de toute ligne d’un code qui ne vous semble pas être instinctivement évident pour le lecteur.

Variables

Les variables sont déclarées à l’aide du mot clé Dim :
Dim szCurrentTitleProp
Les valeurs sont assignées aux variables à l’aide du signe égal (=). Vous devriez toujours déclarer vos variables avant de leur assigner de nouvelles valeurs :
Dim szCurrentTitleProp
szCurrentTitleProp = PropertyValues.SearchForProperty( iTitleProperty ).GetValueAsUnlocalizedText
Vous pouvez utiliser l’expression Option Explicit pour forcer une déclaration explicite de toutes les variables. Si vous essayez d’utiliser une variable non déclarée lorsque Option Explicit est activé dans votre script, votre script ne fonctionnera pas. Par exemple, le script suivant ne fonctionnerait pas puisque la variable szValue n’a pas été déclarée avant de lui assigner une valeur :
Option Explicit
szValue = PropertyValue.GetValueAsUnlocalizedText
Si vous effectuez le scriptage dans M‑Files, vous avez un nombre de variables prédéfinies à votre disposition. La variable PropertyValue peut, par exemple, être utilisée pour récupérer la valeur d’une propriété. Consultez Variables VBScript disponibles pour obtenir la liste complète des variables prédéfinies.
Remarque : Nous vous recommandons d’utiliser la « notation hongroise » pour le nommage des variables. Ainsi, vous (ou toute personne lisant votre code) avez une vision claire du type de donnée de la valeur enregistrée dans la variable. Vous pouvez, par exemple, utiliser la notation suivante :
  • "sz" pour les textes
  • "o" pour les objets
  • "i" pour les nombres entiers
  • "b" pour les booléens
  • "f" pour les nombres flottants
  • "d" pour les dates

Constantes

Vous pouvez utiliser des constantes pour enregistrer des valeurs qui doivent rester constantes tout au long du script :
Const iMaxNumberOfItems = 50
Veuillez noter que vous devez assigner une valeur littérale à une constante. Vous ne pouvez pas utiliser de variable, une autre constante ou une fonction pour initialiser une constante.

Objets

Les objets sont assignés aux variables à l’aide de l’expression Set. Vous pouvez créer une nouvelle instance d’un objet API de M‑Files et l’assigner à une variable de la façon suivante :
Dim oTitleSearch
Set oTitleSearch = CreateObject( "MFilesAPI.SearchCondition" )
Les objets sont des composants qui ont leurs propres propriétés et méthodes. Les méthodes sont des fonctions qui appartiennent à un objet spécifique et qui peuvent être utilisées dans le contexte de l’objet. Les propriétés sont, quant à elles, utilisées pour afficher ou configurer les valeurs d’un objet. Vous pouvez accéder aux propriétés et méthodes d’un objet à l’aide d’une notation par points :
oTitleSearch.Set oTitleExpression, MFConditionTypeEqual, oTitleTypedValue
Les arguments d’une méthode comme oTitleExpression, MFConditionTypeEqual et oTitleTypedValue dans l’exemple ci-dessus sont listés après la méthode et sont séparés par une virgule. Les paramètres sont transmis soit par une valeur soit par une référence. Si une méthode prend un paramètre comme valeur, la méthode copie la valeur transmise en tant qu’argument et la valeur originale n’est de la sorte pas modifiée. Si, par contre, une méthode prend un paramètre comme référence, tout changement provoqué par la méthode sur l’argument a également un impact sur la référence originale. La valeur Nothing doit être utilisée si la valeur par défaut du paramètre est utilisée.

Lors du scriptage dans M‑Files, vous tirerez profit des objets disponibles dans VBScript et, plus important encore, des objets disponibles dans l’API de M‑Files. Reportez-vous à la documentation M‑Files API pour obtenir des informations complètes.

Concaténer des textes

Vous pouvez concaténer deux ou plusieurs textes en un à l’aide de l’opérateur & :
' Get proposal number.
Dim szNumber
szNumber = PropertyValues.SearchForProperty( 1156 ).TypedValue.DisplayValue

' Get customer.
Dim szCustomer
szCustomer = PropertyValues.SearchForProperty( 1288 ).TypedValue.DisplayValue

' Create proposal title.
Dim szName
szName = "Proposal #" & szNumber & " / " & szCustomer
Dans l’exemple ci-dessus, le titre de proposition, enregistré dans la variable szName, est le résultat de la concaténation des textes suivants :
  • texte littéral Proposal #
  • le numéro de proposition, enregistré dans la variable szNumber
  • un autre texte littéral /
  • le nom du client, enregistré dans la variable szCustomer
Le titre de proposition en découlant pourrait ainsi être, par exemple, Proposition #5577 / ESTT.
Vous pouvez ajouter un saut de ligne à votre texte en concaténant la constante VbCrLF avec vos textes :
Err.Raise MFScriptCancel, _
    "The document vault already contains an object with the same title." & VbCrLF & "Please choose another title."

Génération d’erreurs

Si vous deviez valider une valeur de propriété avec VBSScript, il faudrait afficher un message d’erreur pour l’utilisateur au cas où la valeur saisie par l’utilisateur ne serait pas valide. Vous pouvez générer une erreur dans VBScript à l’aide de la méthode Raise de l’objet Err :
Err.Raise MFScriptCancel, "The property """ & szPropertyName & """ must have a value of at least 10 characters."
La méthode prend le numéro et la description de l’erreur pour paramètres. À des fins de scriptage M‑Files, la variable MFScriptCancel est utilisée puisqu’elle enregistre le numéro de l’erreur de M‑Files.

Expressions If

Les expressions If sont utilisées pour exécuter un groupe d’expressions si la condition indiquée dans l’expression If s’avère vraie :
If Len( szValue ) < 10 Then

    Err.Raise MFScriptCancel, "The property """ & szPropertyName & """ must have a value of at least 10 characters."

End If
Le bloc If doit terminer avec une expression End If. Toutes les expressions comprises entre If et End If sont exécutées si la condition indiquée entre If et Then s’avère vraie. Vous pouvez utiliser l’opérateur And pour indiquer plusieurs conditions qui doivent toutes être vraies pour que le bloc If soit exécuté ou bien l’opérateur Or pour indiquer plusieurs opérateurs, dont l’un doit être vrai pour que le bloc if soit exécuté. Vous pouvez utiliser les opérateurs de comparaison suivants pour définir la condition :
  • == vérifie si la valeur de deux opérandes est identique ou non ; si c’est le cas, la condition est vraie.
  • <> vérifie si la valeur de deux opérandes est identique ou non ; si ce n’est pas le cas, la condition est vraie.
  • > vérifie si la valeur de l’opérande de gauche est supérieure à la valeur de l’opérande de droite ; si c’est le cas, la condition est vraie.
  • < vérifie si la valeur de l’opérande de gauche est inférieure à la valeur de l’opérande de droite ; si c’est le cas, la condition est vraie.
  • >= vérifie si la valeur de l’opérande de gauche est supérieure ou égale à la valeur de l’opérande de droite ; si c’est le cas, la condition est vraie.
  • <= vérifie si la valeur de l’opérande de gauche est inférieure ou égale à la valeur de l’opérande de droite ; si c’est le cas, la condition est vraie.
Vous pouvez également imbriquer une expression If à l’intérieur d’une autre expression If ou d’une expression Else par exemple, ou bien vous pouvez utiliser une expression ElseIf pour créer une logique arborescente plus poussée dans votre script.

Fonctions et sous-programmes

Vous pouvez utiliser un sous-programme pour définir une section de code à utiliser plusieurs fois comme référence dans votre code :
Sub CloseFile()
    oMyFile.Close
    Set oMyFile = Nothing
End Sub
Vous pouvez sinon définir une fonction pour utiliser plusieurs fois une section de code qui renvoie une valeur d’un certain type :
Function IsOdd( iValue )
    If iValue MOD 2 = 0 Then ' Even value.
        IsOdd = False
    Else ' Odd value.
        IsOdd = True
    End If
End Function
Pour faire appel à un sous-programme ou à une fonction dans votre script, il vous suffit de vous y référer par son nom :
Closefile()
IsOdd( 5 )

Ressources utiles

Vos sources d’information les plus utiles sur le scriptage dans M‑Files sont les suivantes :

La documentation API de M‑Files est une référence exhaustive aux objets API, méthodes, interfaces, propriétés et énumérations de M‑Files dont vous pouvez tirer profit au sein du code VBScript. La dernière ressource, quant à elle, liste et explique toutes les variables avec les valeurs préassignées que vous pouvez facilement utiliser dans votre code VBScript.

En sus des deux ressources susmentionnées, les sites externes suivants peuvent vous être utiles :

Exemple

L’exemple ci-dessous est un script qui peut servir à valider une propriété si l’utilisateur essaie d’enregistrer des modifications concernant les métadonnées sur la fiche de métadonnées. Le script garantit que la valeur de propriété saisie doit avoir au moins 10 caractères. Regardons le script de plus près :
Option Explicit

Dim szPropertyName, szValue

szPropertyName = PropertyDef.Name

szValue = PropertyValue.GetValueAsUnlocalizedText

If Len( szValue ) < 10 Then

    Err.Raise MFScriptCancel, "The property """ & szPropertyName & """ must have a value of at least 10 characters."

End If
Tout d’abord, les variables szPropertyName et szValue sont déclarées. Ensuite, le nom de la propriété et la valeur correspondante que nous validons sont enregistrés dans les variables que nous venons de déclarer. Nous utilisons la méthode GetValueAsUnlocalizedText (reportez-vous à la documentation M‑Files API pour plus d'informations) pour obtenir la valeur de propriété en tant que texte non localisé.

Notre condition pour valider la valeur de la propriété : la valeur doit avoir au moins 10 caractères. Nous évaluons cette condition dans une expression If. Nous avons défini dans la condition de l’expression If que la longueur de la propriété doit être inférieure à 10 caractères pour que l’expression à l’intérieur de l’expression If puisse être exécutée. Si la valeur de la propriété a 10 caractères ou plus, le bloc du code If n’est pas exécuté et l’exécution du script est terminée.

Dans le bloc If, nous envoyons un message d’erreur à l’utilisateur dans lequel nous indiquons que la valeur de la propriété saisie par l’utilisateur doit avoir au moins 10 caractères ; on enjoint de la sorte à l’utilisateur d’ajouter une valeur plus longue. Une fois le message d’erreur affiché, la fiche de métadonnées s’affiche de nouveau, ce qui permet à l’utilisateur de modifier la valeur de la propriété non valide.

Pour obtenir des instructions complètes sur la validation des valeurs de propriété avec VBScript, consultez Validation automatique des valeurs de propriété.