Hur skriver jag VBScript-kod för M-Files-syften?

Använd länkarna ovan för instruktioner om att lägga till VBScript-kod i varje instans.

Du kan komma åt och hantera objekt i dokumentvalvet genom att använda M-Files-API och VBScript i ovan nämnda omständigheter.

Grundläggande om VBScript

Nedan beskrivs några av grunderna i VBScript så att du kan komma igång. Tänk på att vi bara skrapar på ytan här. Användbara resurser innehåller mer instruktioner. Om scripting är nytt för dig och du inte känner till koncept såsom variabler och funktioner kan det vara bra att först läsa en nybörjarguide till scripting, till exempel Learn Beginning Scripting.

Uttryck

I VBScript, avslutar en radbrytning ett uttryck och det finns därmed inget eget tecken för att avsluta uttryck. Exemplet nedan innehåller två uttryck:
Dim szPropertyName
szPropertyName = PropertyDef.Name
Om du vill dela upp ett uttryck i separata rader kan du använda understreckstecknet (_) för att visa att ett uttryck fortsätter på nästa rad:
Err.Raise MFScriptCancel, _
    "The document vault already contains an object with the same title. Please choose another title."

Kommentera

Kommentera alltid vad du gör i din kod så att andra som läser den förstår vad som pågår. Du kan lägga till en kommentar i din kod genom att använda tecknet ':
' Get the title of the object.
Dim szCurrentTitle
szCurrentTitle = oCurrentTitleProp.GetValueAsUnlocalizedText
Det kan vara bra att lägga till en kommentar ovanför alla kodrader som du misstänker inte kommer att vara omedelbart tydliga för läsaren.

Variabler

Variabler deklareras med nyckelordet Dim:
Dim szCurrentTitleProp
Värden tilldelas till variabler med hjälp av likamed-tecknet (=). Du bör alltid deklarera dina variabler innan du tilldelar dem nya värden:
Dim szCurrentTitleProp
szCurrentTitleProp = PropertyValues.SearchForProperty( iTitleProperty ).GetValueAsUnlocalizedText
Du kan använda uttrycket Option Explicit för att tvångsanvända explicit deklaration för alla variabler. Om du försöker använda en odeklarerad variabel när Option Explicit är aktiverat i ditt script kommer ditt script inte att fungera. Exempelvis skulle följande script inte fungera eftersom variabeln szValue inte har deklarerats innan den tilldelas ett värde:
Option Explicit
szValue = PropertyValue.GetValueAsUnlocalizedText
När du använder script i M-Files har du ett antal fördefinierade variabler till ditt förfogande. Variabeln PropertyValue kan till exempel användas för att hämta en egenskaps värde. Tillgängliga VBScript-variabler innehåller den fullständiga listan över fördefinierade variabler.
Notera: Vi rekommenderar att du använder så kallad ungersk notation när du namnger variabler. På så sätt kan alla som läser din kod tydligt förstå datatypen för det värde som lagras i variabeln. Du kan till exempel använda följande notation:
  • "sz" för strängar
  • "o" för objekt
  • "i" för heltal
  • "b" för Boolesk
  • "f" för flytande punktnummer
  • "d" för datum

Konstanter

Du kan använda konstanter för att lagra värden som måste vara konstanta scriptet igenom:
Const iMaxNumberOfItems = 50
Observera att du måste tilldela ett literalvärde till en konstant. Du kan inte använda en variabel, en annan konstant eller en funktion för att inleda en konstant.

Objekt

Objekt tilldelas till variabler med hjälp av Set-uttrycket. Du kan skapa en ny instans av ett M-Files-API-objekt och tilldela det till en variabel på följande sätt:
Dim oTitleSearch
Set oTitleSearch = CreateObject( "MFilesAPI.SearchCondition" )
Objekt är komponenter som har egna egenskaper och metoder. Metoder är funktioner som hör till ett specifikt objekt och som kan användas i objektets kontext. Egenskaper, å andra sidan, används för att visa eller ställa in värden för ett objekt. Du kommer åt egenskaper och metoder för ett objekt med hjälp av punktnotering:
oTitleSearch.Set oTitleExpression, MFConditionTypeEqual, oTitleTypedValue
metodargument, till exempel oTitleExpression, MFConditionTypeEqual och oTitleTypedValue i exemplet ovan listas efter metoden och separeras med ett komma. Parametrar passeras antingen efter värde eller efter referens. Om en metod tar en parameter efter värde kopierar metoden det värde som passeras som argument och därmed förändras inte det ursprungliga värdet. Om en metod däremot tar en parameter efter referens kommer alla förändringar som metoden kan skapa i argumentet även att påverka den ursprungliga referensen. Värdet Nothing bör användas om standardvärdet för parametern ska användas.

När du använder script i M-Files utnyttjar du de objekt som finns tillgängliga i VBScript och, ännu viktigare, de objekt som finns tillgängliga i M-Files-API. M-Files API Documentation innehåller fullständig information.

Sammanlänkade strängar

Du kan sammanlänka två eller flera strängar till en genom att använda &-operatorn:
' 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
I exemplet ovan är förslagstiteln, som lagras i variabeln szName, resultatet av att följande strängar sammanlänkas:
  • strängkonstant Proposal #
  • förslagsnumret, lagras i szNumber-variabeln
  • en annan strängkonstant /
  • kundnamnet, lagras i szCustomer-variabeln
