Using page Shape Data in Visio master shapes

I had a question recently on how to include page Shape Data in master shapes. This sounds like a useful subject for a blog post…

A more fleshed out question might be:

“If my master shape references page level Shape Data cells, how do I ensure that those page cells exist when the shape is dropped onto a new page?”

To answer this, I’m going to try and break this out into some basic questions to make sure we’re all on the same page (yes, sorry, pun intended):

What is Shape Data?

I suspect if you’re reading this post then you already know exactly what Shape Data is. On the off chance that you’re new to Visio and just for completeness…Shape Data (known as Custom Properties prior to v2007) are sets of user-defined fields that hold data on a per shape basis.

Since these fields are surfaced in the UI via the Shape Data window (under the Data tab) they make it very simple for the user to access and edit them, and potentially have the shape react to that changed data.

Of course the Shape Data really lives in the respective shape’s ShapeSheet and it’s here that you create the properties in the first place.

How can a ‘Page’ have ‘Shape’ Data?

So given that you can apply Shape Data to a Shape, how come you can do the same to a page? After all, it’s a page not a shape, isn’t it?

Well that’s true - if you look at a page in the object model it is indeed a separate class, but, it also carries a property name PageSheet and its return type is of type ‘Shape’. PageSheet actually returns the respective page’s ShapeSheet, and it’s here, of course, that you can add Shape Data.

What’s a master’s page?

Each master automatically gets its own page and this is separate from the document pages where an instance might eventually be used. You can see the page when you have the master open in edit mode and it is also represented by the top level node in the Master Explorer treeview:

This means that you can add Shape Data to the master’s page and then reference it from the master shape.

The reason you might want to do this is that it can be useful to have a global variable that other shapes can reference and react to. For example, if you have a master page Shape Data row named Prop.Bonus, you could reference this in the master’s Prop.TotalPackage cell as follows:

Prop.TotalPackage =

Prop.BaseSalary + (Prop.BaseSalary * ThePage!Prop.Bonus)

Notice the ‘ThePage!’ syntax that lets you get hold of the page’s ShapeSheet.

Page Shape Data in new pages

The final trick happens as you drop the master shape onto the page. At this point Visio looks at references from the master to the page and checks to see if those cells exists in the target page. If they do, then no changes occur, but if they are missing then Visio will automatically add them so that, as the shape drop completes, the cells exist and everything works as expected.

Any value that you set in your master page Shape Data row will only be transferred the first time that an instance is dropped. For all subsequent shape-drops the instance will use the current value of the target page’s Shape Data row.

Bear in mind that only page Shape Data that is directly referenced by the master will be transferred, so if you want to see it in the target page you need to make sure that the master uses it in some way.

One last thing to think about is that your destination page Shape Data name needs to be unique as if two masters reference a similarly named page Shape Data cell, then the first one will win – potentially giving unexpected results.

Not just page Shape Data

This feature is not just limited to Shape Data, but also works with User cells as well, so it’s a very useful part of Visio solution development.