Creating Custom SmartArt Layouts with Office Open XML for Office 2007 and Office 2010

Summary:  Explore the components of a SmartArt graphic layout, learn how to customize SmartArt layouts in the XML, and how to create your own custom layout files. Additionally, learn how to customize the SmartArt Styles and Colors galleries, and walk through the markup of a complete custom layout.

Applies to: Excel 2010 | Office 2007 | Office 2010 | Open XML | PowerPoint 2010 | SharePoint Server 2010 | VBA | Word 2010

In this article
Overview
The Construction of a SmartArt Layout
Formatting a SmartArt Layout
Understanding SmartArt Diagram Files
Customizing SmartArt Graphics Using Office Open XML
Creating a .glox, .gcsx, or .gqsx File from an Existing Diagram
Walkthrough: layout1.xml
Next Steps
Additional Resources
About the Author

Published:  February 2011

Provided by:  Stephanie Krieger

Contents

• Overview

• The Construction of a SmartArt Layout

• Formatting a SmartArt Layout

• Understanding SmartArt Diagram Files

• Customizing SmartArt Graphics Using Office Open XML

• Creating a .glox, .gcsx, or .gqsx File from an Existing Diagram

• Walkthrough: layout1.xml

• Next Steps

• Additional Resources

• About the Author

 Grab the sample code

 Download the SmartArt Template files

Overview

Microsoft Office users create diagrams in almost every kind of document and presentation to help illustrate and add impact to important information. But it hasn’t always been an easy thing to do well. The introduction of SmartArt graphics in the Microsoft Office 2007 took business graphics much further by enabling users to create beautiful, high-quality diagrams virtually just by typing a bulleted list.

In Microsoft Office 2010 (and Microsoft Office for Mac 2011), there are over 100 built-in SmartArt layouts for different kinds of diagrams that users can create. But your company might have branding requirements that require something different from the layout options that are provided—or users might need a kind of diagram that does not exist among the built-in layouts. Fortunately, SmartArt graphics are extensible, so you can help users create exactly the content they need. Use Office Open XML to customize any of the built-in SmartArt layouts or create completely custom layouts for your users.

In this article, examine the construction of a SmartArt diagram from the front and back ends, and walk through the core basics of creating a custom SmartArt layout from scratch.

The Construction of a SmartArt Layout

A SmartArt diagram is basically a graphical representation of a multilevel bulleted list. Users add paragraphs and change indent level in the Text Pane, as shown in Figure 1, to add shapes and configure the diagram. Over 100 built-in layouts are available in Office 2010, covering a range of diagram categories such as list, process, hierarchy, and cycle diagrams.

Figure 1: Users build SmartArt diagrams by adding bullets and changing levels in the Text Pane.

As a developer, the two key points to note about SmartArt from the user’s perspective are the available diagram categories and how the diagram builds as the user types.

Most diagrams follow a structure or pattern that helps them visually convey information more effectively than the text could on its own. For example, as shown in Figure 2, an organization chart follows a hierarchical pattern to visually demonstrate the reporting structure in an organization. Similarly, a cycle diagram visually demonstrates the cyclical relationship between steps in a process. These patterns or structures are types of diagrammatic logic.

Figure 2: Examples of a simple SmartArt organization chart and basic cycle diagram.

SmartArt supports many types of diagrammatic logic. For example, a diagram might be linear, cyclical, or hierarchical. It might bend and change direction at the end of the canvas. Whatever kind of diagram it is, every SmartArt layout must follow at least one logical pattern.

Figure 3: An example of the relationships between what the user types in the text pane and what the diagram draws.

When you design a layout, second-level text might appear in the primary shape below your first level text or in its own shape, or it might not be allowed at all. You may have shapes in which users can add images rather than text or purely decorative shapes that take no content and are for aesthetic purposes only.

Formatting a SmartArt Layout

When you insert a SmartArt layout into a document, the default formatting is typically the first accent color from the applied document theme and a simple fill with no additional graphic formatting effects. A user can then easily format the diagram by selecting options from the SmartArt Styles and SmartArt Colors galleries.

SmartArt formatting is tied to the active document theme. So, for example, if you work for an organization that uses specific brand guidelines in their documents, you might create a custom theme that includes brand colors and graphic formatting preferences. (To learn about themes, including an introduction for developers about how to create your own custom themes, see the article Creating Document Themes with the Office Open XML Formats.)

On the SmartArt Tools Design tab in Office 2010 (or the SmartArt tab in Office for Mac 2011) are the SmartArt Styles and SmartArt Colors galleries.

• The SmartArt Styles gallery shown in Figure 4 contains graphic formatting effect styles, the top row of which use the effect specified in your applied document theme.

• The SmartArt Colors gallery shown in Figure 4 contains a range of color combinations using the colors from the applied document theme.

The options in these galleries are automatically populated by Microsoft Office using settings from the active theme. You cannot edit the built-in options that you see here. However, you can add your own custom entries in these galleries when users have requirements that are not met by the built-in options. Learn how to create your own custom color and quick style files later in this article.

Figure 4: The SmartArt Styles and Colors galleries

Understanding SmartArt Diagram Files

SmartArt diagram files are available for a developer to work with in primarily two ways:

• SmartArt diagram parts exist in the ZIP package of a PowerPoint, Word, or Excel file in which diagrams have been inserted by a user. When you want to customize the options for a diagram that already exists in a user document, such as on a sample slide in a custom PowerPoint template, these are the files to use.

