The {alias} macro allows you to create aliases (or shortcuts) for pages...

As you know, links to pages are easy to create by simply putting the page title in square brackets, but it can be a pain to do this sometimes.

For example, let say you have a page called "ACME device for catching Road Runners going through a tunnel" - having to type all that each time you want to link to a page can be a real pain:

[ACME device for catching Road Runners going through a tunnel]

It would be much easier if you could just create a shortcut called "Catch a Roadrunner" which could be linked to as follows:

[Catch a Roadrunner]

Alternatively you might want a page discussing animals to have aliases of Cats, Dogs, etc. Or you might want a page called Cats to also be linkable to using just Cat or Feline

That's exactly what this macro allows you to do - create one or more shortcuts to a page!

Before using this macro, we strongly recommend reading the Notes tab above to gain an understanding of how the macro actually works.

The {alias} macro has the following parameters:

{alias:name|parent=parent_page}

Parameters

Parameter	Required	Default	Notes
default			The default "name" parameter specifies the name of the alias, for example Catch a Roadrunner.
parent			By default, the alias page will not have any parent (it will be an [USERGUIDE:Orphan Page]. However, you can specify a parent page as follows: @self - the alias page will be attached to the destination page @parent - the alias page will be attached to the parent of the destination page page title - the alias page will be attached to the page with the specified title (must be in current space).

The {alias} macro works by creating a new page with the desired title within the same space as the page that the alias refers to.

This new page is, by default, an [USERGUIDE:Orphan Page] meaning that it has no parent. You can however, have it attached to a page of your choosing using the "parent" parameter.

Because a page has been created with the shorter or alternate title, it can obviously be linked to (including links from other spaces, etc).

When the user clicks a link that goes to the alias page, they are immediately redirected (using the redirect macro automatically inserted on to that page) to the target page on which you created the alias.

Because the redirect macro is being used on the new "shortcut" page, you need to be aware of the following:

• The redirect macro macro does not keep track of whether the target page has had its name changed and as such it's possible for the link to break which in turn breaks the alias
• The redirect macro uses JavaScript to redirect, so browsers with JavaScript turned off will require the user to manually click a link to take them to the target page.

This plug-in is available without cost for both commercial and non-commercial purposes. However, if you have found it to be useful, particularly within a commercial environment, please consider making a donation to the author. This will encourage continued development of this and other plug-ins, as well as speeding up the response for your latest maintenance request.

If you wish to donate, it can be done easily with a credit card or bank transfer using Paymate. No account sign-up is required for credit card payments.

This software is released under a BSD License

© 2005 David Peterson

This macro is compatible with Confluence 1.3.x, 1.4.x and 1.5.x. It has been tested by Adaptavist with Confluence 1.4.1, 1.4.3 and 1.4.4. It has been tested by David Peterson with Confluence 1.5-DR2.

This macro is usually pre-installed with Host accounts. If you wish to install it on your own Confluence install, please download it from the RandomBits.org website.

Adaptavist maintain a JIRA Project for tracking bug reports and feature requests for this macro. The currently reported items are shown below:

• redirect macro
• Online Documentation and Download

Basic Use - Creating an alias

To create an alias, simply use the macro on the target page (that the alias points to) as follows:

{alias:Catch a Roadrunner}

This creates a new [USERGUIDE:Orphan Page] called Catch a Roadrunner which can be linked to - anyone who views that page will instnatly be taken to the page from which the alias was created.

When you save the page after adding or changing an Alias, you'll see a message appear on the page confirming that the Alias has been added, etc. This will only appear once so only you will see it.

Multiple aliases to the same page

You can create multiple aliases for a page, simply by using the macro more than once, for example:

{alias:Cats}
{alias:Dogs}
{alias:Marmosets}

This would create three new pages (called Cats, Dogs and Marmosets) that redirect to the current page when accessed.

Custom parent page

It's generally a good idea to create the new alias pages off the page that they will link to (just to keep things tidy and make it a little more obvious what they relate to in the site map):

{alias:Cats|parent=@self}

This would create the Cats alias page hanging off the page that it will redirect to.

Alternatively, you can use the parent page of the target page, for example:

{alias:Dogs|parent=@parent}

This might be more desirable in some circumstances if the alias names are seemingly unrelated to the target page.

And finally, you can use any specific page as the parent page, for example:

{alias:Marmosets|parent=Home}

In the example above, the Marmosets page would be attached to the Home Page.

Removing an alias

To remove an alias, edit the page that contains the {alias} macro and simply delete the macro then save the page. You'll see a message stating that the alias has been removed and as when creating an alias this message will only appear once so you are the only person to see it.

Viewing or editing an alias page

To view an alias page, you need to alter the URL to that page manually...

Start by getting the URL to the page - for example, the URL to the page you are looking at now is:

http://www.adaptavist.com/display/USERGUIDE/alias+macro

Tip:
If there is a page that links to the alias page containing, you can right-click the link and choose Copy Shortcut or Copy Link Location (depending on which web browser you use).

To temporarily disable the redirect, add "?redirect=false" to the end of the URL, so in our example the URL would become:

http://www.adaptavist.com/display/USERGUIDE/alias+macro?redirect=false

This alias page would then be shown but would not redirect to the target page, allowing you to edit the page to make any changes or even remove the redirect.