How to use the presetShapeDefinitions.xml file and fun with DrawingML.
This article deals with the content contained in ECMA-376 Part 1. The 3rd edition of ECMA-376 was released in June of 2011 and can be downloaded from the following location: http://www.ecma-international.org/publications/standards/Ecma-376.htm
Where can I get the presetShapeDefinitions.xml file?
- Download ECMA-376 3rd edition Part 1 and unzip the contents into an empty folder. You should see a .pdf file and 5 more .zip files.
- Unzip the contents of the OfficeOpenXML-DrawingMLGeometries.zip file into the same folder.
- Open the presetShapeDefinitions.xml file in the XML file editor of your choice. If you don't have a dedicated XML file editor, most basic text editors (Notepad) should be able to open and display the file contents.
What am I supposed to do with this?
That's completely up to you. But here's a few ideas…
- Maybe you are writing an open source word processor for another platform that can read .docx files and you need to be able to draw the shape associated with a <prstGeom> (§220.127.116.11) element. The shape doesn't look right and you are questioning whether or not there is a problem with the definition.
- You could be creating a custom template for PowerPoint and you want to modify one of the existing shapes beyond what is available in the format options.
For the purposes of this blog, I will focus on the second scenario.
How do I do that?
In short, any shape definition from the presetShapeDefinitions.xml file can be used within a <custGeom> (§18.104.22.168) element. Sounds easy, right? Well, it is! Here's how to do it:
- Create a new Microsoft PowerPoint 2010 presentation, delete the 2 title placeholders, and drop any shape you want onto the slide. I will use the 'Moon' shape for demonstration purposes.
- Save the presentation as 'MyShapeTest.pptx'.
- Close Microsoft PowerPoint.
- Rename the file to 'MyShapeTest.zip'.
Wait a second! Why are we renaming the file with a .zip extension? You may have heard that starting with Office 2007 the files that end with 'x', such as .docx, .xlsx, and .pptx are actually zip-compressed packages containing a collection of XML files. Well, you can take that at face value and rename any of those file types with a .zip extension and then open it in your un-zipper of choice and browse the contents, which is exactly what we are going to do.
- Extract the contents of the MyShapeTest.zip file.
- Open the file "ppt\slides\slide1.xml" in a text editor or a dedicated xml file editor.
- Note: If the file opens automatically in Internet Explorer or another browser you may need to use the "Open with…" option.
- Locate the <a:prstGeom prst="moon"> element and its associated </a:prstGeom> element.
- Make the following changes:
- Replace <a:prstGeom prst="moon"> with <a:custGeom>.
- Replace </a:prstGeom> with </a:custGeom>.
- Replace the <a:avLst/> element that exists between the two custGeom elements with the contents of the Moon definition from the presetShapeDefinitions.xml file. DO NOT include the <moon> and </moon> elements.
- Save and close the slide1.xml file.
- Replace the slide1.xml file in the zip-compressed package with the modified version of the file.
- Note: DO NOT re-zip the contents of the MyShapeTest folder. You MUST replace the modified file in the original .zip file.
- Rename the file back to 'MyShapeTest.pptx' and open it with Microsoft PowerPoint.
- Note: If you get an error when opening the presentation you may have accidently changed something that you shouldn't have. Start over and try again.
When you open the file it should look exactly like it did before, but that's exactly the point. You replaced the reference to the shape with the actual definition. It's supposed to look the same.
What's the point?
Remember our 2 scenarios from the "What an I supposed to do with this" section above? Well, we've answered the first question of whether or not the definition is 'good'. If it wasn't, the shape would not have rendered correctly or you would have received an error stating something along the lines of "PowerPoint found a problem with content in MyShapeTest.pptx" when you tried to open the file.
If you're familiar with DrawingML you probably already realized that you can now modify the definition in the slide1.xml file. For those who are not familiar with DrawingML, here's something that you can change in the definition to make the moon a little more interesting.
- Follow steps 3 - 5 from above
- Locate the following line.
- <pathLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
- This is the List of Path Shapes, or the actual lines that are drawn to make the shape.
- Remove the following line from within the pathLst block.
- <arcTo wR="g18w" hR="dy1" stAng="stAng1" swAng="swAng1" />
- Replace it with this.
<pt x="wd2" y="hd2" /></lnTo>
- Follow steps 8-10 from above.
When you open the file you should see that the inside arc has been replaced with 2 straight lines from the moon's points to the center of the shape. In step 4 we only drew the first line. The second one is drawn automatically by the <close /> element.
Refer to ECMA-376 Part 1, Chapter 14 on DrawingML for more information on how to manipulate and draw your own custom shapes.