Access Keys:
Skip to content (Access Key - 0)

<< Plugins Blog

3 steps to create the perfect landing page with the Confluence Dashboards plugin

Oct 10, 2011 16:49

The Confluence Dashboards plugin saves you time and effort in finding and keeping up with the important information on your Wiki.

It allows you to put all of your key information on a personalised, customisable page. Whether it be RSS feeds, Wiki pages, macros or OpenSocial Gadgets, they can all be added to your page. You can then arrange the page however you want, and all changes are remembered.

I'm going to go through an example Confluence Dashboards plugin setup, discussing the 3 steps required to get up an running with the Confluence Dashboards plugin. You can see and try out the result on our live Confluence Dashboards demo.

To build up your Confluence Dashboards page, you have to define the page layout, set the initial boxes and then create the content of those and other boxes.

 

Step 1 - Define the layout

We kick things off by specifying the layout of our page using the {box-layout} macro. This macro allows you to specify the number of columns you want to use, their width and any CSS classes you might want to apply to them.

{box-layout:example} | {box:tc-news}{box:chart} | {box:calculator}{box:g-news} | {box:todo}{box:list}{box:custom-feed|closed=true} | {box-layout}

Step 2 - Specify the initial boxes

The body of the {box-layout} macro is populated by {box} macros, separated with pipe symbols '|' which represent the columns. The {box} macros take the reference ID of their related {box-define} macro, which I will explain shortly. You can also specify their initial states - such as being opened/closed, as well as collapsed or not. These {box} macros give us our default layout - the view that people visiting the page for the first time will see. It's recommended to make this as useful and usable as possible - you to have to accept that some of your users won't have the time or interest to customise their page so the initial page has to work well by itself, without any user interaction. If you're replacing an existing homepage, at first it can be useful to replicate the content that's currently there on this default page to ease users in to the change.

Step 3 - Create your content

You can now start to create the actual contents of the boxes specified in your initial layout, and any additional boxes you want to make available to end-users in a table of contents. You do this with the {box-define} macro, which lets you define the contents of a box using standard Wiki Markup. This macro has seventeen different parameters, which you can optionally specify to define things like whether the box is closeable/dragable/collapsible or not, whether its contents is cached and for how long, as well as the link behaviour, amongst other things. The body of the {box-define} macros is where you include the content itself - you can include RSS feeds, Wiki Pages, widgets, OpenSocial gadgets and Wiki macros.


What content can I include?

Lets take a look at some of the boxes defined in our example, which parameters they use and what content is specified:

Confluence Gadgets

Our first example is a Confluence News gadget. Rather than just displaying links in a list like that of an RSS feed, the Confluence News gadget adds some extra formatting of the content, which makes it look a little nicer. It's one of many pre-written Atlassian gadgets, which are a great resource for users of multiple Atlassian products - the gadgets display information about the content contained in the other Atlassian products and displaying them easily on your Confluence Dashboard can help to give a greater sense of integration between them.

{box-define:confluence-news|title=Confluence News|category=RSS Feeds|editable=true|content-params=width height border|exclude=true}{gadget:url=rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:confluence-news-gadget/gadgets/confluence-news-gadget.xml|width=auto|border=false}show_ads=false{gadget}{box-define}

However, you're not limited to just Atlassian created OpenSocial gadgets, you can create your own, or use other pre-made ones such as those from the directory of Google Gadgets, like:

