Skip to end of metadata
Go to start of metadata

The Office Connector (also known as Word/DAV plugin) allows you to import from or edit pages in popular word processing applications such as MS Word and Open Office Writer. This tutorial shows how to add navigation links to these features.

Overview

The "Edit in Word" feature allows you to edit a wiki page using popular word processing applications. When you click the link, the page will open in the word processor (you'll sometimes be asked to log-in while doing this) and when you've made your changes simply save the document and the wiki page will be updated (you'll have to refresh the wiki pages to see the changes take effect).

The "Doc Import" feature allows you to import a word processor document in to a wiki page. This is useful when you have documents that contain formatting that's not possible using wiki markup - the document will be rendered in your wiki page as close as is possible to the original, but not nessecarily exactly the same.

Important

The code snippets below have been split on to multiple lines to make them easier to read. When you are adding them to your theme layout please remember to put everything on a single line.

You must have the plugin installed before you can use these features. Also, please note that the links are different depending on your version of Confluence.

Edit In Word macro

The Office Connector plugin has a handy macro that you can drop in to any theme panel to add an "Edit in Word" link:

{editinwordlink}

You can see some examples in the Office Connector Support FAQ.

Confluence 2.8 and above

The way that the edit in word link is generated by the office connector code is not compatible with the builder menu system, to work around this we have duplicated and refined the office-connector's code and included it within builder (not the connector itself, but the code that calls it), to use the edit in word feature in a builder menu you will need Builder 3.3.0 or later and use the following syntax

{compound-menuitem:editInWord|icon=word|caption=Edit this %page% in word...}

Tip: You can use any of the menu icons available in Theme Builder if preferred.

To add the "Doc Import" link to your menu, use the following notation:

{compound-menuitem:webui
                  |location=system.content.action/secondary
                  |key=importworditem1
                  |caption=Doc Import}

Confluence 2.7 and earlier

The way that the edit in word link is generated by the office connector code is not compatible with the builder menu system, to work around this we have duplicated and refined the office-connector's code and included it within builder (not the connector itself, but the code that calls it), to use the edit in word feature in a builder menu you will need Builder 3.3.0 or later and use the following syntax

{compound-menuitem:editInWord|icon=word|caption=Edit this %page% in word...}

Tip: You can use any of the menu icons available in Theme Builder if preferred.

To add the "Doc Import" link to your menu, use the following notation:

{compound-menuitem:webui
                  |location=system.page
                  |key=importworditem
                  |caption=Doc Import}

Adding the links to the Edit menu

Go in to the Layout Manager and click on the Menus Tab:

Click on the "Edit" button in the "Menu Shortcut Macros" section and then click on the "Edit Menu" tab of the window that appears:

Add the appropriate macros based on the version of Confluence you are using (see above) and then click the "OK" button to confirm the changes.

Save your layout (click the

Unknown macro: {menuicon}

button - see Layout Manager for more details) and you should see the new links appear in the Edit menu.

Adding text hyperlinks (outside of a menu)

To add text hyperlinks outside of a menu, eg. in a sidebar, just add the "flat=true" parameter to the compound-menuitem macro, for example:

{compound-menuitem:webui
                  |location=system.content.action/primary
                  |key=editinworditem3
                  |icon=page_white_word
                  |caption=Edit in Word
                  |flat=true}
  • No labels

22 Comments

  1. Unknown User (nana)

    The edit in word link to macro given for 2.8 and above does not work

    Unknown macro: {compound-menuitem}

    I copied it exactly as shown.

    1. Unknown User (jking@phelon.com)

      Same here. The "Edit in Word" macro launches the file, but the instructions for adding the "Edit in Word" link to a Confluence 2.8 menu does absolutely nothing.

      1. Unknown User (gfraser)

        Adaptavist are currently investigating this problem, with the assistance of Ryan Ackley (the plugin author). It seems that there are issues with the links generated by the plugin in Confluence 2.8 which prevent the link from functioning properly in custom themes.

        We'll update this page with more information as it becomes available.

        1. Unknown User (theosophe74)

          The Office Connector for Confluence also cannot be integrated into the menus of Confluence 2.7 or earlier either.

          I tested it within an instance running Confluence 2.5.7, Theme Builder 2.0.9, and Office Connector 1.3.6.

          Attempting to use any of the following three menu items resulted in no menu item being displayed, and no errors being reported in the Atlassian Confluence log:

          {menuitem}{menulink:webui|location=system.page.actions|key=editinworditem1}Edit in Word{menulink}{menuitem}
          
          {menuitem}{menulink:webui|location=system.page|key=editinworditem2}Edit in Word{menulink}{menuitem}
          
          {menuitem}{menulink:webui|location=system.content.action/primary|key=editinworditem3}Edit in Word{menulink}{menuitem}
          

          Is there any chance that you and Ryan can also determine why none of the above menu items will appear in Confluence 2.7 or earlier?

        2. Unknown User (ryan)

          Guy, can you file a bug in JIRA if you understand the issue.

          http://developer.atlassian.com/jira/browse/WORDDV

          I have no idea why this wouldn't be working. Is it something wrong with the javascript that themebuilder is having trouble with?

          1. Unknown User (gfraser)

            It's the same problem that's being discussed in the ticket we've added you to on our tracker (StatPro). I think Alain recently added some more info to that ticket for your review?

            Also, are you at AtlasCamp? If so, maybe we can sit down together and find a solution?

            1. Unknown User (ryan)

              I don't see any information besides

              There are appear to be quite a few problems with the office connector ...

              Am I overlooking something? Is anyone able to get the OC interface items to show up? Can you verify whether or not this is happening for all builder users?

              1. Unknown User (gfraser)

                It's happening for all Builder users and also several customers who are using other themes (eg. custom java theme plugins).

                One workaround temporarily is to add the {editinwordlink} macro to the title panel or call it from velocity in a custom java theme plugin.

                1. Unknown User (ryan)

                  How do I get a copy of themebuilder 3? If this is a problem with theme builder you owe me a beer...

                  Unfortunately, I probably won't be at AtlasCamp to collect. I just moved to Sydney. I can't see them sending me back so soon.

                  1. Unknown User (theosophe74)

                    Here is what I have learned thus far in a Confluence 2.5.7, Builder 2.0.9, Connector 1.3.6 environment:

                    1. I actually can get the "Edit in Word" menu item to display without an image if I use the following syntax:
                      {menuitem}{menulink:webui|location=system.page.actions|key=editinworditem1}Edit in Word{menulink}{menuitem}
                      
                      • This was being hidden by the fact that I was using the wrong syntax to display the accompanying image.
                    2. I can see the "Edit in Word" menu item with the "editinword" image if:
                      1. I unzip the entire contents of the connector plugin JAR file to a directory using WinZip.
                      2. I create a GIF equivalent for the editinword.png file.
                        • We've configured all of our themes to not use PNG images, as their apparent larger size when compared to GIFs slows the rendering of the top menu bar to a crawl.
                          • We did this through the setting: Configure Theme -> Options -> Modify Menu Options -> Display menus as quickly as possible (faster page loads, inhibits use of PNG icons)
                      3. I edit the connector's atlassian-plugin.xml to add the following line for the "editinworditem1" web-item:
                         	<resource type="download" name="editinword.gif" location="templates/extra/editinword/editinword.gif"/>
                        
                      4. I update my menuitem to add the following menuicon declaration:
                        {menuitem}{menuicon:../../com.atlassian.confluence.extra.officeconnector:editinworditem1/editinword}{menulink:webui|location=system.page.actions|key=editinworditem1}Edit in Word{menulink}{menuitem}
                        
                        • Yes, there is probably a security risk in allowing upward navigation in the menuicon macro, but our Prod Support team is the only group who has permission to change the menu bar, as it is {import}ed into the theme via a view-only Confluence page.
                        • FYI, the importworditem probably always worked, and I define it as follows:
                          {menuitem}{menuicon:../../com.atlassian.confluence.extra.officeconnector:editinworditem1/editinword}{menulink:webui|location=system.page|key=importworditem}Import from Word{menulink}{menuitem}
                          
                          • Yes, I'm using the same icon for both edit and import, but there isn't an icon for import yet, so feel free to vote on the enhancement request.
                      5. I re-zip the contents of the unzipped folder into a JAR file using Java's jar utility (using WinZip doesn't work).
                      6. I install the updated JAR file into the Confluence Administrative Console.
                    3. Even with the "Edit in Word" menu item now showing along with its icon, when I click on the menu item, the only thing that happens is that the URL in the browser's address bar changes from:
                      http://www.mywikisite.com/display/MYSPACE/My+Wiki+Page
                      
                      to:
                      http://www.mywikisite.com/display/MYSPACE/My+Wiki+Page#" onclick="if (window.ActiveXObject){var ed; try{ed = new ActiveXObject(
                      
                      • That's because Adaptavist Theme Builder renders links generated by menu items using single quotes for the href attribute instead of double quotes, like so:
                        <a href='#onclick="if (window.ActiveXObject){var ed; try{ed = new ActiveXObject('SharePoint.OpenDocuments'
                        
                      • So the link actually rendered in the browser never gets past that second single quote shown above.
                      • I tried changing the link child element of the "editinworditem1" web-item element to use a ' instead of a " to close off the #, to use a single quote for the start of the onclick logic, and to use double quotes inside of the onclick logic to prevent premature logic termination.
                        • Both the href and the onclick attributes of the link in the rendered HTML's source appeared to look right now, but when I clicked on the menu item, the only thing that happened is that a # character is added to the end of my URL.
                        • I'm not sure what the problem is, but when I try as a work-around to use javascript: inside the href instead of #' onclick=', Internet Explorer tells me "'return' statement outside of function" and Firefox tells me "return not in function".
                  2. Unknown User (theosophe74)

                    To figure out whether "return false;" statements were really needed when using the "javascript:" syntax, I exploded the JavaScript out into a readable form and removed the return statements:

                    if (window.ActiveXObject)
                    {
                        var ed;
                    
                        try
                        {
                            ed = new ActiveXObject("SharePoint.OpenDocuments");
                        }
                    
                        catch(err)
                        {
                            window.alert("Unable to create an ActiveX object to open the document. This is most likely because of the security settings for your browser.");
                        }
                    
                        if (ed)
                        {
                            ed.EditDocument("$helper.action.bootstrapManager.baseUrl$relUrl$ext", "Word.Document");
                        }
                        else
                        {
                            window.alert("Cannot instantiate the required ActiveX control to open the document. This is most likely because you do not have Office installed or you have an older version of Office.");
                        }
                    
                    }
                    else if (window.URLLauncher)
                    {
                        var wdFile = new URLLauncher();wdFile.open("$req.contextPath$relUrl$ext");
                    }
                    else if(window.InstallTrigger)
                    {
                        if(window.confirm("A plugin is required to use this feature. Would you like to download it?"))
                        {
                            InstallTrigger.install({"WebDAV Launcher": "$req.contextPath/download/resources/com.atlassian.confluence.extra.officeconnector:editinworditem1/webdavloader.xpi"});
                        }
                    }
                    else
                    {
                        window.alert("Internet Explorer or Firefox is required to use this feature");
                    }
                    

                    As you can see, because you do a sufficient amount of "if" tests and error checking, I don't think you would ever be sent down a path you should not go down based on your browser, etc.

                    So I packed up that version of the JavaScript, made that the logic to be executed after the "javascript:" call in all three web-items within atlassian-plugin.xml, re-JAR'ed the files, and re-installed the plugin JAR.

                    Now, when I click on "Edit in Word", in both Firefox and IE, the file is opened via WebDAV for editing, and I can apply changes, save them, and refresh the corresponding Wiki page to see them.

                    I ran into additional issues after reaching this point, but I don't think they're Theme Builder-related, so I have captured them as potential Office Connector issues:

  2. Unknown User (gfraser)

    Quick update: We've made some progress on the integration issues (still undergoing testing).

    One interim workaround is to add the {editinwordlink} in to one of your theme panels, outside a menu.

    We'll hopefully be posting details in the coming week as to how to get the links working from within a menu.

  3. Unknown User (theosophe74)

    I'm sorry I can't test it myself right now, but I'm pretty sure that "Import Doc" has the same limitations as "Edit in Word". You lose the same types of formatting, as it's saving it as an actual Wiki page.

    If you want the majority of the formatting to be preserved, you need to use the {viewfile} macro.

    A neat trick would be to define an "Import and Preserve" or similarly named menu link that creates a new Wiki page with the name of the Word document, uploads the Word document as an attachment to the page, and adds the line {\viewfile:Imported+Document+Name.doc} to the page before saving it and presenting it to the user.

    Thanks,
    Mike

    1. You would need to talk to the developer of the plugin (Unknown User (ryan)) about that.

      1. Unknown User (theosophe74)

        Can you update, though, the Overview section of this page to be reflective of what the "Doc Import" feature is actually capable of doing?

        I hope my comments on this page about implementing a work-around to the Builder / Office Connector mismatch were helpful in creating an "editInWord" menu item.

        Thanks,
        Mike

        1. Unfortunatley we do not have any control over the office connector code, you will need to speak to Unknown User (ryan) about any changes you would like made to that plugin.

          1. Unknown User (gfraser)

            1. Unknown User (theosophe74)

              I'm not asking for a Connector code change. I am asking for you to update your documentation to be accurate.

              You state:

              The "Doc Import" feature allows you to import a word processor document in to a wiki page. This is useful when you have documents that contain formatting that's not possible using wiki markup - the document will be accurately rendered in your wiki page.

              But the Office Connector Documentation for "Doc Import" states:

              There are many features that Word has that Confluence's wiki text can't support. Some of examples of these are:

              • Merged table cells
              • Nested tables
              • Ability to choose font families
              • Background colors for table cells
              • Text highlighting

              http://confluence.atlassian.com/display/CONFEXT/Document+Import+with+the+Office+Connector

  4. Unknown User (philip parkinson)

    You make reference to builder 3.2.2 in your documentation here, however the latest release is 3.2.1. Are you refering to your early release version?

    In any case having no luck with Builder 3.2.1 and the example menu macros.

    1. 3.2.2 has been bumped now to become 3.3.0 and is available through the Early Access Programme

  5. Unknown User (tstrugar@wwf.org.au)

    When you have time it would be great to have a new icon for this, word_edit, like the existing word icon just with a little pencil added next to it (like the other _edit icons).