• SmartArt layout files are Office Open XML files that have the .glox extension. These are the files that populate the SmartArt UI in PowerPoint, Word, and Excel. When you build a custom SmartArt layout, this is the file type that you need to create.

  Note

  (Use of the term SmartArt UI in this article refers to the SmartArt dialog box and SmartArt Layouts gallery in Office 2010 and the Insert SmartArt Graphic galleries in Office for Macintosh 2011.)

In addition to these two core approaches to working with the Office Open XML for SmartArt graphics, you can also create custom color (.gcsx) and quick style (.gqsx) files to add custom entries to the SmartArt Styles and Colors galleries.

The .glox, .gcsx, and .gqsx files for built-in SmartArt layouts and styles are not exposed when Microsoft Office is installed. However, the .glox files for all of the built-in SmartArt layouts are available for download, accessible from Additional Resources at the end of this article. And you can get the steps later in this article for how to create your own files from the diagram parts in an Office 2010 (or Office for Mac 2011) document package.

Exploring the XML Parts of a Diagram

A SmartArt diagram in a Microsoft Office document file consists of five parts, as you see in Figure 5.

Figure 5: A PowerPoint presentation package expanded to show diagram parts.

It is important to understand what each part contains and thereby what you can potentially customize for the user. However, as a developer, the layout part is the one that corresponds most directly to any custom SmartArt layouts that you create.

• The data#.xml file contains information about both the placeholder data (such as the default "[Text]" that you see in sample shapes when you generate a new diagram) as well as content the user has added to the diagram. That is, this file is where everything from the SmartArt text pane is stored for the diagram.

• The drawing#.xml file describes everything about the visual appearance of the diagram, such as how many shapes it contains and the layout of those shapes.

• The layout#.xml file is the part that contains the information from the original SmartArt .glox file that corresponds to the layout the user selected from the SmartArt UI for creating their diagram. This file determines the type of diagram and how it builds.

• The colors#.xml file contains the color definitions at use in this instance of the diagram, based on the active selection in the SmartArt Colors gallery. This information includes color definitions for each available SmartArt style label.

  A style label is an attribute that you apply to each node in your layout to specify information about its formatting. (Learn more about SmartArt style labels later in this article.)

• The quickStyle#.xml file contains the quick style definitions at use in this instance of the diagram, based on the active selection in the SmartArt Styles gallery. Similar to the colors file, it includes editable definitions for each available style label.

Notice that the previous bulleted list uses the number sign to replace the number 1 for the file names. This is because the number shown in the file names in Figure 5 indicates that it refers to the first diagram in the document. If there are multiple diagrams, the parts for all these appear in the diagrams subfolder and are numbered consecutively.

In the next section, explore examples of how to interact with the layout, colors, and quickStyle files to customize SmartArt content for users in documents or templates. Then, learn how to extract and edit those three files as starting points for your own custom layouts and to add custom entries in the Colors and Quick Styles galleries.

Exploring the Components of a .glox File

A SmartArt layout (.glox) file is a simplified version of the Office Open XML document packages that you may already know. As you see in Figure 6, it contains a [Content_Types].xml file, a _rels folder, and a diagrams folder which contains the primary diagram parts.

Figure 6: The components of a .glox file

As with an Office Open XML document package, the [Content_Types].xml file contains a definition for each primary document part and a definition for each file type extension included in the package. In a .glox package, this file contains just one part name definition, which is for the layout1.xml file, and two extension definitions for the XML and relationship files as you see here.

<?xml version="1.0" encoding="utf-8"?>
<Types xmlns="https://schemas.openxmlformats.org/package/2006/content-types">
  <Default Extension="xml" ContentType="application/vnd.openxmlformats-officedocument.drawingml.diagramLayoutHeader+xml" />
  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml" />
  <Override PartName="/diagrams/layout1.xml" ContentType="application/vnd.openxmlformats-officedocument.drawingml.diagramLayout+xml" />
</Types>

Also as you see in any Office Open XML package, you have the required _rels (relationship) folder that contains a .rels file, which describes the relationships between the parts in the package. In a .glox file, the .rels file contains relationships for the layout file and the layout header, as you see here.

<?xml version="1.0" encoding="utf-8"?><Relationships xmlns="https://schemas.openxmlformats.org/package/2006/relationships">
<Relationship Type="https://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramLayoutHeader" Target="/diagrams/layoutHeader1.xml" Id="rId1" />
<Relationship Type="https://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramLayout" Target="/diagrams/layout1.xml" Id="rId2" />
</Relationships>

The layoutheader1.xml file contains a unique ID as well as detail about the layout for the SmartArt UI, as you see in the markup that follows. The ID must be unique for each layout that you create or it will not load. The title and description are used in the preview that you see in the SmartArt dialog box in Office 2010, as shown in Figure 7.

Notice that the header markup includes a cat tag for the category in which the layout appears. You can add multiple cat tags within the catLsttag to display the layout in multiple categories. Also notice the pri (priority) attribute in the category tag, which indicates where the graphic appears in the dialog box and Layouts gallery. Lower numbers put the diagram closer to the front of the list. As you see in Figure 4, a value of 100 puts this diagram at the front of the List category.

<?xml version="1.0" encoding="utf-8"?>
<layoutDefHdr uniqueId="Simple Snip Corner List_10_2010" xmlns="https://schemas.openxmlformats.org/drawingml/2006/diagram">
    <title val="Snip Corner List" />
    <desc val="Simple custom list layout with a single node and no connectors. This linear layout adds shapes from left to right, reducing the size of all shapes as more are added." />
    <catLst>
        <cat type="list" pri="100" />
    </catLst>
