Using the sp-list macro

On this page:

Using the {sp-list} macro

(Please note this documentation has been updated for version 1.0.4 of the plugin. The 'SharePoint Site Alias' notation has been added. If you have an earlier version of the plugin please upgrade if you'd like to reference multiple SharePoint Sites.)

The {sp-list} macro can display the contents of most lists in SharePoint.

Short Form

This form of the {sp-list} macro has predefined columns allowing for a shorthand notation.

{sp-list:<SharePoint Site alias>:<name of the list>|<list type>}

If you're referencing the SharePoint Site Server selected as the 'default' on the SharePoint Admin settings you can leave out the 'SharePoint Site alias'.

{sp-list:<name of the list>|<list type>}

• listName: is the name of the list in SharePoint
• list types currently supported:
  • doc, docs, document
  • link
  • cal, calendar
  • task, tasks
  • issue, issues
  • discussion, discussions

Examples shown below.

Full Syntax

This should all be on one line.

{sp-list:<SharePoint Site alias>:listName=<name of the list>|
columns=<sharepoint column name mandatory>,<column alias optional>,<column type optional>;
<sp col name>,<alias>,<type>|
debug=<true\|false>}

• listName: is the name of the list in SharePoint
• colums: defines the columns of list.
  • (Using 'view' as a column name will create a link back to the original SharePoint list).
• debug: when set to true will send the SharePoint SOAP response to the html source of the page. You can inspect by doing a 'view source' on the page.

List Name and path:

Currently the full path to the list must be written. For instance a document list in the root site could be embedded within a Confluence page with the following notation:

{sp-list:my site:my list|doc}

or if 'my site' is the default 'SharePoint Site'

{sp-list:my list|doc}

However if that list were in a SharePoint site under the root 'site collection' you might write.

{sp-list:sub site/my list|doc}

Displaying the contents of a document folder

The syntax is to add a // to retrieve a folder's content.

{sp-list:document-library//folder|doc}

(this syntax to display a document folder's contents is only supported in version 1.0.6 and higher of the Java plugin. The version of the SharePoint web parts you're using doesn't matter.)

Examples

Following are examples of the short hand notation, the long hand notation showing the same list and a screenshot of the output.

doc, docs, document

{sp-list:test doc library|doc}

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

link

{sp-list:sample links|link}

{sp-list:sample links|columns=URL,,url;Comments}

cal, calendar

{sp-list:Sample Calendar|cal}

{sp-list:Sample Calendar|columns=Title;Location;EventDate,Start Time,date;EndDate,End Time,date;fAllDayEvent,All Day Event,boolean}

task, tasks

{sp-list:Sample Tasks|task}

{sp-list:Sample Tasks|columns=Title;AssignedTo,,author;Status;Priority;DueDate;PercentComplete,Percent Complete,percent}

issue, issues

{sp-list:sample issues|issue}

{sp-list:sample issues|columns=ID,Issue ID;Title;AssignedTo,,author;Status;Priority;DueDate,Due Date,date}

discussion, discussions

{sp-list:sample discussion|discussion}

{sp-list:sample discussion|columns=Title;Author,,author;ItemChildCount,Replies;DiscussionLastUpdated,Last Updated,date}

The debug option

You can add a debug parameter to your macro as follows:

{sp-list:Sample Tasks|task|debug=true}

This will cause the macro to write out the XML for the list which the SharePoint service is returning in the HTML page but it is commented out. To see it you can right click on the web page and select 'View Source'.

You can the add additional columns to your macro if you wish to display additional data. As you'll see the macro trims off the prepended 'ows_' characters from the field name.