Frequently Asked Questions - TeleForm Script Add-Ins

Create a new class library in Visual Studio, or Visual Basic Express

If you don't have a full copy of Visual Studio available, a free "Express" version is available here.

We recommend using VB.NET as there is more historical documentation based around VB (in its VBA and BasicScript forms), however the steps in this FAQ will still apply in exactly the same manner if C# is chosen.

Firstly, create a new Class Library project. In our examples, we'll use the project name "VBExample"

Once this has been created, choose Properties from the Project menu. Then on the Application side-tab, ensure the box Make assembly COM-visible is ticked:

Next...

Adding a reference to the TeleForm Scripting API Library

Next, we need to add the TeleForm Scripting API reference to the project. To do this, click on the References side-tab on the Properties window.

Click the Add... button, and from the COM tab, find and select the TeleForm 10.5 Scripting API Library. Note that if your version of TeleForm is greater than 10.5, you will have newer versions of the scripting API library to choose.

If you don't have the TeleForm Scripting API Library available, you must install a workstation copy of TeleForm on your PC.

Once, selected, click OK.

Previous... | Next...

Add the necessary interfaces

Now we should be ready to start adding the bare bones of a script to your class library. Currently, you will only have one class in your project, "Class1.vb". We're going to add another which will be used to contain your scripts.

Right-click on your project in the Solution Explorer and select Add... Class Library.

In this example, we're going to call it VBExampleAddIn.

Now, in the new script that opens up, type the following:

Implements tfscript.ITFScriptAddIn

Once this line is added, a whole set of functions and subroutines will be automatically added to the class, based on the ITFScriptAddIn interface.

Additional interfaces can be added. One highly useful one to add at this stage is the ITFFormEntryPoints, which allows access to the various form processing stages.

Implements tfscript.ITFFormEntryPoints

At this point, your single class now contains many of the functions and subroutines that can be used to run your own code. Some choose to have the FormEntryPoint functions in a separate class to the AddIn functions, but for simplicity in this example, we've placed them all in the same class.

The AddIn function FormEntryPoints is called by TeleForm to discover if you have any custom classes to handle form entry points. In the next step, we'll start to add our own script, so in order for TeleForm to be aware of this, add the following line just beneath the Implements lines:

Dim Form As tfscript.ITfForm

Then finally add the following lines to the FormEntryPoints function so it reads as follows:

Public Function FormEntryPoints(ByVal sPath As String, ByVal pForm As tfscript.ITfForm) As _
tfscript.ITFFormEntryPoints Implements tfscript.ITFScriptAddIn.FormEntryPoints
Dim DefaultEntryPoints As New VBExampleAddIn
Form = pForm
Return DefaultEntryPoints
End Function

Previous... | Next...

Adding your own custom business rule code

We're now ready to add custom code to apply your business rules to the Add In. The following script is added in the FormEntry subroutine. It simply takes 3 fields: Day (values 1-31), Month ("JAN" to "DEC") and Year (as a 4-digit year) and concatenates them together into a proper date in the format DD/MM/YYYY to be placed into a field called simply Date.

Public Sub FormEntry(ByVal nContext As tfscript.TFFormEntryContext, ByVal nSubContext As _
tfscript.TFFormEntrySubContext) Implements tfscript.ITFFormEntryPoints.FormEntry
If nContext = tfscript.TFFormEntryContext.TFFormEntry_PreExport Then 'Runs before export
Try 'Using Try in case Date, Day, Month or Year fields do not exist on form
Dim ExportDate As tfscript.ITfField
ExportDate = Form.Fields("Date") 'The ITfField object is read/write
ExportDate.Text = Format(Val(Form.Fields("Day").Text), "00") & "/"
'Line above sets Date field to the day (with leading 0 if required) followed by / (e.g. 23/)
Select Case Form.Fields("Month").Text
'Line above, depending on the Month value, appends the numerical form (e.g. 23/04/)
Case "JAN"
ExportDate.Text = ExportDate.Text & "01/"
Case "FEB"
ExportDate.Text = ExportDate.Text & "02/"
Case "MAR"
ExportDate.Text = ExportDate.Text & "03/"
Case "APR"
ExportDate.Text = ExportDate.Text & "04/"
Case "MAY"
ExportDate.Text = ExportDate.Text & "05/"
Case "JUN"
ExportDate.Text = ExportDate.Text & "06/"
Case "JUL"
ExportDate.Text = ExportDate.Text & "07/"
Case "AUG"
ExportDate.Text = ExportDate.Text & "08/"
Case "SEP"
ExportDate.Text = ExportDate.Text & "09/"
Case "OCT"
ExportDate.Text = ExportDate.Text & "10/"
Case "NOV"
ExportDate.Text = ExportDate.Text & "11/"
Case "DEC"
ExportDate.Text = ExportDate.Text & "12/"
End Select
ExportDate.Text = ExportDate.Text & Form.Fields("Year").Text
'Line above appends the year (e.g. 23/04/2012)
Catch ex As Exception
MsgBox("Error:" & Err.Description) 'Display a message if an error occurs
Exit Sub
End Try
End If
End Sub