</layoutDefHdr>

Figure 7: A diagram preview in the SmartArt dialog box.

The layout1.xml file is the part that contains the complete instructions for your layout. Walk through the layout1.xml file for the simple custom list shown in Figure 7, later in this article.

Figure 8: The components of a .glox file shown in the OPC editor for Visual Studio 2010

Customizing SmartArt Graphics Using Office Open XML

Once you are familiar with the markup behind SmartArt diagrams, you can customize almost any element of diagram that exists in a Microsoft Office document, from styles and formatting to the type and behavior of shapes.

The sample customization tasks selected for this section are intended to demonstrate concepts that apply both when customizing an existing diagram and when you are creating your own .glox, .gcsx, and .gqsx files.

Changing Shapes

One of the simplest and most often requested changes that I get for SmartArt diagrams is the type of shape used. For example, users might find the organization chart layouts especially useful but the company has branding requirements that do not allow for square edges (such as a standard rectangle) for any graphics.

A user can select all shapes in an existing graphic and then use the Change Shape command on the SmartArt Tools Format tab to change them as needed. However, if new shapes are then added to the diagram, they will revert to the shapes indicated in the layout. So, to change all current and future shapes in the diagram, make the change in the layout#.xml file.

Figure 9: The hierarchy category of built-in SmartArtlayouts

1. If you do not know the name of the shape type that that you want for the new shape, you can either look it up in the file format documentation (see the Standard ECMA 376 site on ecma-international.org) or insert a shape of the type that you need onto a blank slide in a PowerPoint presentation and then examine the markup for that slide to find the shape type.

   If you insert the shape on a slide to find the drawingML shape type name, search in the applicable slide document part for the a:prstGeom tag to find the type name.

2. In the layout#.xml file for the diagram that you want to customize, to find the name of the shape type that you are replacing, search for shape tags to find a tag that contains the type attribute. For example, notice the "roundRect" shape type in the following markup, which refers to a rounded rectangle.

   <dgm:shape type="roundRect" xmlns:r="https://schemas.openxmlformats.org/officeDocument/2006/relationships" r:blip="">
               <dgm:adjLst>
                 <dgm:adj idx="1" val="0.1667"/>
               </dgm:adjLst>
             </dgm:shape>
   

3. Use the Replace command in the editor to replace the existing shape name with the new shape name that you want. The number of instances of the shape type name can vary based on the diagram type.

   If the diagram type contains more than one node for shapes (such as a shape for level one content and a separate shape for level two content) and you only want to replace shapes for a specific node, notice that the shape tag that contains the type attribute is nested within a layoutNode tag. This layoutNode tag is where the name and style label attributes appear for a node, to help you determine which node that you are editing.

   For example, in the following sample markup, see the layoutNode and styleLbl in the first line of markup. The name in this case is very explicit. But if you did not get enough information about the node from the name, you can also infer which node this is from the style label. Learn about style labels in the next section.

   <dgm:layoutNode name="firstChild" styleLbl="bgAccFollowNode1">
               <dgm:alg type="sp"/>
               <dgm:shape type="rect" xmlns:r="https://schemas.openxmlformats.org/officeDocument/2006/relationships" r:blip="">
                 <dgm:adjLst/>
               </dgm:shape>
               <dgm:presOf axis="ch desOrSelf" ptType="node node" cnt="1 0"/>
               <dgm:constrLst/>
               <dgm:ruleLst/>
             </dgm:layoutNode>
   

Changing Colors

Of course, a user can select a shape in a diagram to change its color. But when they add new shapes to the diagram, the colors of the new shapes will use the applied SmartArt color style (that is, the selection in the SmartArt Colors gallery). Similar to changing shapes in a layout, if you want the diagram colors to default differently than those available in the SmartArt Colors gallery, change colors in the XML.

As mentioned earlier, each option in the SmartArt Colors gallery contains a set of definitions for how shapes with each style label appear. For example, if you use the built-in Basic Venn layout to create a Venn diagram, the shape fill is semitransparent. That transparent fill is provided by the vennNode1 style label. So, if you needed to create a Venn layout that does not use transparent fill, you could just replace the style label name value in the appropriate layoutNode tag.

See the Style Labels table in the SmartArt Developer Reference for a complete list of style labels with descriptions, visual examples, and intended use. For example, that table will show you that the style label referenced in the previous markup sample, "bgAccFollowNode1" indicates" a secondary shape, such as one used to display child text.

One of the most common user requests I hear is the ability to show the accent 1 theme color automatically as the first shape in a diagram that uses a range of the theme accent colors. Typically, the first accent color in a theme that uses corporate branding represents the company’s primary brand color.

By default, many layouts do not display accent 1 color when a colorful option is selected in the SmartArt Colors gallery. This is because that color is reserved for certain purposes where it should always be the first color, such as the top shape in an organization chart or the center shape in a radial diagram. node0 is the style label typically used in these cases and the color does not vary with this style label. However, you can edit the colors#.xml part for the diagram to easily effect this change so that the rotation of accent shapes automatically begins with accent 1.

Figure 10: A Basic Block List diagram using the first Colorful option in the SmartArt Colors gallery begins with accent 2.

For purposes of this example, insert a Basic Block List diagram onto a slide and apply the first Colorful option in the SmartArt Colors gallery, as shown in Figure 10. Then, close the file and open the document ZIP package for editing the XML.

1. Open the colors#.xml file associated with the Basic Block List diagram that you just created.

