WD2000: How to Automatically Load or Distribute a VBA Project (292037)

MORE INFORMATION

Microsoft provides programming examples for illustration only, without warranty either expressed or implied. This includes, but is not limited to, the implied warranties of merchantability or fitness for a particular purpose. This article assumes that you are familiar with the programming language that is being demonstrated and with the tools that are used to create and to debug procedures. Microsoft support engineers can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific requirements.
For more information about how to use the sample code in this article, click the article number below to view the article in the Microsoft Knowledge Base:

Copy the Project to the Startup Folder

When you place a template (*.dot) or Word add-in library (*.wll) in the Word Startup path, Word loads the macros in the file automatically on startup.

Using the Startup path for distribution therefore reduces administration considerably by allowing you to distribute or update a VBA project with a simple file copy. Many organizations already use logon scripts during network logon, making this process as easy as adding a COPY command to a network logon script.

The following are the default locations for the Word Startup folder: NOTE: The Word Startup path is customizable and may be different from what is listed in this article. If you automate distribution of your VBA project, be sure to verify the Startup path before you copy the file.

For additional information about returning the Startup folder location from an external solution, click the article number below to view the article in the Microsoft Knowledge Base: There is also a Startup folder in the directory that contains the Microsoft Office program files. Word checks this folder during startup, in addition to the earlier-referenced locations. Word then loads any templates or add-in libraries that it finds there. By default, this folder is in the following location: An advantage of using this Startup folder is that the path often is the same, regardless of the user name or the version of Windows installed.

A disadvantage is that files placed in this folder affect all users of a particular workstation, not just the individual user.

Modify the Startup Path

Alternately, you can change the Startup path in Word to a shared network location, and then copy your VBA project only to this network share. This may be preferable to copying the file to each computer on a network.

To change the Word Startup setting manually, click Options on the Tools menu, and then click the File Locations tab.

You can also modify this setting with VBA. The following example changes the Startup path in Word to a shared network location. You can also use a mapped network drive instead of a UNC path: To reset the startup path to its default, set the startup path equal to nothing (""), as in the following:

Import and Export VBComponents

If you prefer to import the VBA component into the global template (or any other template), instead of using the Startup folder for distribution, you can use the VBProjects collection to import a module or userform from a Visual Basic module file (*.bas) or Visual Basic userform file (*.frm), respectively.

To create a BAS or FRM file from your VBA project, right-click a userform or module in the Project Explorer window (to see this window, press CTRL+R while in the Visual Basic Editor), and then click Export File.

You can also export a module or userform with a VBA command. The following is an example argument using the VBComponents.Export method:

   VBE.VBProjects("MyTemplateProject").VBComponents("MyModule").Export _
      FileName:="C:\My Documents\MyModule.bas"
				

The following example macro imports a BAS file named "AddMeModule.bas" from the My Documents folder into the Normal template, and then runs a macro (presumably a macro in the imported module) named "AddMeMacro":

Sub NormalImport()

   'Import the BAS file into Normal. 
   NormalTemplate.VBProject.VBComponents.Import _
      FileName:="C:\My Documents\AddMeModule.bas"

   'Run the named macro.
   Application.Run "AddMeMacro"

End Sub
				

In addition to importing components into the Normal template, you can import VBA components into any template that is open for editing in Word, as in the following example argument:

   VBE.VBProjects("MyTemplate").VBComponents.Import _
      FileName:="C:\My Documents\AddMeModule.bas"
				

Reference a VBProject

To avoid file size increases and the overhead of exporting and importing individual modules and userforms, you can choose instead to reference a VBA project. This allows you to access all of the routines, functions, and userforms of a project without actually opening the file or adding large amounts of code to the Normal template or any other template project.

NOTE: If you attempt to add a reference to a project that is already referenced in the current project, you receive the following error message: To prevent this error, you must check for the existence of a reference before you attempt to add it, or use an error handler.

The following example checks for a project reference called "RefProj" and uses the AddFromFile method to add this reference only if it is not referenced already:

