The following chart shows examples of the CSS styles that can be used and how they look in your own web browser:

disc: Item 1 Item 2 Item 3 Item 4 circle: Item 1 Item 2 Item 3 Item 4 square: Item 1 Item 2 Item 3 Item 4 decimal: Item 1 Item 2 Item 3 Item 4 decimal-leading-zero: Item 1 Item 2 Item 3 Item 4

lower-roman: Item 1 Item 2 Item 3 Item 4 upper-roman: Item 1 Item 2 Item 3 Item 4 lower-alpha: Item 1 Item 2 Item 3 Item 4 upper-alpha: Item 1 Item 2 Item 3 Item 4 lower-greek: Item 1 Item 2 Item 3 Item 4

lower-latin: Item 1 Item 2 Item 3 Item 4 upper-latin: Item 1 Item 2 Item 3 Item 4 hebrew: Item 1 Item 2 Item 3 Item 4 armenian: Item 1 Item 2 Item 3 Item 4 georgian: Item 1 Item 2 Item 3 Item 4

cjk-ideographic: Item 1 Item 2 Item 3 Item 4 hiragana: Item 1 Item 2 Item 3 Item 4 katakana: Item 1 Item 2 Item 3 Item 4 hiragana-iroha: Item 1 Item 2 Item 3 Item 4 katakana-iroha: Item 1 Item 2 Item 3 Item 4

The first two columns above are the most widely supported styles. The other styles generally require an operating system and web browser both capable of rendering Unicode characters.

The following chart shows what the styles should look like if everything is configured properly:

The following chart shows what the styles often look like on systems that don't have full unicode support:

When used without any parameters, the macro will display a list of all incoming links:

{incoming-links}* No Incoming Links{incoming-links}

Resulting in this:

• children macro
• excerpt-include macro
• excerpt macro
• page-info macro

If there were no icoming links, the user would see the following message:

• No Incoming Links

If you don't add a message to display when there are no links, the macro will not display anything!

If you want to limit the number of incoming links shown, use the following notation:

{incoming-links:first=2}* No Incoming Links{incoming-links}

In the example above, we're limiting to just the first 2 links:

• children macro
• excerpt-include macro

By default, the list mode output will show icons to depict different types of content as shown in Example #1. However, you can choose a different item marker using the style parameter:

{incoming-links:style=disc}* No incoming links{incoming-links}

Which results in:

• children macro
• excerpt-include macro
• excerpt macro
• page-info macro

You can see examples of all the CSS style options in the associated tabs at the top of this page.

You can also turn off the marker completely by setting style to none:

{incoming-links:style=none}No incoming links{incoming-links}

Which results in:

• children macro
• excerpt-include macro
• excerpt macro
• page-info macro

By default, the links will be output as a list, however you can also output them as a flat navigation bar:

{incoming-links:mode=flat}---{incoming-links}

Resulting in:

children macro, excerpt-include macro, excerpt macro, page-info macro

As you can see, we didn't include the usual "No incoming links" message between the macro tags - there's no point (usually) in displaying a message in this case. Because the macro will create a blank line (which would look odd), we simply put a few hyphens in instead.

You can make the output look nicer by centering it with the center macro as follows:

{center}{incoming-links:mode=flat}---{incoming-links}{center}

Resulting in:

children macro, excerpt-include macro, excerpt macro, page-info macro

As you can see above, the flat style defaults to putting square brackets around each item. However, there are times that you might want other styles in which case you should use the "separator" parameter:

{incoming-links:mode=flat|separator=braces}---{incoming-links}

{incoming-links:mode=flat|separator=parens}---{incoming-links}

{incoming-links:mode=flat|separator=pipe}---{incoming-links}

Resulting in various styles:

{ children macro } { excerpt-include macro } { excerpt macro } { page-info macro }
( children macro ) ( excerpt-include macro ) ( excerpt macro ) ( page-info macro )
children macro | excerpt-include macro | excerpt macro | page-info macro

As well as the pre-defined styles for separators, you can specify your own custom separator, for example:

{incoming-links:mode=flat|separator=::}---{incoming-links}

Which gives:

children macro:: excerpt-include macro:: excerpt macro:: page-info macro

By default the macro will list incoming links from all types of content, but you might prefer to limit the list to specific types of content. For example, we've got a news item linking to this page (only as an example) that's not much use:

children macro, excerpt-include macro, excerpt macro, page-info macro

To get rid of it, we restrict the content types that are reported on - let's say pages and comments:

{center}{incoming-links:mode=flat|types=page,comment}---{incoming-links}{center}

Resulting in:

children macro, excerpt-include macro, excerpt macro, page-info macro

Alternatively, we might only want to show new items (known internally as "blogposts"):

{center}{incoming-links:mode=flat|types=blogpost}---{incoming-links}{center}

Resulting in:

—

To sort incoming links based on the date the content was created, use the following:

{incoming-links:sort=creation}---{incoming-links}

Resulting in:

• excerpt macro
• excerpt-include macro
• children macro
• page-info macro

To sort incoming links based on the date the content was last modified, use the following:

{incoming-links:sort=modified}---{incoming-links}

Resulting in:

• excerpt-include macro
• excerpt macro
• children macro
• page-info macro

The bitwise sort mode is almost the same as the default natural sort mode – it's faster, but not as good at sorting titles with numbers in them. You should only ever need the bitwise sort if you've got really massive lists of incoming links.

To reverse the sort order, simply add the reverse parameter:

{incoming-links:reverse=true|sort=modified}---{incoming-links}

Resulting in:

• page-info macro
• children macro
• excerpt macro
• excerpt-include macro

There will be times when you want to limit links based on where tehy are coming from - especially if you have lots of incoming links!

The first method is based on the parent page - only links attached directly to the page specified will be listed:

{incoming-links:mode=flat|parent=Navigation and Lists}---{incoming-links}

In the example above, only incoming links from pages attached to the Navigation and Lists page will be displayed:

—

Similarly, you can filter the list to pages that share a common ancestor. For example, to show all incoming links from pages within our Macros section, use the following:

{incoming-links:mode=flat|ancestor=Macros}---{incoming-links}

In the example above, only incoming links from pages attached to the Navigation and Lists page will be displayed:

—

Tip: You can also specify a space key if the page or ancestor is in another space, eg: MYSPACE:Page Title

Finally, you can limit the list to links coming from specific spaces, for example:

{incoming-links:mode=flat|space=ADAPTAVIST}None Yet{incoming-links}

This will filter the links to our ADAPTAVIST space (our corporate website) where there aren't currently any links directly to this page (but should any appear in the future, you'll see them below):

None Yet

To filter by more than one space, simply separate the space keys by commas:

{incoming-links:mode=flat|space=ADAPTAVIST,USERGUIDE}None Yet{incoming-links}

This will now include incoming links from the Builder User Guide and our Corporate Website:

Demonstration News

No self-respecting linking macro would be complete without the ability to display excerpts, and the {incoming-links} macro is no exception!

Excerpts are short summaries added to content (pages, news, etc.) using the excerpt macro and are useful for giving the user more information before they click a link.

To include excerpts, which are displayed in list mode, use the following:

{incoming-links:excerpt=true}No Links{incoming-links}

Resulting in:

• children macro — The {children} macro displays lists of child pages attached to the current page or orphan pages that are not attached to any page...
• excerpt-include macro — The {excerpt-include} macro displays the an excerpt from another locaiton in your content...
• excerpt macro — The {excerpt} macro defines a block of text as being the excerpt (or summary) for a page...
• page-info macro — The {page-info} macro allows you to display several useful pieces of information about the page in a simple format