2. Scroll down or search for the styleLbl tab for the node1 style (it is the second style listed in the file). The contents of that styleLbl tag include fill and line color information, as well as available tags for addition color information (such as text fill color) as shown here.

   <dgm:styleLbl name="node1">
       <dgm:fillClrLst meth="repeat">
         <a:schemeClr val="accent2"/>
         <a:schemeClr val="accent3"/>
         <a:schemeClr val="accent4"/>
         <a:schemeClr val="accent5"/>
         <a:schemeClr val="accent6"/>
       </dgm:fillClrLst>
       <dgm:linClrLst meth="repeat">
         <a:schemeClr val="lt1"/>
       </dgm:linClrLst>
       <dgm:effectClrLst/>
       <dgm:txLinClrLst/>
       <dgm:txFillClrLst/>
       <dgm:txEffectClrLst/>
   </dgm:styleLbl>
   

   Notice the meth (method) attribute in the fillClrLst with the value repeat. This means that each subsequent shape will take on the next accent color in the list and then start back at the top of the list after reaching the end. You will also see style label definitions that use the method span. This method creates a range of colors using shades of the accent colors in the list (similar to a color wheel).

3. Notice that the fill color list tag (dgm:fillClrLst) in the previous markup begins with the accent 2 theme color. Add a new line above the accent 2 scheme color tag for accent 1.

   <a:schemeClr val="accent1"/>
   

   After you do this, there should be six schemeClr tags nested within the fill color list tag. This means that the first shape in the diagram will use accent 1 fill and the diagram shapes will repeat the range of all six theme accent colors as shapes are added.

4. Because node1 is the default style label that is used for this diagram, this is all you have to do to reopen the presentation in PowerPoint and see the change in the diagram. Similarly, if you are editing the colors for a different diagram, you can view the layout#.xml file to determine the style labels that are used and alter the colors for those styles.

   However, if the user could potentially change the layout of the active diagram to a different SmartArt layout that uses different style labels, you may want to work your way through the list of all style labels in the colors file and add accent 1 throughout, wherever a list of colors is repeated.

   If you do this, notice that the schemeClr tag for some style labels is a nested tag that contains attributes. For example, the vennNode1 style includes a transparency attribute for each specified color, specified by the alpha tag shown here. When you add a tag for the accent 1 color, make sure that you add any required attributes as well for consistency.

         <a:schemeClr val="accent2">
           <a:alpha val="50000"/>
         </a:schemeClr>
   

When you reopen the presentation in PowerPoint, you see the altered colors in the existing diagram. However, notice that the SmartArt Colors gallery appears unchanged. To add options to the gallery itself that users can apply to any SmartArt diagram in any document, create a custom .gcsx file as demonstrated later in this article.

Changing Behavior

Rules and constraints appear in a layout#.xml file to govern parameters for shapes and relationships within the layout, such as margins, space between shapes, minimum and maximum font size, and shape height or width.

For example, insert a new graphic into a presentation using the layout Varying Width List (By default, in Office 2010, this layout is the eighth entry in the List category in the SmartArt dialog box). This simple vertical list enables the width of each shape to grow independently.

If you examine the layout#.xml part for a Varying Width List diagram, you find several sections in the markup providing constraints and rules. In a layout, constraints and rules will appear relative to the node to which they pertain.

The first set of constraints that you see defines several parameters for the entire diagram (the root layout node). Notice the third constraint in the list, which indicates the maximum font size (in points) allowed in the diagram as shown here. Font size in SmartArt diagrams is dynamic by default, based on the amount of content a user adds. The value in this example prevents the font size from automatically exceeding 65 points as the user edits text.

(Note that this value does not prevent the user from manually applying a larger font size. When a user manually applies font size, automatic resizing behavior no longer occurs in that instance of the diagram.)

    <dgm:constr type="primFontSz" for="ch" forName="text" op="equ" val="65"/>

A bit further down in the file, you see constraints and rules that affect the primary shapes within the diagram. Specifically, notice the margin constraints and rules shown here.

<dgm:constrLst>
    <dgm:constr type="tMarg" refType="primFontSz" fact="0.2"/>
    <dgm:constr type="bMarg" refType="primFontSz" fact="0.2"/>
    <dgm:constr type="lMarg" refType="primFontSz" fact="0.2"/>
    <dgm:constr type="rMarg" refType="primFontSz" fact="0.2"/>
</dgm:constrLst>
<dgm:ruleLst>
    <dgm:rule type="w" val="INF" fact="NaN" max="NaN"/>
    <dgm:rule type="primFontSz" val="5" fact="NaN" max="NaN"/>
</dgm:ruleLst>

After trying the tasks in this section for customizing a diagram in the XML, you likely have a good feel for the XML components of a diagram. As you explore the remaining sections, remember that the content in the diagram parts that you edit for an existing instance of a diagram are basically the same as those that you work with when you are creating your own layouts or altering the SmartArt Styles and Colors galleries. So, you already know much what you need to start on next steps.

Creating a .glox, .gcsx, or .gqsx File from an Existing Diagram

If you want to create a custom layout that resembles an existing layout but you do not have access to the .glox file, you can save time by creating a .glox file that uses the layout#.xml part for an existing instance of the diagram that you want to copy. Similarly, you can use the colors and quick styles parts in an existing diagram to save time creating your own .gcsx and .gqsx files.

Creating a .glox File

The first of the two following procedures discusses creating the .glox package. However, you must follow the steps in the second procedure to edit the layout1.xml file before your new .glox file will be usable as a layout.

Note that the example in the second procedure uses the layout#.xml file for the Basic Block List layout.

