{"id":2890,"date":"2016-03-19T04:37:12","date_gmt":"2016-03-19T04:37:12","guid":{"rendered":"http:\/\/www.ericwhite.com\/home2\/bm8qcmjy\/public_html\/blog\/?page_id=2890"},"modified":"2016-03-19T04:37:12","modified_gmt":"2016-03-19T04:37:12","slug":"inserting-an-image-into-a-bookmark-in-an-openxml-wordprocessingml-document","status":"publish","type":"page","link":"https:\/\/www.ericwhite.com\/blog\/inserting-an-image-into-a-bookmark-in-an-openxml-wordprocessingml-document\/","title":{"rendered":"Inserting an Image into a Bookmark in an OpenXML WordprocessingML Document"},"content":{"rendered":"

Bookmarks provide a convenient way in WordprocessingML to provide insertion points for various items, such as text, images, etc.  Previously, I have outlined how to programmatically retrieve<\/a> and replace<\/a> text within a bookmark.  In a recent project, a client wanted to use bookmarks as insertion points for one or more images.  Using with the replace bookmark text sample code as a starting point, I extended it to include image insertion.  There are a number of additional steps to create an Open XML
\npackage that contains a properly inserted image. The main points are described below and sample code is attached.<\/p>\n

In a recent screencast<\/a>, I discuss the mechanics of how images are handled in OpenXml.  At the end of that screencast, I show how to manually insert an image into a word document package.  In order to implement this in code, the following steps are performed:<\/p>\n

    \n
  1. Flatten the paragraphs<\/li>\n
  2. Create a resource ID for the image<\/li>\n
  3. Create the image XElement<\/li>\n
  4. Insert the image element into the bookmark<\/li>\n
  5. Move the bookmark<\/li>\n
  6. Create a new image part and stream the image into that part<\/li>\n<\/ol>\n

    Flattening the paragraphs<\/h2>\n

    Flattening the paragraphs is a technique that I use in order to simplify XML operations.  It creates temporarily invalid WordprocessingML, but is useful as an intermediate step.  For example, it is valid for bookmarks to span different levels in the XML hierarchy.  However, for inserting an image in between bookmark start and end tags, our job is significantly easier if the bookmarks are at the same level of hierarchy in the XML.   <\/p>\n

    Create a Resource ID for the Image<\/h2>\n

    The resource ID links the image part to the main document part. The only constraint for the image resource ID is that it must be unique.  To create a resource ID, the code uses a GUID, strips out the dashes and prepends the number with \u201cr\u201d.<\/p>\n

     <\/p>\n

    string<\/span> imageRId <\/span>=<\/span> <\/span>\"r\"<\/span> <\/span>+<\/span> <\/span>Guid<\/span>.<\/span>NewGuid<\/span>().<\/span>ToString<\/span>().<\/span>Replace<\/span>(<\/span>\"-\"<\/span>,<\/span> <\/span>String<\/span>.<\/span>Empty<\/span>);<\/span>  <\/span><\/pre>\n
     <\/p>\n
    Create the Image XElement<\/h2>\n
    There is no easy way to create the markup for the image other than hand-coding the image element tree.  In order to see this markup, I created a Word document, inserted an image, saved the document, opened it in the Open
    \nXML Package Editor Power Tool for Visual Studio 2010<\/a>, and then examined the markup for the image.  A fragment of the markup is shown below.  We can see that the markup for the image is below a w:r element and begins with the w:drawing element:<\/p>\n
     <\/p>\n
    <w:r><\/span>
      <\/span><w:drawing><\/span>
        <\/span><wp:inline<\/span> <\/span>distT<\/span>=<\/span>\"0\"<\/span>
                    <\/span>distB<\/span>=<\/span>\"0\"<\/span>
                    <\/span>distL<\/span>=<\/span>\"0\"<\/span>
                    <\/span>distR<\/span>=<\/span>\"0\"<\/span>><\/span>
          <\/span><wp:extent<\/span> <\/span>cx<\/span>=<\/span>\"2314575\"<\/span>
                      <\/span>cy<\/span>=<\/span>\"1647825\"<\/span> <\/span>\/><\/span>
          <\/span><wp:effectExtent<\/span> <\/span>l<\/span>=<\/span>\"0\"<\/span>
                            <\/span>t<\/span>=<\/span>\"0\"<\/span>
                            <\/span>r<\/span>=<\/span>\"0\"<\/span>
                            <\/span>b<\/span>=<\/span>\"0\"<\/span> <\/span>\/><\/span>
          <\/span><wp:docPr<\/span> <\/span>id<\/span>=<\/span>\"1\"<\/span>
                    <\/span>name<\/span>=<\/span>\"Image1\"<\/span> <\/span>\/><\/span>
          <\/span><wp:cNvGraphicFramePr><\/span>
            <\/span><a:graphicFrameLocks<\/span> <\/span>xmlns:a<\/span>=<\/span>\"http:\/\/schemas.openxmlformats.org\/drawingml\/2006\/main\"<\/span>
                                  <\/span>noChangeAspect<\/span>=<\/span>\"1\"<\/span> <\/span>\/><\/span>
          <\/span><\/wp:cNvGraphicFramePr><\/span><\/pre>\n
    Using the PowerTools for OpenXml<\/a> utility PtOpenXmlUtil.cs, which contains the intialized XName objects for WordprocessingML, I created an image element that produces similar image markup, as shown below.<\/p>\n
    XElement<\/span> imageElement <\/span>=<\/span>
        <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>W<\/span>.<\/span>drawing<\/span>,<\/span>
            <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>WP<\/span>.<\/span>inline<\/span>,<\/span>
                <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"distT\"<\/span>,<\/span> <\/span>\"0\"<\/span>),<\/span>
                <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"distB\"<\/span>,<\/span> <\/span>\"0\"<\/span>),<\/span>
                <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"distL\"<\/span>,<\/span> <\/span>\"0\"<\/span>),<\/span>
                <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"distR\"<\/span>,<\/span> <\/span>\"0\"<\/span>),<\/span>
                <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>WP<\/span>.<\/span>extent<\/span>,<\/span>
                    <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"cx\"<\/span>,<\/span> imageWidthExtent<\/span>),<\/span>
                    <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"cy\"<\/span>,<\/span> imageHeightExtent<\/span>)<\/span>
                <\/span>),<\/span>
                <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>WP<\/span>.<\/span>effectExtent<\/span>,<\/span>
                    <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"l\"<\/span>,<\/span> <\/span>\"0\"<\/span>),<\/span>
                    <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"t\"<\/span>,<\/span> <\/span>\"0\"<\/span>),<\/span>
                    <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"r\"<\/span>,<\/span> <\/span>\"0\"<\/span>),<\/span>
                    <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"b\"<\/span>,<\/span> <\/span>\"0\"<\/span>)<\/span>
                <\/span>),<\/span>
                <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>WP<\/span>.<\/span>docPr<\/span>,<\/span>
                    <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"id\"<\/span>,<\/span> <\/span>\"1\"<\/span>),<\/span>   
                    <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"name\"<\/span>,<\/span> name<\/span>)<\/span>                                        
                <\/span>),<\/span>
                <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>WP<\/span>.<\/span>cNvGraphicFramePr<\/span>,<\/span>
                    <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>A<\/span>.<\/span>graphicFrameLocks<\/span>,<\/span>
                        <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>XNamespace<\/span>.<\/span>Xmlns<\/span> <\/span>+<\/span> <\/span>\"a\"<\/span>,<\/span> A<\/span>.<\/span>a<\/span>),<\/span>
                        <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"noChangeAspect\"<\/span>,<\/span> <\/span>\"1\"<\/span>))<\/span>
                <\/span>),<\/span>
                <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>A<\/span>.<\/span>graphic<\/span>,<\/span>
                        <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>XNamespace<\/span>.<\/span>Xmlns<\/span> <\/span>+<\/span> <\/span>\"a\"<\/span>,<\/span> A<\/span>.<\/span>a<\/span>),<\/span>
                        <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>A<\/span>.<\/span>graphicData<\/span>,<\/span>
                            <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"uri\"<\/span>,<\/span> <\/span>Pic<\/span>.<\/span>pic<\/span>),<\/span>
                            <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>Pic<\/span>.<\/span>_pic<\/span>,<\/span>
                                <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>XNamespace<\/span>.<\/span>Xmlns<\/span> <\/span>+<\/span> <\/span>\"pic\"<\/span>,<\/span> <\/span>Pic<\/span>.<\/span>pic<\/span>),<\/span>
                                <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>Pic<\/span>.<\/span>nvPicPr<\/span>,<\/span>
                                    <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>Pic<\/span>.<\/span>cNvPr<\/span>,<\/span>
                                        <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"id\"<\/span>,<\/span> <\/span>\"0\"<\/span>),<\/span>
                                        <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"name\"<\/span>,<\/span> <\/span>\"\"<\/span>)<\/span>
                                    <\/span>),<\/span>
                                    <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>Pic<\/span>.<\/span>cNvPicPr<\/span>)<\/span>
                                <\/span>),<\/span>
                                <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>Pic<\/span>.<\/span>blipFill<\/span>,<\/span>
                                    <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>A<\/span>.<\/span>blip<\/span>,<\/span>
                                        <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>R<\/span>.<\/span>r <\/span>+<\/span> <\/span>\"embed\"<\/span>,<\/span> imageRId<\/span>)<\/span>
                                    <\/span>),<\/span>
                                    <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>A<\/span>.<\/span>stretch<\/span>,<\/span>
                                        <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>A<\/span>.<\/span>fillRect<\/span>)<\/span>
                                    <\/span>)<\/span>
                                <\/span>),<\/span>
                                <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>Pic<\/span>.<\/span>spPr<\/span>,<\/span>
                                    <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>A<\/span>.<\/span>xfrm<\/span>,<\/span>
                                        <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>A<\/span>.<\/span>off<\/span>,<\/span>
                                            <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"x\"<\/span>,<\/span> <\/span>\"0\"<\/span>),<\/span>
                                            <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"y\"<\/span>,<\/span> <\/span>\"0\"<\/span>)<\/span>
                                        <\/span>),<\/span>
                                        <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>A<\/span>.<\/span>ext<\/span>,<\/span>
                                            <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"cx\"<\/span>,<\/span> imageWidth<\/span>),<\/span>
                                            <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"cy\"<\/span>,<\/span> imageHeight<\/span>)<\/span>
                                        <\/span>)<\/span>
                                    <\/span>),<\/span>
                                <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>A<\/span>.<\/span>prstGeom<\/span>,<\/span>
                                    <\/span>new<\/span> <\/span>XAttribute<\/span>(<\/span>\"prst\"<\/span>,<\/span> <\/span>\"rect\"<\/span>),<\/span>
                                    <\/span>new<\/span> <\/span>XElement<\/span>(<\/span>A<\/span>.<\/span>avLst<\/span>)<\/span>
                                <\/span>)<\/span>
                            <\/span>)<\/span>
                        <\/span>)<\/span>
                    <\/span>)<\/span>
                <\/span>)<\/span>
            <\/span>)<\/span>
    <\/span>);<\/span><\/pre>\n
    There are several input parameters for this image element: the image dimensions, the dimensions of the space reserved for the image (extent), and the resource ID.  The image name is not critical as the image part is referenced by the resource ID, not the image name.<\/p>\n
    The height and width of the image and the dimensions reserved for it are defined by the attributes in the A:ext and wp:extent elements, respectively.  These values are in EMUs, English Metric Units, where 1 EMU = 1\/914400 inch = 1\/360000 cm.  In this sample code, the image to be inserted is passed in as a Bitmap object.  The methods that return the width and height for a Bitmap object return the values in a different unit, where 1 unit = 1\/96 inch.  Thus, the Bitmap image width and height are first converted into EMUs and then assigned as attribute values in the A:ext and wp:extent elements.   <\/p>\n
    To understand how these dimensions effect the layout, see the examples below:<\/p>\n
    \"<\/p>\n\n\n\n\n\n
    \n
    Image Size, Extent<\/p>\n<\/td>\n
    		\n
    Example 1<\/p>\n<\/td>\n
    		\n
    Example 2<\/p>\n<\/td>\n
    		\n
    Example 3<\/p>\n<\/td>\n<\/tr>\n
    \n
    <<\/span>a:ext<\/span>     <\/span><\/p>\n<\/td>\n
    		\n
    cx<\/span>=<\/span>“2400000<\/span>“<\/span><\/p>\n
    cy<\/span>=<\/span>“1600000<\/span>“ \/><\/span><\/span><\/p>\n<\/td>\n
    		\n
    cx<\/span>=<\/span>“2400000<\/span>“<\/span><\/p>\n
    cy<\/span>=<\/span>“800000<\/span>“ \/><\/span><\/span><\/p>\n<\/td>\n
    		\n
    cx<\/span>=<\/span>“2400000<\/span>“<\/span><\/p>\n
    cy<\/span>=<\/span>“1600000<\/span>“ \/><\/span><\/span><\/p>\n<\/td>\n<\/tr>\n
    \n
    <<\/span>wp:extent <\/span><\/p>\n<\/td>\n
    		\n
    cx<\/span>=<\/span>“2400000<\/span>“
    \n  cy<\/span>=<\/span>“1600000<\/span>“ \/><\/span><\/span><\/p>\n<\/td>\n
    		\n
    cx<\/span>=<\/span>“2400000<\/span>“
    \n  cy<\/span>=<\/span>“1600000<\/span>“ \/><\/span><\/span><\/p>\n<\/td>\n
    		\n
    cx<\/span>=<\/span>“1200000<\/span>“
    \n  cy<\/span>=<\/span>“800000<\/span>“ \/><\/span><\/span><\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Notice in Example 2 that when the image size is smaller than
    \nthe space reserved for it (extent), then the space is left unfilled.  And when
    \nthe extent dimensions are smaller than the image size, the image is squeezed
    \ninto the extent space, as shown in Example 3. <\/p>\n
    After this image element has been instantiated, it is
    \ninserted between the bookmark start and end elements. <\/p>\n
    Move the Bookmark<\/h2>\n
    The client requested to be able to insert multiple images at
    \nthe same bookmark.  Because the image is inserted between w:bookmarkStart and
    \nw:bookmarkEnd, one of these needed to be moved adjacent to the other. 
    \nOtherwise the current image would be replaced by the new one.  By moving the w:bookmarkEnd
    \nto after the w:bookmarkStart and before the image markup, the next image added
    \nvia the method call to the same bookmark moves the existing image(s) to the right.<\/p>\n
    One important point about bookmark names in Word is that
    \nbookmark names are treated as case-insensitive within Word.  That is, you
    \ncannot create bookmarks by name \u201cA\u201d and \u201ca\u201d; only one will be accepted.   So
    \nwhen we work with bookmarks within code, we convert the bookmark name to
    \nuppercase to eliminate case-sensitivity.  For example:<\/p>\n
    XElement<\/span> bookmark <\/span>=<\/span> xDoc<\/span>.<\/span>Descendants<\/span>(<\/span>W<\/span>.<\/span>bookmarkStart<\/span>)<\/span>
       <\/span>.<\/span>FirstOrDefault<\/span>(<\/span>d <\/span>=><\/span> 
           <\/span>((<\/span>string<\/span>)<\/span>d<\/span>.<\/span>Attribute<\/span>(<\/span>W<\/span>.<\/span>name<\/span>)).<\/span>ToUpper<\/span>()<\/span> <\/span>==<\/span> bookmarkName<\/span>.<\/span>ToUpper<\/span>());<\/span><\/pre>\n
    Create a New Part and Stream the Image into that Part<\/h2>\n
    After adding the image element, the image part is created
    \nand then the image is streamed into that part.  In this example, the image to
    \nbe inserted at the bookmark is passed into the method as a Bitmap object: image<\/b>. 
    \nThe variable imageFormatForSave<\/b> specifies the format to save the image
    \npart as: e.g., ImageFormat.Png, ImageFormat.Jpeg, etc.  <\/p>\n
    Lastly, the document\u2019s root element is replaced with the new
    \nroot element with the image markup, and then that is put into the
    \nMainDocumentPart.<\/p>\n
    MainDocumentPart<\/span> mainPart <\/span>=<\/span> doc<\/span>.<\/span>MainDocumentPart<\/span>;<\/span>
    <\/span>ImagePart<\/span> imagePart <\/span>=<\/span> mainPart<\/span>.<\/span>AddImagePart<\/span>(<\/span>ImageElement<\/span>.<\/span>GetImagePartType<\/span> <\/span>(<\/span>imageFormatForSave<\/span>),<\/span> imageRId<\/span>);<\/span>
                
    <\/span>using<\/span> <\/span>(<\/span>MemoryStream<\/span> ms <\/span>=<\/span> <\/span>new<\/span> <\/span>MemoryStream<\/span>())<\/span>
    <\/span>{<\/span>
        image<\/span>.<\/span>Save<\/span>(<\/span>ms<\/span>,<\/span> imageFormatForSave<\/span>);<\/span>
        <\/span>byte<\/span>[]<\/span> ba <\/span>=<\/span> ms<\/span>.<\/span>ToArray<\/span>();<\/span>
        <\/span>using<\/span> <\/span>(<\/span>Stream<\/span> s <\/span>=<\/span> imagePart<\/span>.<\/span>GetStream<\/span>(<\/span>FileMode<\/span>.<\/span>Create<\/span>,<\/span> <\/span>FileAccess<\/span>.<\/span>ReadWrite<\/span>))<\/span>
            s<\/span>.<\/span>Write<\/span>(<\/span>ba<\/span>,<\/span> <\/span>0<\/span>,<\/span> ba<\/span>.<\/span>GetUpperBound<\/span>(<\/span>0<\/span>)<\/span> <\/span>+<\/span> <\/span>1<\/span>);<\/span>
    <\/span>}<\/span>
                    
    xDoc<\/span>.<\/span>Elements<\/span>().<\/span>First<\/span>().<\/span>ReplaceWith<\/span>(<\/span>newRoot<\/span>);<\/span>
    doc<\/span>.<\/span>MainDocumentPart<\/span>.<\/span>PutXDocument<\/span>();<\/span><\/pre>\n
    The sample code is attached.  It provides several test cases to show the functionality of the image insertion utility. <\/p>\n
    Download – Example Code<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
    Bookmarks provide a convenient way in WordprocessingML to provide insertion points for various items, such as text, images, etc.  Previously, I have outlined how to programmatically retrieve and replace text within a bookmark.  In a recent project, a client wanted to use bookmarks as insertion points for one or more images.  Using with the replace […]<\/p>\n","protected":false},"author":10567,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"_bbp_topic_count":0,"_bbp_reply_count":0,"_bbp_total_topic_count":0,"_bbp_total_reply_count":0,"_bbp_voice_count":0,"_bbp_anonymous_reply_count":0,"_bbp_topic_count_hidden":0,"_bbp_reply_count_hidden":0,"_bbp_forum_subforum_count":0,"_s2mail":"","footnotes":""},"class_list":["post-2890","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/www.ericwhite.com\/blog\/wp-json\/wp\/v2\/pages\/2890","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.ericwhite.com\/blog\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/www.ericwhite.com\/blog\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/www.ericwhite.com\/blog\/wp-json\/wp\/v2\/users\/10567"}],"replies":[{"embeddable":true,"href":"https:\/\/www.ericwhite.com\/blog\/wp-json\/wp\/v2\/comments?post=2890"}],"version-history":[{"count":1,"href":"https:\/\/www.ericwhite.com\/blog\/wp-json\/wp\/v2\/pages\/2890\/revisions"}],"predecessor-version":[{"id":2891,"href":"https:\/\/www.ericwhite.com\/blog\/wp-json\/wp\/v2\/pages\/2890\/revisions\/2891"}],"wp:attachment":[{"href":"https:\/\/www.ericwhite.com\/blog\/wp-json\/wp\/v2\/media?parent=2890"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}