{gadget:url=http://www.google.com/ig/modules/calculator.xml|width=auto|border=false}{gadget}
{gadget:url=http://hosting.gmodules.com/ig/gadgets/file/112581010116074801021/turtle.xml|width=auto|border=false}{gadget}
RSS Feeds

The Confluence Dashboards plugin is a great way to deliver RSS content to your users. In our example we have a number of RSS feeds. Some of the interesting parameters being used in the example below, which displays the Atlassian Developer blog are the cache, category and retarget parameters.

{box-define:dev-news|cache=1h|editable=true|title=Atlassian Dev Blog|category=RSS Feeds|content-params=max showTitlesOnly|retarget=_blank}{rss:url=http://feeds.feedburner.com/AtlassianDeveloperBlog|max=5|showTitlesOnly=true|titleBar=false}{box-define}
  • Cache
    Caching of content was something really important that the Confluence Dashboards plugin got right. The Confluence Dashboards plugin is often used on pages with some of the highest traffic on your Wiki such as Intranet home pages and Knowledge base landing pages. The Confluence Dashboards plugin transparently background caches content. For those familiar with the cache macro, this is a step beyond the functionality offered by that, with content automatically being rendered in the background so that no user is ever left waiting for content to load.
  • Category
    You might want to make a lot of content available for inclusion on your page. To aid this, you can automatically build a table of contents with collapsible page trees of boxes that can be added. In this example the category is 'RSS Feeds' but you could name it 'RSS Feeds/Tech' to create a 'Tech' subcategory within a list of RSS Feeds for example. You can further sub-categorise your content, using additional '/' in the category name e.g. 'RSS Feeds/Tech/Gadgets'.
  • Retarget
    If your box contains links, then you can choose the link behaviour, as in whether or not the link opens in the current window, a new window or something else.
{box-define:tc-news|cache=1h|title=Gadget News|category=RSS Feeds|content-params=max showTitlesOnly|retarget=_blank}{rss:url=http://feeds.feedburner.com/crunchgear|max=5|showTitlesOnly=true|titleBar=false}{box-define}

Here we see 'showTitlesOnly=true', this means that it's just the RSS link title which is shown in the box, the description containing the first part of the blog itself has chosen to be hidden.

{box-define:y-news|cache=1h|title=Hacker News|category=RSS Feeds/Tech|content-params=max showTitlesOnly|retarget=_blank}{rss:url=http://news.ycombinator.com/rss|max=5|showTitlesOnly=true|titleBar=false}{box-define}
Sticky Notes with the box-notes macro

Moving down the recipe, we see an example of one of the additional macros provided by the Confluence Dashboards plugin being used, the {box-notes} macro. This macro, which doesn't have any parameters, provides the ability to add an editable segment of text within a box, to act like a virtual sticky-note. You can edit the contents of the box and it will be saved for when you next view the page.

{box-define:sticky-note|title=Sticky Note|editable=true|box-params=title|duplicable=true|edit-title=true|retarget=_blank}{box-note}Edit me!{box-note}{box-define}
Widgets and Wiki Pages with the box-page-frame macro

In the next box, we use another Confluence Dashboards macro, {box-page-frame}. This works like an iframe, but improves upon it, making it a useful and reliable way to include Wiki pages within a box. This allows you to re-use components which you might have already created on your Wiki, as well as a range of uses for new pages which you might want to create. It also helps work around limitations within specific macros, such as the ability to include multiple To Do macros on your page, which you otherwise couldn't do if they were used within the page directly.

This box also shows a good use of the 'duplicable' parameter - setting this parameter to true adds a button to the box title bar enabling users to create a copy of that box on their page - this is useful for boxes that end-users might like to want several of on a page, such as sticky-notes or user-definable RSS feeds.

{box-define:wpage|title=Wiki Page|editable=true|box-params=title|duplicable=true|edit-title=true|retarget=_blank}{box-page-frame:page=Wiki Page|space=demo|height=200px}{box-define}
…
Wiki Macros

We can then see the chart macro being used to generate and display a chart within one of our boxes. In this example the data is hard-coded in the page, however there's nothing to stop this being dynamically generated data resulting from something like an SQL macro or something else. This means you can include live data on your charts - great for team leads and project managers, who want to keep up to date with important metrics.

{box-define:chart|title=Chart|editable=true|content-params=type orientation 3D height legend colors}{chart:3D=true|width=290|height=200}| A | One | Two | Three | Four |
| B | 1 | 2 | 3 | 4 |{chart}{box-define}

Finally, we see the last of the macros provided by the Confluence Dashboards plugin being used, the {box-reset}. This just shows a button that when clicked reverts any user changes, displaying the original default layout.

{box-define:list|title=Feed Boxes|category=hide|closable=false|mode=live}{box-list:categorise=true}{box-reset:tag=button}Reset layout{box-reset}{box-define}

Nearly all of the macros can also include CSS class fields, making the entire look and feel of the boxes and the complete page customisable. There's also a number of in-built themes which you can select from.

The result of this recipe is used in our demo of the Confluence Dashboards plugin, which you can view and play around with.

Find out more

For more information, see the Confluence Dashboards plugin documentation and ask any questions on our Community site. We're also running a webinar with Atlassian on the 19th.

The Complete Code

The complete code for this layout is as follows:

{box-layout:example}| {box:tc-news}{box:chart} | {box:calculator}{box:g-news} | {box:todo}{box:list}{box:custom-feed|closed=true} | {box-layout}

{box-define:confluence-news|title=Confluence News|category=RSS Feeds|editable=true|content-params=width height border|exclude=true}{gadget:url=rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:confluence-news-gadget/gadgets/confluence-news-gadget.xml|width=auto|border=false}show_ads=false{gadget}{box-define}

{box-define:dev-news|cache=1h|editable=true|title=Atlassian Dev Blog|category=RSS Feeds|content-params=max showTitlesOnly|retarget=_blank}{rss:url=http://feeds.feedburner.com/AtlassianDeveloperBlog|max=5|showTitlesOnly=true|titleBar=false}{box-define}

{box-define:tc-news|cache=1h|title=Gadget News|category=RSS Feeds|content-params=max showTitlesOnly|retarget=_blank}{rss:url=http://feeds.feedburner.com/crunchgear|max=5|showTitlesOnly=true|titleBar=false}{box-define}

{box-define:y-news|cache=1h|title=Hacker News|category=RSS Feeds/Tech|content-params=max showTitlesOnly|retarget=_blank}{rss:url=http://news.ycombinator.com/rss|max=5|showTitlesOnly=true|titleBar=false}{box-define}

{box-define:d-news|cache=1h|title=Digg Tech|category=RSS Feeds/Tech|content-params=max showTitlesOnly|retarget=_blank}{rss:url=http://digg.com/news/technology/media/recent.rss|max=5|showTitlesOnly=true|titleBar=false}{box-define}

{box-define:g-news|cache=1h|title=Google Blog|category=RSS Feeds/Blogs|content-params=max showTitlesOnly|retarget=_blank}{rss:url=http://googleblog.blogspot.com/atom.xml|max=5|showTitlesOnly=true|titleBar=false}{box-define}

{box-define:j-news|cache=1h|title=Kottke Blog|category=RSS Feeds/Blogs|content-params=max showTitlesOnly|retarget=_blank}{rss:url=http://feeds.kottke.org/main|max=5|showTitlesOnly=true|titleBar=false}{box-define}

{box-define:custom-feed|title=Custom Feed|editable=true|box-params=title retarget|content-params=titleBar|exclude=true|duplicable=true|edit-title=true|retarget=_blank}{rss:max=5|showTitlesOnly=true|titleBar=false}{box-define}

{box-define:sticky-note|title=Sticky Note|editable=true|box-params=title|duplicable=true|edit-title=true|retarget=_blank}{box-note}Edit me!{box-note}{box-define}

{box-define:wpage|title=Wiki Page|editable=true|box-params=title|duplicable=true|edit-title=true|retarget=_blank}{box-page-frame:page=Wiki Page|space=demo|height=200px}{box-define}

{box-define:todo|title=To Do|editable=false}{box-page-frame:page=To Do|space=demo|height=215px}{box-define}

{box-define:gallery|title=Gallery|editable=true}{box-page-frame:page=Gallery|space=demo|height=500px}{box-define}

{box-define:chart|title=Chart|editable=true|content-params=type orientation 3D height legend colors}{chart:3D=true|width=290|height=200}| A | One | Two | Three | Four |
| B | 1 | 2 | 3 | 4 |{chart}{box-define}

{box-define:calculator|title=Calculator|editable=true|content-params=width border|exclude=true|edit-title=true}{gadget:url=http://www.google.com/ig/modules/calculator.xml|width=auto|border=false}{gadget}{box-define}

{box-define:turtles|title=Turtles|editable=true|content-params=width border|exclude=true}{gadget:url=http://hosting.gmodules.com/ig/gadgets/file/112581010116074801021/turtle.xml|width=auto|border=false}{gadget}{box-define}

{box-define:list|title=Feed Boxes|category=hide|closable=false|mode=live}{box-list:categorise=true}{box-reset:tag=button}Reset layout{box-reset}{box-define}
Adaptavist Theme Builder Powered by Atlassian Confluence