Revisit the section on exploring the components of a .glox file to see the files and folders that you need to create. In that section, you also find the markup that you need for the [Content_Types].xml file, the .rels file, and the layoutHeader1.xml file in the following steps.

To create a .glox package

1. Create the [Content_Types].xml file with the markup provided earlier.

2. Create folders named _rels and diagrams.

   • In the _rels folder, add the .rels file with the markup provided earlier.

   • In the diagrams folder, add the layoutHeader1.xml file with the markup provided earlier.

3. In the layoutHeader1.xml file, edit the markup to make certain that you have specified a unique ID, and to give the new layout a title and description. You may also need to edit the category list and priority as appropriate for the type of diagram that you are creating.

4. Extract the layout#.xml part for the layout that you want to copy from the Microsoft Office document into which you have inserted an instance of that diagram. If the diagram was not the first in the document from which you extracted the part, rename the file layout1.xml.

5. Add the layout1.xml file to the diagrams folder that you created in step 2. The next procedure in this section will show you the required edits to this file for the new .glox package to function as a SmartArt layout.

6. Select the content types file and the two folder that you created and compress them into a ZIP folder. Then, change the file extension of the zip package to .glox.

To edit a layout1.xml file for use in a .glox file

1. With the layout1.xml file open for editing, search for the prefix dgm: and globally replace it with nothing. So, for example, the <dgm:layoutDef… tag becomes <layoutDef….

2. Edit the layout definition tag (the first line underneath the XML version reference at the top of the file) to include only the namespace definition for a diagram, and without the :dgm part reference. The edited line should resemble the following markup.

   <layoutDef xmlns ="https://schemas.openxmlformats.org/drawingml/2006/diagram">
   

   Note

   The preceding steps are the only steps that you must take before the .glox file is technically usable. However, the remaining steps are recommended for best practice and ease of editing/proper behavior as you customize the layout.

3. If title, description, and category tags appear directly underneath the layout definition tag, delete them. Leaving them will not prevent the file from functioning, but this information appears in the layoutHeader1.xml part in the .glox package.

4. You may want to replace the sample data (sampData), style data (styleData), and color data (clrData) tags with your own content, but it is not necessary to do that at this point.

5. These tags are technically optional (that is, the .glox file will load without them) but they are necessary because they enable previews to appear in the SmartArt dialog box, the SmartArt Styles gallery, and the SmartArt Colors gallery respectively. The sample data also enables the starter shapes that appear when the user first inserts the diagram. So, you might want to edit these tags later if what you see in the previews and placeholders enabled by these tags is no longer what you want after you customize the layout. Learn more about these sample data, style, and color tags in the walkthrough section.

6. Even though the .glox file will function in most cases at this point, there are still some recommended changes to make to clean up the layout file and make it easy to edit. In particular, notice the following:

   • Shape tags include relationship information that applies to the instance of the diagram in a document; not to a layout. For best practice, scan through the markup now and clean up the layout file by deleting this unnecessary information. For example, the tag shown here that contains the namespace and blip attributes is the opening to a paired tag because it contains no slash at the end of the tag.

     <shape xmlns:r="https://schemas.openxmlformats.org/officeDocument/2006/relationships" r:blip="">
     

     Edit the tag shown here to be <shape> in the layout file. However, if the original shape tag is not paired (i.e., the slash appears at the end of this tag and there is no end tag in the file) make sure that you leave the slash when you remove the unnecessary attributes from this tag. Do not remove tags nested within a shape tag, even if they are empty. Some of these may be required.

   • If a shape tag that includes the shape type does not include a style label, it is a good idea to add one. As noted earlier, shapes will use appropriate style labels if none is specified. However, specifying style labels gives you much more control over the appearance of the diagram. To do this, find the layoutNode tags for shape nodes and add the styleLbl attribute within that tag.

     For example, if you are using the Basic Block List layout file as the example here, the tag that should contain a style label is <layoutNode name="node">. To assign the style label node1 to the shapes in this node, edit the tag as shown here.

     <layoutNode name="node" styleLbl="node1">
     

Before you start customizing your new .glox file, save it to the default user SmartArt folder and then open the SmartArt dialog box in an Office 2010 program to see whether it loads correctly in the dialog box and can be inserted in a document.

• The default SmartArt folder location for Office 2010 running on Microsoft Windows 7 or Windows Vista is C:\Users\[user name]\AppData\Roaming\Microsoft\Templates\SmartArt Graphics.

• If your new file will also be used in Office for Mac 2011 (all SmartArt layouts are cross-platform compatible), the path for custom SmartArt content on the Mac OS is /Users/[user name]/Library/Application Support/Microsoft/Office/SmartArt Graphics.

Creating .gcsx and .gqsx Files

The process for creating .gcsx and .gqsx files resembles creating a .glox file. The two procedures that follow show you the steps for a .gcsx package and explain differences for .gqsx as applicable.

Even though the steps and file/folder makeup of the package are largely the same as when you are creating a .glox file, those steps are repeated here because there are differences in some files names and markup at every step.

To create a .gcsx and .gqsx package

1. Create the [Content_Types].xml file. The markup resembles the .glox file but references the correct file for the part name and the correct content type for colors or effects in both the XML extension and the partname information. The markup shown here is for a colors file, as you can see by the references to diagramColorsHeader and diagramColors.

   <?xml version="1.0" encoding="utf-8"?>
   <Types xmlns="https://schemas.openxmlformats.org/package/2006/content-types">
     <Default Extension="xml" ContentType="application/vnd.openxmlformats-officedocument.drawingml.diagramColorsHeader+xml" />
     <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml" />
     <Override PartName="/diagrams/colors1.xml" ContentType="application/vnd.openxmlformats-officedocument.drawingml.diagramColors+xml" />
   </Types>
   

   If you are creating a .gqsx file, replace diagramColors with diagramStyles (and diagramColorsHeader with diagramStylesHeader). And replace the filename colors1.xml in the partname definition path with quickstyle1.xml. Notice that colors is plural in file names but quickstyle is not.

