{deck:id=Linking Plugin|width=907px}
{card:label=Overview}
h4. Linking Plugin
This plugin contains macros for linking to templates, the dashboard and other Confluence features.
h5. This plugin includes the following macros:
* *add-page* \- This will create a link on your page which, when clicked, is equivalent to clicking 'Add Page' on the Page Operations bar.
* *add-page-form* \- Creates a simple form on a page for users to enter the name of the new page to add.
* *child-countert* \- Allows display of the 'current' and 'next' Child Counter value, as well as the ability to disable or reset the value if required.
* *incoming-linksl* \- Generates a list of links of pages which link into this page.
* *link-page* \- This will create a link to a page, or a link to create a page based on a template and/or parent page.
* *link-to* \- Creates a link to special Confluence locations. All locations are case-insensitive.
* *link-window* \- Links to a page or URL, popping it up into a new window.
* *orphaned-links* \- Creates a list of pages which do not have any other pages linking to them.
* *outgoing-links* \- Creates a list of pages, websites and email addresses the current page links to.
* *undefined-links* \- Creates a list of pages which are linked to but have not yet been created.
{card}
{card:label=Documentation}
{deck:id=docs}
{card:label=add-page}
This will create a link on your page which, when clicked, is equivalent to clicking 'Add Page' on the Page Operations bar.
h4. The Code
{code}
{add-page:template=[template name]|live=true|parent=[<at:var at:name="self," />parent,@home,Page Name]}[link text]{add-page}
{code}
h4. {toggle-cloak:id=1} Parameters
{cloak:id=1}
||Name || Required || Default || Description ||
|| source | (x) | | (Since 2.11.0) The name of the template or page that is the source of the new page body content. |
|| type | (x) | template | (Since 2.11.0) Either 'template' or 'page', depending on what type of source is being used. |
|| parent | (x) | @self | The page you would like to be the parent of the new page. If no parent page is desired, set parent to a blank value. ie. 'parent='. Otherwise, set to 'Page Name' or 'SPACEKEY:Page Name'. There are also three special values:
* *@self* - sets the parent to the new page the macro appears in.
* *@parent* - sets the parent of the new page to the parent of the current page.
* *@home* - sets the parent of the new page to the home page of the current space. |
|| labels | (x) | | The list of labels to attach to the new page. Only works for live template pages. |
|| title | (x) | | If you want popup text to appear when the mouse is hovered over the link, enter it here. |
|| allowRename | (x) | false | (Since 2.4) If set to true, the user will be allowed to rename the page when it is being created. |
|| prefix | (x) | | (Since 2.8.0) The %injectable% prefix to apply to the page name. The user will not be able to modify this section of the name while creating it. Eg: 'prefix=%page:title% - ' will add the current page title plus ' - ' to the start of the page name. |
|| postfix | (x) | | (Since 2.8.0) The %injectable% postfix to apply to the page name. The user will not be able to modify this section of the name while creating it. Eg: 'postfix= - %page:title%' will add the current page title plus ' - ' to the end of the page name. |
|| template | (x) | | (Deprecated in 2.11.0) The name of the Template to use when creating the page. |
|| clonePage | (x) | | (Since 2.10.0; Deprecated in 2.11.0) The name of the page that will be cloned to create the new page. Note that the 'live' and 'template' parameters are not allowed in conjunction with this parameter. |
{cloak}
{card}
{card:label=add-page-form}
Very similar to the add-page macro, this will then create a new page, which may be based on a template if so desired.
h4. Code
{code}
{add-page-form:template=A Template|live=true}Add new page{add-page-form}
{code}
h4. {toggle-cloak:id=2} Parameters
{cloak:id=2}
||Name || Required || Default || Description ||
|| source | (x) | | (Since 2.11.0) The name of the template or page that is the source of the new page body content. |
|| type | (x) | template | (Since 2.11.0) Either 'template' or 'page', depending on what type of source is being used. |
|| parent | (x) | @self | The page you would like to be the parent of the new page. If no parent page is desired, set parent to a blank value. ie. 'parent='. Otherwise, set to 'Page Name' or 'SPACEKEY:Page Name'. There are also three special values:
* *@self* - sets the parent to the new page the macro appears in.
* *@parent* - sets the parent of the new page to the parent of the current page.
* *@home* - sets the parent of the new page to the home page of the current space. |
|| labels | (x) | | The list of labels to attach to the new page. Only works for live template pages. |
|| allowRename | (x) | false | (Since 2.4) If set to true, the user will be allowed to rename the page when it is being created. |
|| nameWidth | (x) | | If set, this specifies the width of the name text field. Can be any valid CSS width value, such as '300px' or '60%'. |
|| class | (x) | | (Since 2.6.5) Sets a class for the displayed form items. |
|| prefix | (x) | | (Since 2.8.0) The %injectable% prefix to apply to the page name. The user will not be able to modify this section of the name while creating it. Eg: 'prefix=%page:title% - ' will add the current page title plus ' - ' to the start of the page name. |
|| postfix | (x) | | (Since 2.8.0) The %injectable% postfix to apply to the page name. The user will not be able to modify this section of the name while creating it. Eg: 'postfix= - %page:title%' will add the current page title plus ' - ' to the end of the page name. |
|| template | (x) | | (Deprecated in 2.11.0) The name of the Template to use when creating the page. |
{cloak}
{card}
{card:label=child-counter}
When 'child counting' is enabled for a page, the plugin will keep track of how many children have been added to this page over time. This is different to the 'current page count', since it will not decrease when pages are deleted. This makes it useful for creating new pages with unique ID values which will never be duplicated.
h4. Code
{code}
{macro:current/next/disable/enable/reset X|source=[page name]}
{code}
h4. {toggle-cloak:id=3} Parameters
{cloak:id=3}
||Name || Required || Default || Description ||
|| default / action | (/) | current | May be one of the following:
* *current* - Outputs the current 'child count' value.
* *next* - Outputs the next 'child count' value (current + 1). Requesting this will also 'enable' child counting automatically.
* *enable* - Enables child counting. Will not reset the counter if it's already enabled.
* *disable* - Disables child counting and resets the counter.
* *reset* - Resets the current 'counter' value to 0.
* *reset to X* - Resets the current 'counter' value to the specified number. Must be positive.
|| source | (x) | @self | Specifies the page the macro should operate on. If specified to another page, this will perform the specified action on that page, if the current user has sufficient permissions. |
{note:title=Note}
It doesn't generally make much sense to use the 'operational' actions permanently on a page. For example, specifying 'reset to 100' on a page will constantly reset the counter to 100, not just the first time you save it. It may be simplest to add them in edit mode and Preview, then remove them again.
{note}
{cloak}
{card}
{card:label=incoming-links}
Generates a list of links of pages which link into this page.
h4. Code
{code}
{incoming-links:page=Another Page|types=page,comment}No links were found.{incoming-links}
{code}
h4. Examples
{code}
{incoming-links}No links exist{incoming-links}
{incoming-links:style=square|excerpt=true}
{incoming-links:scope=Another Page>children}
{incoming-links:scope=A Different Page>descendents}
{incoming-links:spaces=MYSPACE}
{incoming-links:page=Another Page|types=page,comment}
{code}
h4. {toggle-cloak:id=5} Parameters
{cloak:id=5}
||Name || Required || Default || Description ||
|| page | (x) | current location | The page to search on. |
|| spaces | (x) | current space | The spaces from which linked pages must come from. Spaces should be comma-separated. |
|| mode | (x) | lis | The mode in which incoming links are displayed. Available modes:
* *list* - Links are displayed in a bullet-pointed list.
* *flat* - Links are displayed in a single row, with a separator between each item. |
|| separator | (x) | comma | The style of separator to have. Defaults to ', ' when in flat mode. Available separators:
* *commas* - Each item is separated by a ', '
* *brackets* - Each item is surrounded by square brackets
* *braces* - Each item is surrounded by curly braces
* *parens* - Each item is surrounded by parentheses
* *pipe* - Each item is separated by a pipe ('|').
* *"other"* - The value inside the quotes is the separator. |
|| style | (x) | | The style of the bullet points. May be one of the following:
* *icons* - Displays the standard Confluence page-type icons
* *none* - No bullets displayed
* *CSS list-styles* - Any standard CSS list-style values are also allowed. Eg. 'disc', 'square', etc. |
|| maxResults | (x) | | The maximum number of results to display. |
|| name | (x) | | Parameter description goes here. |
|| excerpt | (x) | false | If 'true', any excerpt set for the page is displayed next to the link. |
|| types | (x) | any type | The types of pages to list. Must be a comma-separated list of any of the following:
* *page* - a standard page.
* *news* - a news item.
* *comment* - a page/news item comment.
* *spacedescription* - a space description.
* *userinfo* - the user's profile information details.
* *attachment* - an attachment.
* *mail* - an archived mail message.
* *mailto* - a 'mailto' link.
* *url* - an external link.
|| scope | (x) | | Allows the possible pages to be restricted to a specific page parent/child scope. More than one filter may be applied. Eg:
* scope=My Page>children - the direct children of 'My Page'
* scope=My Page>descendents - any descendents of 'My Page'.
* scope=My Page>ancestors, Other Page>ancestors - any ancestors of both 'My Page' and 'Other Page'.
|| labels | (x) | | Specify the labels a page may or may not have attached. Eg.
* labels=one, two - may have either 'one' or 'two' attached.
* labels=+one, +two - must have both 'one' and 'two' attached.
* labels=+one, -two - must have 'one', but not 'two' attached. |
{cloak}
{card}
{card:label=orphaned-links}
Creates a list of pages which do not have any other pages linking to them.
h4. Code
{code}
{orphaned-links:spaces=MYSPACE}
{code}
h4. Examples
{code}
{orphaned-links}No links exist{orphaned-links}
{orphaned-links:style=square|excerpt=true}
{orphaned-links:scope=Another Page>children}
{orphaned-links:scope=A Different Page>descendents}
{orphaned-links:spaces=MYSPACE}
{orphaned-links:types=page,comment}
{code}
h4. {toggle-cloak:id=6} Parameters
{cloak:id=6}
||Name || Required || Default || Description ||
|| page | (x) | current location | The page to search on. |
|| spaces | (x) | current space | The spaces from which linked pages must come from. Spaces should be comma-separated. |
|| mode | (x) | lis | The mode in which incoming links are displayed. Available modes:
* *list* - Links are displayed in a bullet-pointed list.
* *flat* - Links are displayed in a single row, with a separator between each item. |
|| separator | (x) | comma | The style of separator to have. Defaults to ', ' when in flat mode. Available separators:
* *commas* - Each item is separated by a ', '
* *brackets* - Each item is surrounded by square brackets ('[' and ']').
* *braces* - Each item is surrounded by curly braces ('{' and '}').
* *parens* - Each item is surrounded by parentheses ('(' and ')').
* *pipe* - Each item is separated by a pipe ('|').
* *"other"* - The value inside the quotes is the separator. |
|| style | (x) | | The style of the bullet points. May be one of the following:
* *icons* - Displays the standard Confluence page-type icons
* *none* - No bullets displayed
* *CSS list-styles* - Any standard CSS list-style values are also allowed. Eg. 'disc', 'square', etc. |
|| maxResults | (x) | | The maximum number of results to display. |
|| name | (x) | | Parameter description goes here. |
|| excerpt | (x) | false | If 'true', any excerpt set for the page is displayed next to the link. |
|| types | (x) | any type | The types of pages to list. Must be a comma-separated list of any of the following:
* *page* - a standard page.
* *news* - a news item.
* *comment* - a page/news item comment.
* *spacedescription* - a space description.
* *userinfo* - the user's profile information details.
* *attachment* - an attachment.
* *mail* - an archived mail message.
* *mailto* - a 'mailto' link.
* *url* - an external link.
|| scope | (x) | | Allows the possible pages to be restricted to a specific page parent/child scope. More than one filter may be applied. Eg:
* scope=My Page>children - the direct children of 'My Page'
* scope=My Page>descendents - any descendents of 'My Page'.
* scope=My Page>ancestors, Other Page>ancestors - any ancestors of both 'My Page' and 'Other Page'.
|| labels | (x) | | Specify the labels a page may or may not have attached. Eg.
* labels=one, two - may have either 'one' or 'two' attached.
* labels=+one, +two - must have both 'one' and 'two' attached.
* labels=+one, -two - must have 'one', but not 'two' attached. |
{cloak}
{card}
{card}
{card:label=outgoing-links}
Wiki content may be included as the body to be shown if no links exist.
h4. Code
{code}
{outgoing-links}No links exist{outgoing-links}
{code}
h4. Examples
{code}
{outgoing-links}No links exist{outgoing-links}
{outgoing-links:style=square|excerpt=true}
{outgoing-links:scope=Another Page>children}
{outgoing-links:scope=A Different Page>descendents}
{outgoing-links:spaces=MYSPACE}
{outgoing-links:types=page,comment}
{code}
h4. {toggle-cloak:id=7} Parameters
{cloak:id=7}
||Name || Required || Default || Description ||
|| page | (x) | current location | The page to search on. |
|| spaces | (x) | current space | The spaces from which linked pages must come from. Spaces should be comma-separated. |
|| mode | (x) | lis | The mode in which incoming links are displayed. Available modes:
* *list* - Links are displayed in a bullet-pointed list.
* *flat* - Links are displayed in a single row, with a separator between each item. |
|| separator | (x) | comma | The style of separator to have. Defaults to ', ' when in flat mode. Available separators:
* *commas* - Each item is separated by a ', '
* *brackets* - Each item is surrounded by square brackets
* *braces* - Each item is surrounded by curly braces
* *parens* - Each item is surrounded by parentheses
* *pipe* - Each item is separated by a pipe ('|').
* *"other"* - The value inside the quotes is the separator. |
|| style | (x) | | The style of the bullet points. May be one of the following:
* *icons* - Displays the standard Confluence page-type icons
* *none* - No bullets displayed
* *CSS list-styles* - Any standard CSS list-style values are also allowed. Eg. 'disc', 'square', etc. |
|| maxResults | (x) | | The maximum number of results to display. |
|| name | (x) | | Parameter description goes here. |
|| excerpt | (x) | false | If 'true', any excerpt set for the page is displayed next to the link. |
|| types | (x) | any type | The types of pages to list. Must be a comma-separated list of any of the following:
* *page* - a standard page.
* *news* - a news item.
* *comment* - a page/news item comment.
* *spacedescription* - a space description.
* *userinfo* - the user's profile information details.
* *attachment* - an attachment.
* *mail* - an archived mail message.
* *mailto* - a 'mailto' link.
* *url* - an external link.
|| scope | (x) | | Allows the possible pages to be restricted to a specific page parent/child scope. More than one filter may be applied. Eg:
* scope=My Page>children - the direct children of 'My Page'
* scope=My Page>descendents - any descendents of 'My Page'.
* scope=My Page>ancestors, Other Page>ancestors - any ancestors of both 'My Page' and 'Other Page'.
|| labels | (x) | | Specify the labels a page may or may not have attached. Eg.
* labels=one, two - may have either 'one' or 'two' attached.
* labels=+one, +two - must have both 'one' and 'two' attached.
* labels=+one, -two - must have 'one', but not 'two' attached. |
{cloak}
{card}
{card:label=undefined-links}
Creates a list of pages which are linked to but have not yet been created.
h4. Code
{code}
{undefined-links}No links exist{undefined-links}
{code}
h4. Examples
{code}
{undefined-links}No links exist{undefined-links}
{undefined-links:style=square|excerpt=true}
{undefined-links:scope=Another Page>children}
{undefined-links:scope=A Different Page>descenents}
{undefined-links:spaces=MYSPACE}
{undefined-links:types=page,comment}
{code}
h4. {toggle-cloak:id=8} Parameters
{cloak:id=8}
||Name || Required || Default || Description ||
|| page | (x) | current location | The page to search on. |
|| spaces | (x) | current space | The spaces from which linked pages must come from. Spaces should be comma-separated. |
|| mode | (x) | lis | The mode in which incoming links are displayed. Available modes:
* *list* - Links are displayed in a bullet-pointed list.
* *flat* - Links are displayed in a single row, with a separator between each item. |
|| separator | (x) | comma | The style of separator to have. Defaults to ', ' when in flat mode. Available separators:
* *commas* - Each item is separated by a ', '
* *brackets* - Each item is surrounded by square brackets
* *braces* - Each item is surrounded by curly braces
* *parens* - Each item is surrounded by parentheses
* *pipe* - Each item is separated by a pipe ('|').
* *"other"* - The value inside the quotes is the separator. |
|| style | (x) | | The style of the bullet points. May be one of the following:
* *icons* - Displays the standard Confluence page-type icons
* *none* - No bullets displayed
* *CSS list-styles* - Any standard CSS list-style values are also allowed. Eg. 'disc', 'square', etc. |
|| maxResults | (x) | | The maximum number of results to display. |
|| name | (x) | | Parameter description goes here. |
|| excerpt | (x) | false | If 'true', any excerpt set for the page is displayed next to the link. |
|| types | (x) | any type | The types of pages to list. Must be a comma-separated list of any of the following:
* *page* - a standard page.
* *news* - a news item.
* *comment* - a page/news item comment.
* *spacedescription* - a space description.
* *userinfo* - the user's profile information details.
* *attachment* - an attachment.
* *mail* - an archived mail message.
* *mailto* - a 'mailto' link.
* *url* - an external link.
|| scope | (x) | | Allows the possible pages to be restricted to a specific page parent/child scope. More than one filter may be applied. Eg:
* scope=My Page>children - the direct children of 'My Page'
* scope=My Page>descendents - any descendents of 'My Page'.
* scope=My Page>ancestors, Other Page>ancestors - any ancestors of both 'My Page' and 'Other Page'.
|| labels | (x) | | Specify the labels a page may or may not have attached. Eg.
* labels=one, two - may have either 'one' or 'two' attached.
* labels=+one, +two - must have both 'one' and 'two' attached.
* labels=+one, -two - must have 'one', but not 'two' attached. |
{cloak}
{card}
{card:label=link-page}
test
{card}
{card:label=link-window}
test
{card}
{deck}
{card}
{deck}
{roundrect:bgcolor=#828282|width=909px|height=50px|corners=false,false,true,true}
{roundrect}
|