New Window User Macro

Added by Bob Swift, last edited by Jonathan Nolen on Apr 17, 2007  (view change)

Make links open in a new window by embedding them in the New Window macro.

You can use the {link-window} macro in the Linking Plugin to achieve the same goal, but with more flexibility and security

Version History

Date Author Notes
Apr 13, 2005 Bob Swift Initial Release
Jun 01, 2005 Scott Frederick Fixed parameter numbering, allow URL to be passed as $body to avoid problems with GET vars
Jun 23, 2005 Günter Zöchbauer Made icon path dynamic
Aug 04, 2005 Mingyi Liu Added tooltip
Oct 18, 2005 Jeff Klassen Added JavaScript code to allow config of pop-up window
Oct 18, 2005 Guy Fraser Provided keyboard access and compatibility with older browsers:
  • Allows keyboard shortcuts to be used to "click" the link
  • Open in a popup window if JavaScript is supported by the user's browser and the browser can open links in a new window; or
  • Open in a new full featured browser window if the user's browser doesn't support JavaScript but can open links in a new window; or
  • Open in the current browser window if the user's browser doesn't support JavaScript and can't open links in a new window (or if the user has suppressed popup or new windows in their browser settings or through the use of additional software).

Overview

This user macro allows you to create links that open in a new window.

Inform your users to limit use of this macro to exceptional cases:

Related Jira Issues

http://jira.atlassian.com/browse/CONF-1986 seems to be the closest Jira issue tracking this feature.

Installation

  • You need to be a Confluence administrator with access to the Confluence server
  • Download the attached icon () and copy it to .../images/icons directory on the Confluence server
  • Go to Administration->User macros and add the code below as a user macro called newwindow
## Link using a new browser window

## parameter 0: is the text to use
## parameter 1: optional pop up tip (title)
## parameter 2: popup width (default=400)
## parameter 3: popup height (default=200)
## parameter 4: scrollbars? (yes/no) (default=yes)
## body: link

#set ($text = $param0)
#set ($icon = "${req.getContextPath()}/images/icons/new-win-icon.gif")

#if ($body)
  #set ($link = $body)
#else
  #set ($link = $text)
#end

#if ($param1)
  #set ($tip = $param1)
#else
  #set ($tip = "Visit page in new window")
#end

#if ($param2)
  #set ($width = $param2)
#else
  #set ($width = "400")
#end

#if ($param3)
  #set ($height = $param3)
#else
  #set ($height = "200")
#end

#if ($param4)
  #set ($scrollbars = $param4)
#else
  #set ($scrollbars = "yes")
#end

<script type="text/javascript"><!--
function popup(mylink, windowname) {
 if (!window.focus) return true;
 var href = (typeof(mylink) == 'string') ? mylink : mylink.href;
 window.open(href, windowname, 'width=$width,height=$height,scrollbars=$scrollbars');
 return false;
}
//--></script>

<a href="$link" title="$tip" target="_blank" onclick="return popup(this, '$tip')" onkeypress="return popup(this, '$tip')">
${text}<img src="$icon" class="rendericon" border="0" alt="$tip" /></a>

Usage

{newwindow:caption|title|width|height|scrollbars}url{newwindow}

Because parameters are not named, you should ensure that all preceeding parameters are specified.

Parameter Notes
caption The caption to display for the link on-screen
title The tooltip for the link and also the title of the launched window
width The width of the pop-up window
height The height of the pop-up window
scrollbars Set to "yes" (default) for scrollbars or "no" if you don't want scrollbars
url The URL to launch in the pop-up window

Examples

{newwindow:yahoo|yahoo main site}http://yahoo.com{newwindow}
{newwindow:yahoo|yahoo main site|800|600|no}http://yahoo.com{newwindow}

Labels

