earmin/mendeleymacros

Mendeley macros

Macros used with Microsoft Word to add new functionalities to Mendeley's plugin.

Functionalities:

• Generates hyperlinks for citations pointing to corresponding reference in the bibliography generated by Mendeley's plugin. It supports IEEE and APA CSL citation styles.
• Maintains Microsoft Word style of the bibliography generated by Mendeley's plugin when refreshing it.

Author

José Luis González García

Macros

GAUG_removeHyperlinksForCitations(strTypeOfExecution As String)

Removes all hyperlinks generated for the citations from the document and leaves all fields as originally inserted by Mendeley's plugin. It also removes all bookmarks generated in the bibliography.

The parameter strTypeOfExecution can have one of three different values:

• "RemoveHyperlinks": UNEXPECTED RESULTS IF MANUAL MODIFICATIONS EXIST, BUT THE FASTEST. Removes the bookmarks and hyperlinks. Manual modifications to citations and bibliography will remain intact. This value CANNOT be used if the square brackets are part of the hyperlinks in the IEEE CSL citation style.
• "CleanEnvironment": EXPERIMENTAL, BUT VERY FAST. Removes the bookmarks and hyperlinks. Manual modifications to citations and bibliography will also be removed to have a clean environment
• "CleanFullEnvironment": SAFE, BUT VERY SLOW IN LONG DOCUMENTS. Removes the bookmarks and hyperlinks. Manual modifications to citations and bibliography will also be removed to have a clean environment.

Important: It works ONLY with the IEEE and APA CSL citation styles installed with Mendeley. It MAY not work if you make manual modifications to the citation fields, bibliography or both IEEE and APA CSL citation styles.

NOTE: strTypeOfExecution="RemoveHyperlinks" is the way to go; it is reliable and fast. In case of manual modifications to the citations or bibliography, the hyperlinks may not be created or linked correctly. If previous approach did not work, use strTypeOfExecution="CleanEnvironment"; also fast but still considered as EXPERIMENTAL. It executes a very light weight version of Mendeley's function Mendeley.undoEdit to remove the hyperlinks and manual modifications from the citations. If you want to be in the safe side, use strTypeOfExecution="CleanFullEnvironment" which calls Mendeley's functions to do the job. The execution with the last option may take several minutes; use it with caution. Mendeley is slow when undoing changes to citation fields. This function is also called when creating hyperlinks for IEEE and APA citation styles.

GAUG_removeHyperlinks

Wrapper for GAUG_removeHyperlinksForCitations("RemoveHyperlinks").

GAUG_cleanEnvironment

Wrapper for GAUG_removeHyperlinksForCitations("cleanEnvironment").

GAUG_cleanFullEnvironment

Wrapper for GAUG_removeHyperlinksForCitations("cleanFullEnvironment").

GAUG_createHyperlinksForCitationsAPA

Creates the bookmarks in the bibliography as well as the hyperlinks for the citations in the whole document.

Requires: GAUG_removeHyperlinksForCitations(strTypeOfExecution As String)

Important: It works ONLY with the APA CSL citation style installed with Mendeley. It MAY not work if you make manual modifications to the citation fields, bibliography or APA CSL citation style.

GAUG_createHyperlinksForCitationsIEEE

Creates the bookmarks in the bibliography as well as the hyperlinks for the citations in the whole document.

Requires: GAUG_removeHyperlinksForCitations(strTypeOfExecution As String)

Important: It works ONLY with the IEEE CSL citation style installed with Mendeley. It MAY not work if you make manual modifications to the citation fields, bibliography or IEEE CSL citation style.

NOTE: There is a configuration flag used to prevent the square brackets from being part of the hyperlinks. The flag is in the Custom configuration section. Setting blnIncludeSquareBracketsInHyperlinks=True will include the square brackets as part of the hyperlinks. BE AWARE that Microsoft Word DOES NOT handle this kind of hyperlinks very well and it is not possible to remove them with the argument "RemoveHyperlinks" or the wrapper GAUG_removeHyperlinks.

GAUG_getUndoEditButton

This is a copy of the original macro installed with Mendeley located in Mendeley-1.16.1.dotm (file name depends on the version of Mendeley), but I could not call it from my own macros.

DEPRECATED. It is possible to call the original function; there is no need of having this copy anymore.

refreshDocument

