/
Using the sp-list Macro (v 1.1)

Using the sp-list Macro (v 1.1)

Aug 18, 2016

You can use the SharePoint List macro {sp-list} to display a SharePoint list on a Confluence wiki page. The macro can display most SharePoint list types.

Screenshot: The SharePoint List macro in Confluence



On this page:

Usage with the Macro Browser

The 'Macro Browser' is a graphical menu that allows you to view the list of available Confluence macros and add them to the current page or blog post.

To insert the SharePoint List macro into a page using the Macro Browser,

Usage with the Wiki Markup Editor

Basic Form

Full Form

Make sure that you enter the entire text on a single line without any line breaks.

{sp-list:SHAREPOINT SITE ALIAS:listName=LIST NAME|columns=COLUMN 1 NAME,COLUMN 1 ALIAS,COLUMN 1 TYPE;COLUMN 2 NAME,COLUMN 2 ALIAS,COLUMN 2 TYPE|debug=TRUE}

Parameters

Separating Multiple Parameters

In wiki markup, the parameters are separated by a pipe character (|). The SharePoint List macro has a slightly more complex format than other Confluence macros. For each parameter, you can enter multiple values separated by a comma (,) or a semi-colon (;). We give a detailed description in the table below.

Parameter

Default

Description

listname
(SharePoint site alias:listName)

No default

The first parameter can contain either just the name of the SharePoint list ('listName') or the SharePoint site alias and the list name, separated by a colon (:). The text 'listName' is optional.

The following example has two parameters. The first parameter contains just the list name 'documents'. (The second parameter is the list type, as described below, and is not relevant here.) For now, please look at just the first parameter before the pipe character (|):

{sp-list:documents|document}

In the next example, the first parameter contains an alias 'mySharePoint' and the list name 'documents':

{sp-list:mySharePoint:documents|document}

Here is another example with alias and list name, where the parameter name 'listName' is explicitly specified:

{sp-list:mySharePoint:listName=documents|document}


The SharePoint site alias is the nickname of the SharePoint server as specified in the SharePoint Admin settings. See the Confluence SharePoint plugin configuration guide. Note that this value is case sensitive – use the same capital and lower-case letters as in the plugin configuration screen.

The listName is the name of the list in SharePoint. This value is not case sensitive.

Specifying the full path to your list

You must give the full path to the list. In the above example, we have assumed that the list is located at the root (top-level) SharePoint site. However, if the list is in a SharePoint site called 'mySubSite' that is a child of the root site collection, you might specify the following:

{sp-list:/SiteDirectory/mySubSite/documents|document}
Displaying the contents of a document folder

To display the contents of a folder 'my folder' within a document library, add a double forward slash(//):

{sp-list:/SiteDirectory/mySubSite/documents//my folder|document}

(Unnamed parameter: List type)

No default

Use this parameter to specify the type of the list in SharePoint. If you do not specify the columns (see below), then you must specify the list type. If you do not specify the columns, Confluence will display default columns for the given list type. The macro supports the following list types:

  • doc, docs, document

  • link

  • cal, calendar

  • task, tasks

  • issue, issues

  • discussion, discussions

    See the examples below.

columns
(columns)

If the 'list type' parameter is present and there is no 'columns' parameter, then SharePoint will display default columns for the given list type.

Use this parameter to specify the columns of the SharePoint list that will be displayed on the Confluence page. If you do not specify the columns, Confluence will display default columns for the given list type. If you specify both the list type and the columns, Confluence will display the specified columns instead of the default columns.
Use 'view' as a column name to create a link to the original SharePoint list.

You can enter one or more columns, separated by a semi-colon (;). For each column, you can specify the column name, alias and type, separated by a comma (,). The format is:

columns=COLUMN 1 NAME,COLUMN 1 ALIAS,COLUMN 1 TYPE;COLUMN 2 NAME,COLUMN 2 ALIAS,COLUMN 2 TYPE

For example:

{sp-list:documents|columns=BaseName,Document Name,doc;FileSizeDisplay,File Size,fileSize;Modified,,date;Author,,author;view}


The column name is a unique SharePoint 'field ID' for the column. Please refer to Frode's awesome list of Sharepoint Column Field IDs. For example, to find the field ID for the column containing the file size, go to Frode's page for F to P. As shown on the page, the field ID is FileSizeDisplay.

Alternatively, you can use the 'debug' parameter to obtain a list of SharePoint field IDs. See more about the debug option below.

The column alias will be displayed as the column header on the Confluence wiki page. You can enter any value you like here.

The column type determines how the macro will format the value when displaying it on the Confluence page. The following values are supported:

  • fileSize – Formats the column value as a file size.

  • author – Formats the column value as a link to the user's profile on SharePoint.

  • date – Formats the column value as a date in the form "MM/dd/yyyy" (ie. the "American" format).

  • dateTime – Formats the column value as a date and time in the form "MM/dd/yyyy hh:mm aa".

  • url – Formats the column value as a hyperlink.

  • boolean – Displays a value of 'yes' or 'no'.

  • percent – Formats the column value as a percentage.

  • doc – Formats the column value as a link to a document in the SharePoint list.

debug

False

Set this parameter to 'true' if you want to send the SharePoint SOAP response to the HTML source of the page. You can see the result by viewing the source of the page. See more below.