confluence14 confluence14 Delete
plugin plugin Delete
repository_excluded repository_excluded Delete
repository_excluded_by_user_macro repository_excluded_by_user_macro Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Comments (26)

 

  1. Jun 01, 2005

    Scott Frederick says:

    I had a few problems using this macro: 1. Apparently the parameter numbering c...

    I had a few problems using this macro:

    1. Apparently the parameter numbering changed in Confluence 1.4, so $param1 and $param2 had to be changed to $param0 and $param1

    2. The URL I was trying to pass in the second paramter contains an argument (e.g. http://www.someurl.com/page?arg=test). The "=" in the URL breaks the parsing such that the second paramter is not recognized. To work around this, I changed the macro so that the URL can be passed as a second parameter or in the body of the macro.

    So, my macro now looks like this: 

    ## Link using a new browser window
## parameter 0: is the text to use
## parameter 1: link (if blank, defaults to text)
## Example usage:
##  {newwindow:http://yahoo.com}
## or 
##  {newwindow:Yahoo|http://yahoo.com}
## or
##  {newwindow:Yahoo}http://yahoo.com{newwindow}

#set ($text = $param0)
#set ($icon = "/images/icons/new-win-icon.gif") 

## Set link to second parameter if it is defined, otherwise set to body if it is defined, otherwise to first parameter

#if ($param1)
  #set ($link = $param1)
#elseif ($body)
  #set ($link = $body)
#else
  #set ($link = $text)
#end

<a href="$link" target="_blank" title="Visit page in new window" > $text <img src="$icon" class="rendericon" border="0" alt="Visit page in new window"/></a>

    I also created an alternative icon that I think more closely matches the normal Confluence link icon. It is attached as new-win-icon2.gif.

  2. Jun 15, 2005

    Günter Zöchbauer says:

    had to change the following line #set ($icon = "/images/icons/new-win-icon.gif"...

    had to change the following line
    #set ($icon = "/images/icons/new-win-icon.gif")
    to
    #set ($icon = "/confluence/images/icons/new-win-icon.gif")
    because the URL to my confluence is http://localhost/confluence

    Is there a a variable available containing the base URL?

    1. Jun 15, 2005

      Mike Cannon-Brookes says:

      Günter, I believe the variable you're looking for is $baseurl - or something cl...

      Günter,

      I believe the variable you're looking for is $baseurl - or something close!

      Cheers,
      Mike

      1. Jun 20, 2005

        Günter Zöchbauer says:

        Hi Mike, thanks for your note. $baseurl doesn't work. Where can I find informa...

        Hi Mike,

        thanks for your note.
        $baseurl doesn't work.
        Where can I find information about preset values/variables?

        Cheers,
        Günter

        1. Jun 23, 2005

          Günter Zöchbauer says:

          Found it: #set ($icon = "${req.getContextPath()}/images/icons/new-win-icon.gi...

          Found it:

          #set ($icon = "${req.getContextPath()}/images/icons/new-win-icon.gif")

  3. Aug 04, 2005

    Mingyi Liu says:

    Very nice macro! I modified it slightly to allow tooltip (title): ## Link usi...

    Very nice macro! I modified it slightly to allow tooltip (title):

    ## Link using a new browser window, derived from the original newwindow

## parameter 0: is the text to use
## parameter 1: optional pop up tip (title)
## body: link
## Example usage:
##  {newwindow:yahoo|yahoo main site}http://yahoo.com{newwindow}

#set ($text = $param0)
#set ($icon = "/images/icons/new-win-icon2.gif")

#if ($body)
  #set ($link = $body)
#else
  #set ($link = $text)
#end

#if ($param1)
  #set ($tip = $param1)
#else
  #set ($tip = "Visit page in new window")
#end

<a href="$link" target="new" title="$tip" > $text <img src="$icon" class="rendericon" border="0" alt="new window icon"/></a>

    I want to note that the good style for using new window macros is to always put link in body to make sure links with '?' work.

    Right now I'm bothered that I could not get other confluence pages poped up in a new window - the new window macros work only on external links. Can it work on internal links (the easy way would be to have confluence process the link first to produce an url, then the macro put it into a href). I just couldn't find a function to do it.

    Any idea?

    Thanks!
    Mingyi

    1. Aug 04, 2005

      David Loeng says:

      This would be quite tricky to do. You'd have to first search for the Page object...

      This would be quite tricky to do. You'd have to first search for the Page object for that link, and then call getUrlPath().

      You're better bet is contructing the url with the spac key and the page title, provided the title consists only of ASCII characters.

      Cheers,
      Dave

  4. Oct 18, 2005

    Jeff Klassen says:

    I also found this macro useful. I created a version with a javascript to make th...

    I also found this macro useful. I created a version with a javascript to make the new window open as a popup. With this version you can specify the width and height of the popup, and whether scrollbars should be on/off.

    e.g. 

    {newwindow:yahoo|yahoo main site|800|600|no}http://yahoo.com{newwindow}

    ## Link using a new browser window, derived from the original newwindow

## parameter 0: is the text to use
## parameter 1: optional pop up tip (title)
## parameter 2: popup width (default=400)
## parameter 3: popup height (default=200)
## parameter 4: scrollbars? (yes/no) (default=yes)
## body: link
## Example usage:
##  {newwindow:yahoo|yahoo main site}http://yahoo.com{newwindow}
##  {newwindow:yahoo|yahoo main site|800|600|no}http://yahoo.com{newwindow}

#set ($text = $param0)
#set ($icon = "${req.getContextPath()}/images/icons/new-win-icon.gif")

#if ($body)
  #set ($link = $body)
#else
  #set ($link = $text)
#end

#if ($param1)
  #set ($tip = $param1)
#else
  #set ($tip = "Visit page in new window")
#end

#if ($param2)
  #set ($width = $param2)
#else
  #set ($width = "400")
#end

#if ($param3)
  #set ($height = $param3)
#else
  #set ($height = "200")
#end

#if ($param4)
  #set ($scrollbars = $param4)
#else
  #set ($scrollbars = "yes")
#end

<script type="text/javascript">
<!--
function popup(mylink, windowname)
{
if (! window.focus)return true;
var href;
if (typeof(mylink) == 'string')
   href=mylink;
else
   href=mylink.href;
window.open(href, windowname, 'width=$width,height=$height,scrollbars=$scrollbars');
return false;
}
//-->
</script>

<a href="$link" onClick="return popup(this, '$tip')" > $text <img src="$icon" class="rendericon" border="0" alt="new window icon"/></a>

    1. Oct 18, 2005

      Jeff Klassen says:

      Oops, the last line should be: <a href="$link" title="$tip" onClick="retu...

      Oops, the last line should be:

      <a href="$link" title="$tip" onClick="return popup(this, '$tip')" > $text <img src="$icon" class="rendericon" border="0" alt="new window icon"/></a>

      1. Oct 18, 2005

        Guy Fraser says:

        To make the link more accessible and also allow it to work on browsers with JS t...

        To make the link more accessible and also allow it to work on browsers with JS turned off, would it be worth doing something like this:

        <a href="$link" title="$tip" target="_blank" onclick="return popup(this, '$tip')" onkeypress="return popup(this, '$tip')">${text}<img src="$icon" class="rendericon" border="0" alt="$tip"/></a>

        NB: "onclick" should be all lowercase for XHTML compliancy.

        The benefits of this tweak are:

        • Allows keyboard shortcuts to be used to "click" the link
        • Open in a popup window if JavaScript is supported by the user's browser and the browser can open links in a new window; or
        • Open in a new full featured browser window if the user's browser doesn't support JavaScript but can open links in a new window; or
        • Open in the current browser window if the user's browser doesn't support JavaScript and can't open links in a new window (or if the user has suppressed popup or new windows in their browser settings or through the use of additional software).

        Would it also be worth having $param5 used to specify an accesskey? If specified, the accesskey="$param5" attribute could be added to the <a> tag thus allowing a keyboard shortcut to be used...?

        1. Oct 18, 2005

          Guy Fraser says:

          We're never sure if authors are keen on people changing their work I'll update...

          We're never sure if authors are keen on people changing their work I'll update the main page...

          1. Oct 18, 2005

            Dan Hardiker says:

            The general rule of thumb is; if you can edit it - and you have something to con...

            The general rule of thumb is; if you can edit it - and you have something to contribute that you feel would improve the content of the page - then edit away! It can always be rolled back!

  5. Oct 18, 2005

    Guy Fraser says:

    Ok, I've updated the main page with the latest version, added version history, a...

    Ok, I've updated the main page with the latest version, added version history, a usage guide and some other stuff.

    Should we delete all these comments now?

    1. Oct 18, 2005

      Bob Swift says:

      Wow, very nice!  Thanks for doing this.  How about letting each au...

      Wow, very nice!  Thanks for doing this.  How about letting each author remove their own comments once they verify they are no longer relevant?  I can check back in a few days and do some additional cleanup if necessary.

    2. Dec 23, 2005

      Mingyi Liu says:

      Nice job! I don't mind that my comment being deleted. The comments on this pag...

      Nice job! I don't mind that my comment being deleted. The comments on this page are getting a bit too long, especially since you nicely documented everything anyway. Thanks!

  6. Oct 18, 2005

    Bob Swift says:

    I think we still need the ability to create a new (full function) browser window...

    I think we still need the ability to create a new (full function) browser window as well as the ability for a popup.  I was thinking of adding another parameter, but I think it makes more sense to have 2 separate macros. For example newwindow and popup. An alternative would be to go to the popup if any of the popup parameters are specified (but this would force one of them to be specified before you get the popup behavior.  Comments before I update the page?

    1. Oct 18, 2005

      Guy Fraser says:

      It might be worth moving this macro to the next stage - a proper plugin with nam...

      It might be worth moving this macro to the next stage - a proper plugin with named parameters....

      1. Oct 18, 2005

        David Peterson [CustomWare] says:

        You could add it to the [Linking Macros] if you want to save on having a...

        You could add it to the [Linking Macros] if you want to save on having a whole new plugin package. I haven't quite gotten it into subversion yet, but I will be happy to do a manual merge, if you want to go that way. Alternately, you could also just put it in it's own plugin... Bob?

        1. Oct 19, 2005

          Bob Swift says:

          If we go the plugin route, then, yes it would probably be better to include as y...

          If we go the plugin route, then, yes it would probably be better to include as you suggested.   Let me think on that for a while - nice things about user macros are easy ability to customize and no upgrade customization/incompatibility (usually!) as long as they are kept simple (few or no parameters).

          1. Oct 19, 2005

            Guy Fraser says:

            I must concur, user macros are a dream when it comes to community development an...

            I must concur, user macros are a dream when it comes to community development and fine tuning because they are so easy to work with - you just edit the text, test, bug fix and voila!

            I've found that a lot of people look down on user macros because they consider them to be "toys", but I use them all the time. I've got a whole plethora of user macros doing all kinds of weird and wonderful things (some of which are uploaded to Macros).

            However, I think this user macro is getting to the upper limit of managability in terms of the parameters - would it be worth getting the last few tweaks made with the macro above (or a wishlist) and then seeing if it's worth making the plugin version?

            1. Apr 03, 2006

              Shannon Krebs - Adaptavist says:

              Another benefit of adding this macro into a proper plugin is the parameters can ...

              Another benefit of adding this macro into a proper plugin is the parameters can be documented for users on the help page rather then linking back to this page or maintaining your own.

  7. Oct 30, 2006

    Eric Bardoux says:

    It seems that it does not work with attachements...

    It seems that it does not work with attachements...

  8. Nov 08, 2006

    Derek Nicol says:

    Has this been moved into a plugin yet?

    Has this been moved into a plugin yet?

    1. Feb 12, 2007

      David Peterson [CustomWare] says:

      I've added this to the latest version of the Linking Plugin. It's called {link-w...

      I've added this to the latest version of the Linking Plugin. It's called {link-window}, partly to avoid clashing, partly to fit better with the existing macros in that library, and partly because it's mostly new code anyway...

  9. Nov 02, 2007

    Mattias Jansson says:

    As a new user of Confluence I found a problem when adding this Macro to our site...

    As a new user of Confluence I found a problem when adding this Macro to our site. When a new browser is opened and I choose to go back to the confluence window where the link was and I try to do something, I get the Confluence login page and have to login again. What can be the reason?

    1. Nov 05, 2007

      Choy Li Tham says:

      Hi Mattias, I realize that you have been created a support issue at our Support...

      Hi Mattias,

      I realize that you have been created a support issue at our Support system:

      Hence, please follow up the issue from there. Thanks.

      Regards,
      Choy Li