This is a copy of the original macro installed with Mendeley located in Mendeley-1.16.1.dotm (file name depends on the version of Mendeley). It has been modified in order to keep the Microsoft Word style of the bibliography generated by Mendeley's plugin when refreshing it. Have a look at the three lines with the comment 'MabEntwickeltSich, you need to add them to the macro of your installation of Mendeley. Follow the installation instructions below.

But remember, this will only work if you used a Microsoft Word style for the bibliography. You can use a build-in style or create your own. If you made manual modifications to the format (font and paragraph) directly to the bibliography and then refresh it, it will go back to the original Microsoft Word style settings.

Important: This macro will NOT work out if its context. This is just to show what modifications have to be made to the original macro installed by Mendeley's plugin.

Installation

Copy the code to your Microsoft Word macros to install any of the GWDG_* macros. See note below if using a Mac!

The GWDG_* macros make use of regular expressions; hence you need to enable the RegExp object in Visual Basic for Applications. This can be done from the menu “Tools” | “References” and checking the box next to “Microsoft VBScript Regular Expressions 5.5”.

To install the refreshDocument macro you need to modify the original macro by inserting the three extra lines with the comment 'MabEntwickeltSich:

What you need to do is to open the file Mendeley-1.16.1.dotm (or Mendeley-word201*-1.16.1.dot on a Mac) located in C:\Program Files\Mendeley Desktop\wordPlugin (or /Applications/Mendeley Desktop.app/Contents/Resources/macWordPlugin/word201* on a Mac). Check your own installation, your version of Mendeley may be different. Then modify the macro:

Function refreshDocument(Optional openingDocument As Boolean = False) As Boolean

The macro is located in the module MendeleyLib. For this, you may have to enable macros for the document when you open it. You may also need to enable the “Developer” tab in Microsoft Word. Once you finish the modifications, save the changes and close Microsoft Word. Open Mendeley Desktop, uninstall the Microsoft Word plugin and reinstall it again for the changes to take effect.

A sad note for Mac users

The current versions of GAUG_createHyperlinksForCitationsAPA and GAUG_createHyperlinksForCitationsIEEE make use of regular expressions which are not available on Mac OS X. HOWEVER, there is hope if you need the hyperlinks for the IEEE CSL citation style. Commit 6289273 has an old version of GAUG_createHyperlinksForCitationsIEEE without regular expressions which you can still use. Follow the standard installation.

Usage

ALWAYS have a BACKUP COPY of your document BEFORE using these macros. GAUG_removeHyperlinksForCitations(strTypeOfExecution As String) is still considered as experimental.

Execute the desired macro. See also Extending/modifying the code.

My recommendation for a typical usage is to keep your document free of any manual modification to the bibliography or to the citations inserted by Mendeley, but you can merge the citations with the standard way provided by Mendeley: [1][2][3][4] becomes [1]-[4]. This also applies for the APA CSL citation style.

Keep also your document without the bookmarks and hyperlinks generated by these macros while editing. Generate them ONLY when you want to create the PDF file or when you are done with the edition. If you will edit the document again, remove all bookmarks and hyperlinks (generated by these macros) to prevent any conflict with Mendeley's plugin as the citation numbers (in IEEE) or text (in APA) may change.

It is important to note that GAUG_removeHyperlinksForCitations is very slow when strTypeOfExecution="CleanFullEnvironment". It uses Mendeley's code to restore the original citation fields and bibliography. It is also called from GAUG_createHyperlinksForCitationsAPA and GAUG_createHyperlinksForCitationsIEEE to have a clean environment before creating the bookmarks and hyperlinks.

Extending/modifying the code

In this moment the code is adapted to my own needs and to the structure of my document. Nevertheless, changing the code to fit other requirements is straight forward when you stick to the IEEE or APA CSL citation styles. Much more effort may be required to support a different CLS citation style; and I can confirm that a lot of effort was done to include APA.

My document is divided in sections (Microsoft Word sections) for the chapters and other parts that are included in the thesis. The bibliography is located in a section with the title “Bibliography” and style "Titre de dernière section” (custom Microsoft Word style for the title). The macros (to remove or create the hyperlinks) will try to find the bibliography in a section with this description. I did it this way to increase speed in long documents. If you want to remove this restriction and locate the bibliography in any section, simply replace the lines of code If blnFound Then with If blnFound Or True Then to force the macro to check every section for the bibliography. You may also need to change the name of the style “Titre de dernière section” in the macros or add it to Microsoft Word, otherwise it will produce an error.

Comments and suggestions are welcome.