Förslagstiteln skulle därmed kunna vara till exempel Förslag nr5577/ESTT.
Du kan lägga till en radbrytning i strängen genom att sammanlänka VbCrLF-konstanten med dina strängar:
Err.Raise MFScriptCancel, _
    "The document vault already contains an object with the same title." & VbCrLF & "Please choose another title."

Visa fel

Om du till exempel behöver verifiera ett egenskapsvärde med VBScript behöver du se till att användaren får ett felmeddelande om det värde som användaren har angett är ogiltigt. Du kan visa ett fel i VBScript med hjälp av Raise-metoden för Err-objektet:
Err.Raise MFScriptCancel, "The property """ & szPropertyName & """ must have a value of at least 10 characters."
metoden tar felnumret och -beskrivningen som parametrar. Av M-Files-scriptskäl används MFScriptCancel-variabeln eftersom det lagrar M-Files-felnumret.

If-uttryck

If-uttryck används för att utföra en grupp uttryck om det villkor som anges i If-uttrycket bedöms vara sant:
If Len( szValue ) < 10 Then

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

End If
If-blocket måste avslutas med ett End If-uttryck. Alla uttryck mellan If och End If utförs om det villkor som anges mellan If och Then bedöms vara sant. Du kan använda And-operatorn för att ange flera villkor som alla måste vara sanna för att if-blocket ska utföras, eller Or-operatorn för att ange flera operatorer. En av dessa måste vara sann för att if-blocken ska utföras. Du kan använda följande jämförelseoperatorer för att ange villkoren:
  • == kontrollerar om värdet av två operatorer är lika eller inte. Om de är det är villkoret sant.
  • <> kontrollerar om värdet av två operatorer är lika eller inte. Om de inte är det är villkoret sant.
  • > kontrollerar om värdet för den vänstra operatorn är större än värdet för den högra operatorn. Om det är det är villkoret sant.
  • < kontrollerar om värdet för den vänstra operatorn är mindre än värdet för den högra operatorn. Om det är det är villkoret sant.
  • >= kontrollerar om värdet för den vänstra operatorn är större än eller lika med värdet för den högra operatorn. Om det är det är villkoret sant.
  • <= kontrollerar om värdet för den vänstra operatorn är mindre än eller lika med värdet för den högra operatorn. Om det är det är villkoret sant.
Du kan även stapla ett If-uttryck inuti ett annat If eller, ett Else-uttryck, eller använda ElseIf-uttrycket för att skapa en djupare grenlogik i ditt script.

Funktioner och underrutiner

Du kan använda en underrutin för att definiera ett kodavsnitt att använda flera gånger enligt referens i din kod:
Sub CloseFile()
    oMyFile.Close
    Set oMyFile = Nothing
End Sub
Eller så kan du definiera en funktion som flera gånger använder ett kodavsnitt som returnerar ett värde av något slag:
Function IsOdd( iValue )
    If iValue MOD 2 = 0 Then ' Even value.
        IsOdd = False
    Else ' Odd value.
        IsOdd = True
    End If
End Function
Om du vill anropa en underrutin eller funktion i ditt script ska du bara referera till det med namn:
Closefile()
IsOdd( 5 )

Användbara resurser

De bästa informationskällorna i fråga om script inom M-Files är följande:

M-Files-API-dokumentationen är en omfattande referens till de M-Files-API-objekt, -metoder, -gränssnitt, -egenskaper och -numreringar som du kan utnyttja i VBScript-kod. Den sistnämnda resursen å andra sidan visar och förklarar alla variabler med redan tilldelade värden som du kan använda i din VBScript-kod.

Utöver dessa två resurser kan du ha nytta av följande externa webbplatser:

Exempel

Exemplet nedan är ett script som kan användas för att validera en egenskap när användaren försöker spara metadataändringar i metadatakortet. Scriptet ser till att det angivna egenskapsvärdet måste vara minst 10 tecken långt. Låt oss titta närmare på scriptet:
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
Först deklareras variablerna szPropertyName och szValue. Därefter lagras namnet på egenskapen och dess värde som vi validerar i de variabler som vi precis har deklarerat. Vi använder GetValueAsUnlocalizedText-metoden (se M-Files-API-dokumentation för mer information) för att hämta egenskapsvärdet som icke lokaliserad text.

Vårt villkor för att validera egenskapsvärdet är att värdet måste bestå av minst 10 tecken. Vi utvärderar det villkoret i ett If-uttryck. I villkoret för If-uttrycket har vi definierat att egenskapen måste vara mindre än 10 tecken för att uttrycket inuti If-uttrycket ska utföras. Om egenskapsvärdet är 10 tecken eller mer utförs inte If-kodblocket och scriptutförandet avslutas.

I if-blocket skickar vi ett felmeddelande till användaren där vi anger att det egenskapsvärde som användaren har angett måste bestå av minst 10 tecken. Vi instruerar därmed användaren att lägga till ett längre värde. När felmeddelandet har visats visas metadatakortet igen, vilket gör att användaren kan modifiera det ogiltiga egenskapsvärdet.

Fullständiga instruktioner om att validera egenskapsvärden med VBScript finns i Verifiera egenskapsvärden automatiskt.