2. Create folders named _rels and diagrams.

   • In the _rels folder, add the .rels file with the markup shown here. If you are creating a quick style file instead of a colors file, make the same alterations that were required in the content types file.

     <?xml version="1.0" encoding="utf-8"?>
     <Relationships xmlns="https://schemas.openxmlformats.org/package/2006/relationships">
       <Relationship Type="https://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramColorsHeader" Target="/diagrams/colorsHeader1.xml" Id="rId1" />
       <Relationship Type="https://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramColors" Target="/diagrams/colors1.xml" Id="rId2" />
     </Relationships>
     

   • In the diagrams folder, add the colorsHeader1.xml file with the following markup.

     <?xml version="1.0" encoding="utf-8"?>
     <colorsDefHdr xmlns="https://schemas.openxmlformats.org/drawingml/2006/diagram" uniqueId="new unique ID">
         <title val="Colorful - Start with Accent 1" />
         <desc val="" />
         <catLst>
             <cat type="colorful" pri="100" />
         </catLst>
     </colorsDefHdr>
     

     In the header file, edit the markup to make certain that you have specified a unique ID for each .gcsx or .gqsx file that you create, and to name your color or style. Additionally, edit the category and priority as needed.

     If you are creating a quick style file, the colorsDefHdr tag in this sample markup is named styleDefHdr (make sure that you change both the start tags and the end tags).

     For both color and style header files, it is important to be aware that the category names to add in the header file do not precisely match what you see in the UI. The list of category names to use in the header file is shown here in Table 1. As with any XML markup, remember that the terminology must be precise, including capitalization.

   Table 1. Color and style category names for .gcsx and .gqsx files

   Color gallery categories	Style gallery categories
   mainScheme colorful accent1 accent2 accent3 accent4 accent5 accent6	simple 3D

3. Create a new PowerPoint presentation with a SmartArt graphic in it, and apply the color style that is closest to the custom colors that you want. (If you are creating a quick style file, apply the SmartArt style that is closest to the custom quick style that you want).

4. Extract the colors#.xml part (or the quickStyle#.xml part) for the applicable diagram from the ZIP package of the file that you just created. If the diagram was not the first in the document from which you extracted the part, rename the file so that it is colors1.xml (or quickStyle1.xml).

5. Add the file that you just extracted to the diagrams folder that you created in step 2. The next procedure in this section will show you the required edits to this file for the new package to function as a SmartArt color or quick style file.

6. Select the content types file and the two folders that you created and compress them into a ZIP folder. Then, change the file name extension of the zip package to .gcsx (or .gqsx for a quick style file).

To edit a colors1.xml (quickstyle1.xml) file for use in a .gcsx or .gqsx file

1. With the colors1.xml (quickstyle1.xml) file open for editing, search for the prefix dgm: and globally replace it with nothing. So, for example, the <dgm:colorsDef… tag becomes <colorsDef….

2. Edit the colors (or styles) definition tag (the first line underneath the XML version reference at the top of the file) to include the two namespace definitions that you see by default but not the unique ID (as this is in the header file in the package), and remove the :dgm part reference from the diagram namespace prefix (so that it is just xmlns=). The edited line should resemble the following markup. Note that in a quick style file, this line of markup looks the same but the tag name is styleDef.

   <colorsDef xmlns="https://schemas.openxmlformats.org/drawingml/2006/diagram" xmlns:a="https://schemas.openxmlformats.org/drawingml/2006/main">
   

You’re now ready to make whatever formatting changes you would like to the style label definitions in the colors1.xml or quickStyle1.xml file in your new package. Do this exactly as you would for recoloring the style label definitions for an existing diagram, as demonstrated earlier.

To load your new color or style file, save it to the applicable path for custom .glox files provided in the previous section. Note that .gcsx and .gqsx files are also cross-platform and will load in both Office 2010 and Office for Mac 2011 SmartArt Styles and Colors galleries.

Walkthrough: layout1.xml

As you have already seen, the layout1.xml file stores the complete definition for a SmartArt diagram layout. This section shows you a layout1.xml file for the custom simple linear list shown earlier.

To create your own completely custom layout from scratch, you can create a .glox package as explained in the previous section and just create a new layout1.xml file instead of copying one from an existing diagram.

A layout file consists of the following:

• Sample\placeholder data to create previews in the SmartArt UI as well as the SmartArt Styles and Colors galleries.

• Definition for the root layout node (the overall diagram) and all nodes within it—including shapes (points) within the diagram, text and images within shapes, and the relationships between shapes and text elements. The definitions include parameters and constraints for appearance and rules for behavior of the diagram layout and its content.

Within even a simple diagram, as shown here, you will notice that you see multiple algorithms at work—such as those pertaining to the behavior of the diagram (linear flow and composite in this case), text (referred to as tx in the markup), and spacing between shapes (referred to as sp in the markup). You also see For Each statements in this sample markup to manage the propagating of shapes and space between shapes.

Some more complex layouts contain elements not seen here, such as conditional statements to handle the options available to the user within the algorithm type (as in a hierarchy diagram, for example) or use of connectors between shapes (such as in the diagram image shown in Figure 1). However, this layout gives you a core set of basics for getting started with your own layouts, which you can build upon using the additional resources that are provided later.

