Skip to end of metadata
Go to start of metadata

{blog-list} Macro

Description

The blog-list macro is used to display a list of blog posts and excerpts....

Usage

{blog-list}

Parameters

The "Ver" column shows which version of Theme Builder the parameter became available in.

Property

Required

Default

Notes

Theme Panels Only

Ver

default

(error)

singlespace

Display mode. (singlespace/multispace)

 

3.2

space

(error)

@current

The space (or list of spaces) whose posts should be listed (SPACEKEY/@all/@current/@favourite/@global/@personal/@children) NB: the @all parameter must be used on it's own, other macro parameters may be used in a list.

 

3.2

label

(error)

n/a

A list of team labels that can be used to filter the list of blog posts

 

3.3.5

author

(error)

n/a

A comma separated list of usernames/group names/@self/@creator/@owner

 

3.3

sort

(error)

creation

The order that the posts should be listed in (creation/modified/recent)

 

3.2

reverse

(error)

false

List the blogposts in reverse order

 

3.2

count

(error)

9

The number of posts that should be displayed.

 

3.2

start

(error)

0

Offset from the start for listing the posts.

 

3.2

dateFormat

(error)

defined by confluence settings

Format that dates should be displayed in

 

3.2

date

(error)

false

Show the Date of the blogpost.

 

3.2

title

(error)

true

Show the Title of the blogpost.

 

3.2

linktitle

(error)

true

Link the title to the blogpost

 

3.2

excerpt

(error)

true

Display the excerpt of the blogpost (true/false/full)

 

3.2

postedby

(error)

true

Display the date that the post was created (true/false/date).

 

3.2

permalink

(error)

n/a

Text to use for posted by

 

3.2

postedByCaption

(error)

n/a

Text to use for posted by.

 

3.2

none

(error)

n/a

Text to display when no posts have been found

 

3.2

Examples

Basic Use

Add the {blog-list} macro to a page or panel where you want to display a list of blog posts

{blog-list}

Display blog posts for the whole site (including personal spaces)

To display blogs for all spaces set the display mode to multispace (so that the space the blog originated in is displayed), and set the spaces parameter to @all

{blog-list:multispace|space=@all}

Display blog posts for just global spaces (whole site, no personal spaces)

To display blogs for global spaces set the display mode to multispace (so that the space the blog originated in is displayed), and set the spaces parameter to @global

{blog-list:multispace|space=@global}

Display title, excerpt & date

{blog-list:count=3|postedby=date|permalink=}

Only display titles

{blog-list:count=3|postedby=false|excerpt=false|permalink=}
{blog-list:count=3|permalink=}

Show the date the post was made

{blog-list:count=3|date=true}

CSS Customisation

The standard output follows this structure

<div class="bloglist default">

    <div class="post">
        <div class="date"><span>Jun 01, 2009 23:30</span></div>
        <div class="permalink"><a href="$bloglisthelper.getTinyURL($post)">Permalink</a></div>
        <div class="title">
            <a href="http://www.mysite.com/x/Goy9Ag">This is the blogpost title</a>
        </div>
        <div class="excerpt"><span>The excerpt of the blogpost will be shown here</span></div>
        <div class="postedby">Posted by Test User on Jun 01, 2009 23:30 </div>
        <div class="commentcount">Comments (5)</div>
    </div>

</div>

Hints and Tips

When excepts are enabled, the macro will output a block of content taken from the top of your blog posts. If you need more control over the excerpts, consider using the excerpt macro.

Frequently Asked Questions

None at present.

  • No labels

14 Comments

  1. Unknown User (gfraser)

    @Emma - check with Alain which version of Builder this macro was added in - it certainly wasn't 3.0, it was 3.2 or something like that.

  2. Unknown User (ville.valtasaari@thl.fi)

    The blog-calendar, -list and -archive macros would be just perfect if they included the labels option with boolean AND and OR. That would allow us to have blogs/news of several categories in a single space.

    r. Ville

  3. Unknown User (cemerick)

    A couple things:

    • postedby's default value of true doesn't seem to do anything – I had to set postedby=date in order to get the creation date to display
    • the blog titles are linked to the 'raw' page IDs, rather than to the news items' titles (which is far nicer to look at, etc). Is there any way to change this, or is doing this just an enhancement item?
    • The raw materials are there to implement pagination, so maybe a paginate=true/false option could be added to save everyone else the trouble. (smile)

    It's great to have proper permalinks on the blog post listings now!

    Thanks,

    • Chas
  4. Unknown User (cemerick)

    It appears that blog-list does not hide posts whose published date is in the future. I'd assume that that's a bug...

    1. Unknown User (gfraser)

      I didn't think Confluence allowed blog posts dates set in the future?

      1. Unknown User (cemerick)

        Interesting...apparently, no, it's not supposed to (though I didn't know that 10 min ago). If you choose a date in the past (say, Sept. 1st), and then click over to the next month, the month will be changed, leaving the day in place (giving us a publish date of Oct 1st).

        So, an issue with Confluence's date picker, rather than with blog-list.

        1. Interesting ... so the door is open for me to create an action which abuses the API and allows you to pick dates in the future to use the blog functionality for planning meetings (big grin)

          1. Unknown User (ville.valtasaari@thl.fi)

            Abuse it some more to allow for scheduled publishing (wink)

            r. Ville

  5. Unknown User (jnevin)

    Note that the Parameters documentation is incorrect:

    To filter by regular label(s), use the parameter "label", eg

    {blog-list:date=true|label=case-studies,strategy-pov|permalink=Bookmark Link}
    
    1. The confluence notation guide is always your most upto date reference, this html documentation tends to lag a little behind the current state of play.

  6. Unknown User (abarnes)

    The documentation lacks an example for author, and I'm not sure what it means by "username". I have users whose full name includes ", Administrator" (dunno why), and it seems to ignore the author parameter entirely.

    1. Your username is abarnes, does that help at all?

      1. Unknown User (abarnes)

        How are you, as a unprivileged user, retrieving that username?

        1. If you hover over your name Andrew it will show as the link url .../~abarnes as it goes to your profile. This is your username (unique name reference) within Confluence, the one you use to sign in if needed.