Constraints
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
This topic describes how to use constraints to position shapes and words in a layout node.
You can specify constraints for the current node or for child nodes. Constraints are listed in <constrList> tags. Each algorithm has a specific set of constraints that helps control the layout. All constraints have default values.
Constraint Types
Indicate which constraint type the constraint should use by including the type parameter. Constraints can specify width and height. For example, consider the constraints in the following code.
These constraints specify a width of 25 millimeters for the shape and a height that remains constant relative to the width. The refType value indicates that the height should be specified relative to the width (w) constraint. Specifying a height relative to the width initializes the aspect ratio of a shape. In this case, the height is 0.65 times the width.
Rules
Rules indicate the ranges of values that a layout algorithm can use to modify the constraint values if it cannot lay out the graphic by using the constraints. For example, you can specify a rule to increase the size of a shape or to decrease the font size, if a user types more text in a text shape than fits.
Consider the following example rule list, which could be located in a layout node or shape:
The <ruleLst> tag indicates the beginning of a rule list. The tags that follow specify the rules to apply. In this case, the first rule applies to the height of the shape and specifies that the height can grow as much as necessary to accommodate text. This is indicated by the INF value. The second rule specifies that the width can also increase as much as necessary. The third rule applies to the text font size and specifies that the font can shrink to a size of 5 points to fit inside the shape. The rules are executed in the order they appear in the XML code. In this case, the shape grows as high as it can, then as wide as it can, and then the font starts to shrink. The last rule is handy because the parent node might impose a limit on the maximum width or height for this node at some point, causing the size growing rules to reach a limit. The font shrinking rule is a good backup.
Mapping to the Data
SmartArt templates are generally designed so that users can quickly and simply enter data and have the graphic customize itself to appropriately display that data. You can conceptually think of this user-input data as a nested list. For example, a user might enter information similar to the following figure into the text pane of a SmartArt template, illustrating a conference schedule.
User input in a SmartArt graphic
.jpg "User input in a SmartArt template")
This information is stored in the data definition file of the final SmartArt graphic.
The <presOf> tag links the layout back to the data definition. The following example shows a <presOf> tag for a layout node that does not map to any data. This tag is used for shapes without text and for layout nodes without shapes that algorithms use to lay out the actual shapes.
The <presOf> tag in the preceding example can also be expressed as follows.
<presOf />
You can also use this tag to map a specific layout node to a specific data element. The following simplified example demonstrates using the <presOf> tag to place the first and second elements of the data definition into two rectangular shapes.
The ch attribute indicates that the data should go into the child shape (the roundRect). The st attribute points to the data element that should be mapped to the shape, and cnt indicates the number of data elements to map.
One of the most common presOf statements sets the axis to self. This means that the layout node maps to the current data point. The desOrSelf axis value indicates that the layout node can map to the current data point and all its descendents.
For a comprehensive list of presOf attributes, see forEach and presOf Attributes.
Using Variables
Twenty-six user constraint variables are available to developers. These variables can be used to set a fixed value. Other constraints can then refer to that value. The following code shows an example of a variable.
<constr type="userA" val="26.4"/>
The type parameter can be userA through userZ. You can set and reference variables at different parent/child or sibling-level nodes. This has many uses, such as setting node width and height to the same value across the graphic.
Control Statements
The SmartArt Developer Reference provides tags that allow for programming-language–style control statements.
forEach Loops
The <forEach> tags have a function similar to that of a For loop in a programming language. The following example demonstrates a linear algorithm with linear flow going from left to right. Each top-level data item that the user types will have the characteristics of the layout node in the forEach loop.
The attributes for the <forEach> tag set the details of the flow of the For loop. Setting the ptType attribute to node specifies that layout nodes will be created for each data item. Setting the axis attribute to ch specifies that the nodes are children of the current layout node. The <alg> and <shape> tags specify that the graphic uses a rectangle shape and that the rectangle contains text, respectively.
For a comprehensive list of forEach attributes, see forEach and presOf Attributes.
Choose Statements
The SmartArt SDK also provides tags that allow the code to evaluate conditional statements. This is similar to a conditional statement, such as If…Then…Else or Select Case, in programming languages. Use a <choose> block with a set of <if> blocks to evaluate a condition, and then perform different actions depending on the value of the condition.
The following example sets a direction value between the <varLst> tags. Later, that value is used to pick the correct linDir parameter.
The <if> tag in this <choose> block tests the dir value to see if it is norm. If it is, it sets the linDir parameter to fromL (from the left). Otherwise, it sets the parameter to fromR (from the right). The op attribute value equ specifies that this is an equality comparison. You can use Lt and gt for less than and greater than, respectively.
Shapes
Include shapes in a SmartArt template by using the <shape> tag. The type of the shape is specified in this tag, as shown in the following code.
<shape type="octagon" />
You can choose from a variety of shape types, including rectangle (rect), triangle, diamond, or chevron. For a list of available shape types, see AutoShapes.
Adjust Handles
Some shapes include a series of yellow dots that you can manipulate by using the mouse to further refine the shape. These adjustment handles are represented in the XML code by a number. For example, the following code sets the bentArrow shape’s adjust handles to extreme values that make it resemble an upside-down L.
The idx number indicates the index of the adjust handle. The val indicates how much the handle is adjusted.
Packaging the Layout Definition File
After completing the layout and layout header files for a new SmartArt template, you must package these files and place them in users’ distributable file locations. For more information, see the “File Locations for Distributable SmartArt Templates” section in SmartArt Files and Tools.
The layout definition file (.glox file) must have two more files to establish the relationship between the layout and layout header. The following list shows the required files and their locations:
CompressedFileName.glox\[Content_Types].xml
CompressedFileName.glox\diagrams\LayoutHeader1.xml
CompressedFileName.glox\diagrams\Layout1.xml
CompressedFileName.glox\_rels\.rels
The [Content_Types].xml file and the .rels file (in the \_rels\ directory) establish that the LayoutHeader1.xml file contains header information for the layout file.
The following example shows a [Content_Types].xml file.
The following example shows a .rels file.
These two files generally will not change when you create a new layout template.
When all four files are created and placed in the correct directories, perform the following steps:
Compress the top-level directory into a .zip file by right-clicking the .zip file and adding the directory to a .zip archive.
Rename the .zip extension to .glox.
Copy the .glox file to users’ distributable file locations.
Testing the Graphic Layout
After packaging a new layout template, the template should be available. Open Office PowerPoint 2007 (close it and reopen if it is already open). In the Illustrations group on the Insert tab, click SmartArt. At this point, your new template will load. If there is a problem with the name or unique ID of the graphic, the user will be presented with an error message that contains the error log. If the graphic has a problem, it will appear as a red X in the Choose a SmartArt Graphic dialog box. If the user attempts to insert the graphic, an error dialog box appears. For more information, see the “Error Log” section in SmartArt Files and Tools.
Common Errors
There are three general categories of errors in layout files: nonUniqueID errors, XML or schema errors, and layout validation errors.
nonUniqueId
The layout does not have a unique ID. When this error occurs, the layout files with duplicate uniqueID values will not load. The user is presented with an error message in the SmartArt layout group.
The following error log entry shows a typical nonUniqueID error.
XML or Schema Errors
There are two ways in which XML or schema errors can cause the layout to fail. If the error occurs in the layout header file (LayoutHeader1.xml), the file will not load. If the error occurs in the Layout1.xml file, the file will load but will display a red X in the Choose a SmartArt Graphic dialog box. An error message appears when the layout is selected.
The following log entry shows a typical XML formatting error. The line and column numbers indicate the location of the error.
Layout Validation Errors
These errors behave the same as XML errors but occur only when the SmartArt engine attempts to run a layout. The following log entry shows an error that occurs when two layout nodes have the same name attribute.
Design Errors
After the graphic layout file successfully loads, check for design errors. These errors do not show up in the log file but will be visible in the graphic. Common design errors include the following:
Text does not show up in the appropriate shape.
Some text is not displayed in any shape.
Shape size or font sizes are not consistent across shapes.
Shapes are not positioned correctly.
As you add shapes, the graphic does not react the way you expect.
Often, correcting design errors is a process of trial and error, ending when the graphic meets your needs. When you test a graphic layout, explore how it looks with various SmartArt styles and colors and across different themes. Not every graphic will look good with every style and color.
For more information, see Create Custom SmartArt Graphics for Use in the 2007 Office System.