To see the full markup for the layout1.xml file that is shown in the samples that follow, see the file Simple Snip Corner List.glox in the sample downloads for this article.

Sample Data, Colors, and Styles

Directly following the layout definition tag are the sample data, color data, and style data tags that are used to create the placeholder content, color gallery thumbnail, and style gallery thumbnail respectively. The placeholder content created from the sample data markup determines the default shapes that appear when the user inserts a new diagram based on the layout as well as the preview that appears in the SmartArt UI.

Showing three top-level shapes as you see in the markup here is typical, but you can customize this data to fewer or more shapes in your previews and in the default content that is created when the user inserts a new diagram based on the layout.

This sample shows the sample data. Directly following it in the markup are the styleData and clrData tags, which contain the same data model, point list, and connection list tags nested within. In the example layout used here, as is typical, the styleData and clrData models are identical to the sample data model. However, they do not have to be.

<sampData>
<dataModel>
    <ptLst>
        <pt modelId="0" type="doc" />
        <pt modelId="10" type="node">
            <prSet phldr="1" />
        </pt>
        <pt modelId="20" type="node">
            <prSet phldr="1" />
        </pt>
        <pt modelId="30" type="node">
            <prSet phldr="1" />
        </pt>
    </ptLst>
    <cxnLst>
        <cxn modelId="40" type="parOf" srcId="0" destId="10" srcOrd="0" destOrd="0" presId="" />
        <cxn modelId="50" type="parOf" srcId="0" destId="20" srcOrd="1" destOrd="0" presId="" />
        <cxn modelId="60" type="parOf" srcId="0" destId="30" srcOrd="2" destOrd="0" presId="" />
    </cxnLst>
</dataModel>
</sampData>

• Notice in this markup that the point list provides for three shapes, set as placeholders. You can replicate the point tags to create additional placeholder shapes if you want (or remove to include fewer shapes). However if you do, take note to update IDs so that all are unique.

• If changing IDs, notice that the ID numbers for the points are referenced in the destID (destination ID) attribute in the corresponding connection list. And that the ID for the connections follows on consecutively from the IDs used for the points.

If your diagram is more complex, you can nest points to create corresponding placeholder data as shown here.

<sampData>
<dataModel>
    <ptLst>
        <pt modelId="0" type="doc" />
        <pt modelId="10" type="node">
            <prSet phldr="1" />
        </pt>
        <pt modelId="11" type="node">
            <prSet phldr="1" />
        </pt>
        <pt modelId="20" type="node">
            <prSet phldr="1" />
        </pt>
        <pt modelId="21" type="node">
            <prSet phldr="1" />
        </pt>
        <pt modelId="30" type="node">
            <prSet phldr="1" />
        </pt>
        <pt modelId="31" type="node">
            <prSet phldr="1" />
        </pt>
    </ptLst>
    <cxnLst>
        <cxn modelId="40" type="parOf" srcId="0" destId="10" srcOrd="0" destOrd="0" presId="" />
        <cxn modelId="12" type="parOf" srcId="10" destId="11" srcOrd="0" destOrd="0" presId="" />
        <cxn modelId="50" type="parOf" srcId="0" destId="20" srcOrd="1" destOrd="0" presId="" />
        <cxn modelId="22" type="parOf" srcId="20" destId="21" srcOrd="0" destOrd="0" presId="" />
        <cxn modelId="60" type="parOf" srcId="0" destId="30" srcOrd="2" destOrd="0" presId="" />
        <cxn modelId="32" type="parOf" srcId="30" destId="31" srcOrd="0" destOrd="0" presId="" />
    </cxnLst>
</dataModel>
</sampData>

Notice that the data in the previous sample knows which shapes are secondary because they are related to the primary shapes in the connection list (the srcID attribute).

If you are not terribly concerned with the structure of previews or default content and want to make sure that something appears, you can use the simpler default data, an example of which is shown in the following sample.

<sampData useDef="1">
    <dataModel>
        <ptLst/>
        <bg/>
        <whole/>
    </dataModel>
</sampData>

The useDef (use default) attribute is a Boolean value. When it is true, as in this example, clrData and styleData tags are ignored and defaults are used instead. (Note that, by default, three shapes are displayed.) So, you can omit the color and style data tags and previews will still appear in those galleries. If the useDef attribute is omitted (it is false by default), information must be specified in the point list and connection list for sample data to appear.

Root Layout Node

Directly following the sample data is the root layout node definition, which provides the definition (including algorithm, parameters, constraints, and rules) for the whole diagram.

The point nodes (nodes that describe a typical shape element in the diagram into which the user adds content) as well as supporting nodes (such as those that define the space between shapes), are all nested within the root layout node tag. They are broken up under several headings here for readability.

<layoutNode>
    <alg type="lin" />
    <shape />
    <constrLst>
        <!--Font size constraint-->
        <constr op="equ" type="primFontSz" for="des" ptType="node" val="40" />
        <!--Constraints for composite-->
        <constr type="w" for="ch" forName="composite" refType="w" />
        <constr type="h" for="ch" forName="composite" refType="h" />
        <!--Space between rows/columns-->
        <constr op="equ" type="sp" refType="w" refFor="ch" refForName="composite" fact="0.1" />
        <!--Constraints for sibTrans-->
        <constr op="equ" type="w" for="ch" forName="sibTrans" refType="w" refFor="ch" refForName="composite" fact="0.1" />
        <constr op="equ" type="h" for="ch" forName="sibTrans" refType="w" refFor="ch" refForName="sibTrans" />
    </constrLst>
    <forEach name="nodesForEach" axis="ch" ptType="node">
        <!--composite-->
        <layoutNode name="composite">
        <alg type="composite">
            <param type="ar" val="1.6667" />
        </alg>
        <shape />