Sub RefFromFile()

   Dim RefExists As Boolean

   'Return each reference in Normal.dot.
   For Each Reference In NormalTemplate.VBProject.References

      'Check the name of the reference.
      If Reference.Name = "RefProj" Then

         'Notify if the reference exists.
         MsgBox "Reference already exists"

         'Set the RefExists Boolean to True.
         RefExists = True
      End If

   Next

   'Add the reference if it does not exist.
   If RefExists = False Then
      NormalTemplate.VBProject.References.AddFromFile _
         FileName:="C:\My Documents\RefMe.dot"

      'Notify that the reference was added.
      MsgBox "Reference has been added"
   End If

End Sub
				

As in the NormalImport example (see the "Import and Export VBComponents" section of this article), you can run a macro from the referenced project by using the Word program's Run method.

Alternately, you can call a sub, function, or userform directly by preceding its name with the project name and the container name, as in the following examples:

   RefProj.UserForm1.Show
				

   RefProj.Module1.MacroName
				

Keep in mind that you cannot call a sub, function, or userform directly within the same routine that is used to add the reference to it, because you will receive the following error message: This is because the project you are calling is not available until after you run the code to add the reference. To work around this limitation, add the reference in one routine, and then call a separate routine to actually run the macro or display the userform.

For more information about the VBProject collection, in the Visual Basic Editor, click Microsoft Visual Basic Help on the Help menu, type VBProject property in the Office Assistant or the Answer Wizard, and then click Search to view the topic.

Use OrganizerCopy

Another way to automate copying modules and userforms between files is to use the OrganizerCopy method. This method performs the same action as copying a project item through the Organizer dialog box in Word.

The following example macro copies a module named "CopyMeModule" from a template named "CopyMod.dot" into the Normal template:

Sub OrgCopy()

   'Specifies the source, destination, name
   ' and the type of object being copied.
   Application.OrganizerCopy Source:="C:\My Documents\CopyMod.dot", _
      Destination:=NormalTemplate.FullName, Name:="CopyMeModule", _
      Object:=wdOrganizerObjectProjectItems

End Sub
				

This method has one notable limitation: you cannot copy project items from the Normal template to any other file. This is by design, to prevent the spread of macro viruses.

In addition, you cannot copy projects to or from a template that is loaded as an add-in or reference, unless the template is open in Word for editing.

For additional information, click the article number below to view the article in the Microsoft Knowledge Base: For more information about the OrganizerCopy method, in the Visual Basic Editor, click Microsoft Visual Basic Help on the Help menu, type OrganizerCopy method in the Office Assistant or the Answer Wizard, and then click Search to view the topic.

Use the Addins Collection

This method allows you to use an outside template or Word add-in library (*.wll) without opening or moving the file, and without modifying any other VBA project in Word. That is because add-ins are application-level objects, rather than document or VBA component objects.

Adding a project to the Addins collection is the same as clicking the Add button in the Templates and Add-ins dialog box in Word.

The following example installs an add-in named "AddToAddins.dot" and runs a macro in the template called "AddinMacro":

Sub AddToAddins()

   'Install the add-in.
   Application.AddIns.Add FileName:="C:\My Documents\AddToAddins.dot", _
      Install:=True

   'Run a macro in the add-in.
   Application.Run "AddinMacro"

End Sub
				

The Install property for this method specifies whether the check box for the add-in is selected in the Templates and Add-ins dialog box. This property must be True to run a macro from the add-in.

Unlike referencing a project, you can add the same add-in multiple times without error.

The add-in remains available in the Templates and Add-ins dialog box until you remove it, either by selecting it in Templates and Add-ins and clicking the Remove button, or by using the Addins.Remove VBA method.

One limitation of this method is that the installed state automatically changes to False when you quit and restart Word, unless the add-in is loading from the Startup folder (see the "Copy the Project to the Startup Folder" section of this article). For additional information about this limitation, click the article number below to view the article in the Microsoft Knowledge Base: For more information about the Addins collection object, in the Visual Basic Editor, click Microsoft Visual Basic Help on the Help menu, type Addins collection in the Office Assistant or the Answer Wizard, and then click Search to view the topic.