Previous... | Next...

Building the class library, adding a COM GUID

In order for a TeleForm application to be able to communicate with the new VB.NET script (a class library), a GUID must be associated with it so that it is visible in the COM. Visual Studio offers a tool to generate a new GUID, however there are websites which also offer the same service (for example http://www.guidgenerator.com/).

A GUID (globally unique identifier) is a 128-bit integer number, with so many permutations that it is considered highly unlikely to generate duplicates. This GUID is then used from now on to associate with our new library (DLL).

To instruct Visual Studio to use a new GUID, write the following at the top in front of the Class definition, so the whole definition reads:

<Guid("B5F4EE9E-9064-4B6D-A672-329C38853B0B"), ClassInterface(ClassInterfaceType.None), ProgId("VBExample.VBExampleAddIn")> _  
Public Class VBExampleAddIn

Your own generated GUID should appear in the quotes.

You are now ready to Save and Build your Add In. You can do this by right-clicking on the VBExample project in the Solution Explorer and by selecting Build VBExample.

The resulting DLL will be visible in your project directory, for example:

C:\Users\<yourlogin>\Documents\Visual Studio 2010\Projects\VBExample\VBExample\bin\Release

This file location will be used in the next step. 

Previous... | Next...

Configuring TeleForm Scripting API to use your new class library

Now the initial work has been completed in creating a new Add In, TeleForm needs to be made aware of it so that it can load up the required DLL when needed. To do this, open up any TeleForm module and from the Utility menu, select Configuration.

In the configuration screen that appears, choose the Global System tab, and then the Scripting API sub-tab. A set of already-installed Add-Ins will appear in a list. Click New to configure the VBExample Add-In.

The following screen should appear:

The following settings have been adjusted:

• Component Installation: Copy and register. On any workstations that don't currently have the new VBExample.dll registered, it will be automatically copied and registered using the Registration Command (configured below).
• Component: Click the Load button to browse to the VBExample project directory (from the last step).
• Name: This has been manually set to VBExample.
• GUID: The GUID from the last step has been pasted manually here, with curly brackets before and after.
• Registration command: This command will register the DLL with the current PC's COM. Note that the path of Regasm is dependant on the version of .NET that you compiled the project in. Note, in build 10555 of TeleForm 10.5.2 upwards, the path of the RegAsm command can be simplified using the notation <.NET 4.0>\regasm
• Finally, the Enabled option has been ticked.

Clicking on OK will immediately check the setting, presenting an error message if something is wrong.

From this point on, any workstation that hasn't previously been exposed to the Add-In will have it automatically copied and registered locally. Updated versions of your Add-In DLL must be placed in
<TeleForm Mapped Drive>:\TeleForm\Scripts\AddIns for them to be automatically distributed across workstations.

Previous... | Next...

Final configuration notes

Adding a new Add-In using the instructions within this FAQ, when enabled, will be run for every TeleForm application, for every form and every batch. Some business rules may be required just for individual forms rather than for all. In which case, it may be necessary to check the FormID value before applying business rule logic.

Further documentation on all API objects, methods and properties are found in:

<TeleForm Mapped Drive>:\TeleForm\Doc\SDK\COM

Previous...