• The primary algorithm type for this diagram is linear flow. In this case, it is a horizontal linear list in which shapes are added from left to right along a single line. Shapes will automatically decrease in size in order to remain equally sized and spaced as new shapes are added.

• The font size constraint in this case sets the maximum font size for the diagram to 40 points.

• The constraints for composite refer to the composite algorithm, which sits within its own node at the bottom of this sample. This algorithm specifies the size and position of child nodes, but as you can see here it also sets parameters for the whole diagram. Notice the param tag nested within the composite algorithm tag at the bottom of the markup here, which sets the aspect ratio for the layout. Changing this aspect ratio will change the shape proportions. For example, an aspect ratio of 1 would make the snipped rectangles in this diagram appear as snipped squares.

• The forEach statement in this example propagates subsequent points (shapes) as the user creates the diagram. Without this statement, only one instance of the snipped rectangle will appear in the diagram and each new top-level item would be a bulleted paragraph within the shape.

• The constraints for sibTrans (sibling transition) refer to the following markup that appears at the end of this layout file (still nested within the root layout node). This content defines spacing between sibling elements.

  <forEach name="sibTransForEach" axis="followSib" ptType="sibTrans" cnt="1">
      <!--sibTrans-->
      <layoutNode name="sibTrans">
          <alg type="sp" />
          <shape />
      </layoutNode>
  </forEach>
  

• Notice another forEach statement here, which propagates another instance of space for each new instance of a shape in this layout.

• Also notice that this sibTrans node uses another algorithm—the sp (space) algorithm.

  Tip

  You can set the width constraint for the space algorithm shape to a negative value in order to create overlapping shapes in your layout.

Primary Element Node

This example layout contains one primary shape/point element (the snipped rectangle), the definition of which is shown here.

<!--Main-->
<layoutNode name="Main" styleLbl="node1">
    <alg type="tx">
<param type="parTxLTRAlign" val="l" />
    </alg>
    <shape type="snipRoundRect">
<adjLst>
    <adj idx="1" val="0.1667" />
    <adj idx="2" val="0.1667" />
</adjLst>
    </shape>
    <presOf axis="desOrSelf" ptType="node" st="1" cnt="0" />
    <constrLst>
<constr type="lMarg" refType="primFontSz" fact="0.15" />
<constr type="rMarg" refType="primFontSz" fact="0.15" />
<constr type="tMarg" refType="primFontSz" fact="0.15" />
<constr type="bMarg" refType="primFontSz" fact="0.15" />
    </constrLst>
    <ruleLst>
<rule type="primFontSz" val="10" />
    </ruleLst>
</layoutNode>

I named this node Main because it is the only shape element in the diagram. Set the value of a Name attribute to basically anything that you consider intuitive. Notice the following:

• As explained earlier in this article, a style label appears in the layoutNode tag to define the formatting for shapes in this node.

• The tx (text) algorithm defines additional parameters for the text within these shapes. In this case, the paragraph text horizontal (left-to-right) alignment is specified as left. The default if this parameter is omitted is centered.

• The adjLst tag nested within the snipped rectangle shape tag specifies the adjustment handle values. These values enable you to set the position of the yellow diamond adjustment handles that you see on most Office Art shapes. If you want a precise shape, you may find it easiest to insert a shape on a slide, set the adjustment handles as you want the shape to appear, and then extract the adjustment values from the markup for the shape on that slide.

• The presOf (presentation of) tag refers to child text within the node. If this line is not present, no text is allowed below level one. The axis value desOrSelf refers to the active level or all descendants. References that you see to ch (child) refer to the next lower level. References to des (descendants) refer to all subsequent levels.

• As seen earlier in this article, the additional constraints shown in this markup example set the margins as a factor of the active primary font size and the rule provided here sets the minimum font size for text within this node.

More complex layouts will of course contain additional elements, but this example contains all of the basic elements that you need to create a working SmartArt layout from scratch.

Next Steps

Once you feel comfortable creating a basic custom layout such as the one explored in this article, remember that you can copy and customize any built-in layout as a way to explore more complex layout structures.

Visit the SmartArt Developer Reference links provided in the Additional Resources, where you can learn about all available SmartArt algorithms and techniques such as adding animation settings to your layouts. And the implementer notes listed in Additional Resources are a great, searchable resource for accessing the full documentation on diagram definitions within the file format.

Additional Resources

For more information, see the following resources:

• SmartArt Developer Reference

• Layout Algorithms: SmartArt Developer Reference

• SmartArt Style Labels: SmartArt Developer Referencehttps://msdn.microsoft.com/en-us/library/dd439445(v=office.14)

• Diagram Definitions: ECMA 376 Implementer Notes on ecma-international.org

• MSDN Code Gallery: Office 2010 SmartArt Template Files (136 Samples)

• MSDN Code Gallery: PowerPoint CustomHelp add-in code for Office for Mac 2010

About the Author

 Stephanie Krieger is the author of two books, Advanced Microsoft Office Documents 2007 Edition Inside Out and Microsoft Office Document Designer. As a professional document consultant, she has helped many global companies develop enterprise solutions for Microsoft Office on both platforms. Her new book for Office 2010 and Office for Mac 2011 is scheduled for release in Spring 2011.