VBA within Publisher

Part 2

This part of the tutorial addresses the creation and use of variables.

Variables, Data Types, and the "Dim" Statement

Variables are placeholders for data. They can store data directly (for example, a variable can store values such as 123, Bob, and 2006-08-26 20:21), or they can store references to other data (such as a particular shape on a page, or a particular page within a publication).

All variables should be declared using the "Dim" statement before they are used. By default, VBA will automatically create any variable when its name is specified for the first time, but that can be dangerous. If a variable name is mistyped, then a new variable of that name will be created, and that can cause a program to behave oddly. This behaviour can be turned off by inserting the "Option Explicit" option at the very top of a module.

The Dim statement has the following structure:

Dim <Variable Name 1> [As <Data Type 1>][, <Variable Name 2> [As <Data Type 2>]]

Restrictions on variable names are the same as those on subroutine names (see Part 1). If the "As" keyword is omitted, then the variable is declared as a Variant (which can hold any type of data, value or reference). This can be bad, as it will not give you the drop-downs containing lists of possible keywords, and will not warn you if you try and use the wrong type of data in the wrong place. If you want to force yourself to use data types, then use the "Option Strict" option at the top of the module.

Standard data types (which are common to all VBA implementations) include:
Integer and Long (which must contain whole numbers, Long being able to store larger numbers than integer, but taking up more memory)
Single and Double (which store single- and double-precision fractions)
String (which stores text)
DateTime (which stores a date, time, or both)
Variant (which stores anything)
Boolean (which stores either True or False).

Publisher-specific types (which can be found in the Object Browser, which is accessible by pressing the F2 key in the VBE) include:

Page (which contains a reference to a particular page of a document)
Shape (which contains a reference to a particular shape on a page – note that in Publisher, almost anything that can be put on a page is a Shape, including Text Boxes, AutoShapes, Pictures, and WordArt)
TextFrame (which contains a reference to a TextFrame object, the aspect of a Shape that holds its Text Box qualities, including all the text within it. Shapes that are not Text Boxes do not have a TextFrame object)
TextRange (which contains a reference to a particular range of text, surprisingly).

The two types of data type mentioned above have specific names. Value types hold data, whilst Reference types hold only references to data. Most of the most important Publisher-specific data types are reference types, but value types are important for more general programming. Whilst there is not much difference between these when programming, it is important to bear in mind whether you are working with data that is abstract or that is tied to the publication when you are writing code.

Sidenote: Generalised function definitions

Notice above I wrote the general syntax of the Dim statement as

Dim <Variable Name 1> [As <Data Type 1>][, <Variable Name 2> [As <Data Type 2>]]

Terms in angle brackets are instructions to replace the term with your own, omitting the angle brackets. Terms in square brackets are optional; the square brackets themselves should always be omitted, regardless of whether the terms inside them are or not. So valid examples of the Dim statement (ignoring the requirement for valid data types for now) could be:

Dim Foo

Dim Foo As Bar

Dim Felix As Cat, Rover As Dog

Sidenote 2: Foo and Bar

Foo and Bar are abstract keywords ("metasyntactic variables") often used when demonstrating programming principles when it doesn't matter what the variable is called. More information can be found here and here.

Assigning Data to Variables

Back in the good old days of computer programming, when mice were furry and windows let light in, there was a "Let" keyword that was used to assign data to variables. Then Microsoft came along and decided that it was a pointless keyword, and it was much more sensible to omit it. This leaves the format for assigning data to value types as

<Variable> = <Value>

<Variable> is the variable to which data is to be assigned.

<Value> is the new value for the variable. It can be taken from another variable, a property of an object, or assigned directly.

Examples include:

Foo = Bar   'Foo and Bar must have the same data type, or a conversion route - e.g. Foo a String and Bar an Integer

Foo = "Bar" 'Foo must be a String or a Variant

Foo = 123   'Foo must be a numeric type, String or Variant

Foo = ThisDocument.Pages(1).Shapes(3).TextFrame.TextRange.Text 'Foo must be a String or a Variant

The first example assigns the value of the variable Bar to the variable Foo. The second assigns the text "Bar" to the variable Foo. (This illustrates why strings must be enclosed within double quotes.) The third assigns the value 123 to the variable Foo, and the fourth assigns the text of the text box that is the third shape on page 1 of the current document to the variable Foo.

Now, a related statement that applies to reference types is Set. This works in exactly the same way as Let used to, but it creates a reference, rather than assigning a value. The syntax is:

Set <Variable> = [New] <Object>