Bubbles - Quick Start

Work in progress

Note: This guide is aimed at Site Administrators.

Before doing anything, you need configure the plugin. This guide will cover the basics of configuring:

• Widgets
• Portals
• Permission Schemes
• Communities

We'll only be doing the bear minimum to start with - just enough to get you up and running. There are also other features (like [User Levels] and Relationships) that we're not covering in this quick start guide because they are not essential for the majority of features.

Before doing too much configuration you should read through the rest of the user guide to get a better understanding of how the features work and find out about patterns that have worked well for us.

Ok, let's get started...

Go in to the Confluence Administration Console and you'll see a link on the left for "Community Bubbles" - that'll take you in to the plugin configuration area.

Widgets

Widgets are re-usable blocks of markup - they can contain simple wiki content, macros, HTML and even Velocity parsing. We're going to start with a couple of simple widgets to illustrate.

Click the "Widgets" tab and add a new widget with the following settings:

{my-communities:@self|showlogo=false|showtitle=true}

Right, let's add another one:

<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=8,0,0,0" type="application/x-shockwave-flash"
width="100%" height="340px" id="InsertWidget_9c37be6d-dddf-4673-a953-201a31462c57" align="middle">
	<param name="movie" value="http://widgetserver.com/syndication/flash/wrapper/InsertWidget24.swf?appId=9c37be6d-dddf-4673-a953-201a31462c57"/>
	<param name="quality" value="high" />
	<param name="wmode" value="transparent" />
	<param name="menu" value="false" />
	<param name="allowScriptAccess" value="sameDomain" />
 <embed src="http://widgetserver.com/syndication/flash/wrapper/InsertWidget24.swf?appId=9c37be6d-dddf-4673-a953-201a31462c57"  name="InsertWidget_9c37be6d-dddf-4673-a953-201a31462c57"  width="100%" height="340px" quality="high" menu="false" pluginspage="http://www.macromedia.com/go/getflashplayer" type="application/x-shockwave-flash" wmode="transparent" align="middle"  allowScriptAccess="sameDomain" /> </object>
<img style="visibility:hidden;width:0px;height:0px;" border="0" width="0" height="0" src="http://runtime.widgetbox.com/syndication/track/9c37be6d-dddf-4673-a953-201a31462c57.gif" />

As you've probably just realised, you can put pretty much anything in a widget, even external widgets from WidgetBox

At this point you can, if desired, use the widgets anywhere within the wiki, for example you could add this to a wiki page:

{widget:MY-COMMUNITIES}

{widget:PACMAN}

However, you'll only see the PACMAN widget - that's because there are no communities set-up yet (so the user can't join them) therefore the MY-COMMUNITIES widget will output nothing.

While widgets can be used in their own right, you could probably do the same with User Macros (a standard feature of Confluence). In fact, you can include user macros (and any other macros) within widgets. But let's look at the real benefit of widgets...

Portals

Portals allow you to group together a selection of widgets and easily deploy them throughout your wiki.

Click the "Portals" tab and add a new portal with the following settings:

ID	DEMO
Title	Demo Portal
Description	Just testing...
Wrap Portal and Widgets
Configurable
Collapsible
Columns	2
Column Widths	40% and 60%
Widgets	Add the PACMAN and MY-COMMUNITIES widgets. Set MY-COMMUNITIES to be in column 2. Make sure both widgets have the "Display" property ticked.

Now you can easily deploy that portal anywhere in your wiki using the following:

{portal:DEMO}

It'll look ugly to start with as there are no styles applied - to quickly add some basic styling to the portal, edit it and add the following ¹ to the "Header" field:

{style}
/* Spacing between portal columns */
.portal-column.column2 {
 padding-left: 8px;
}

/* Widget */
.widget {
 border: 1px solid #ddd;
 margin-bottom: 8px;
}

/* Widget titles */
.widget-title {
 background: #ddd;
 height: 20px;
 text-align: center;
 vertical-align: center;
}
.widget-title img {
 float: left;
}

/* Widget content */
.widget-content {
 padding: 4px;
}
{style}

NB: This isn't the ideal way to style portals as it results in the style being output in the page leading to longer download times. However, it will suffice for the purposes of this quick start guide.

When you display a page with the DEMO portal, you'll notice a few things:

• each widget has a "-" or "+" icon in it's title, allowing you to collapse or expand the widget
• any widgets that output nothing are completely removed from the portal
• a "Configure Portal" link appears below the portal (if you have sufficient privileges to customise the portal)

Right, we really must get the MY-COMMUNITIES widget working, but one last step before we set up our first community...

Permission Schemes

Permission Schemes are used exclusively with Communities. You can define any number of schemes and then make one or more of them available to each type of community.

Let's start by making the two most common types of permission scheme found in most social networking sites...

Go in to the "Permission Schemes" tab and add a new scheme with the following settings:

In a nutshell, communities with the above permission scheme will be visible to all users (including anonymous users) and can be edited by members (who must be registered users).

Right, let's add another permission - this time the second most common type of community...

A network community generally requires all members to meet some specific criteria, for example working for a specific company or living in a specific country. The "Network" enrolment model within this permission scheme is ideal for scenarios where membership is automated (eg. using Confluence's XML-RPC API).

Right, now we can finally define some communities!

Communities

First, what are communities? They are a bundle consisting of the following:

• A wiki space
• Pre-defined permission scheme
• A membership group (with privileges and enrolment criteria defined via the permission scheme)
• A specific portal on the space home page
• A specific theme (and layout if using Theme Builder)
• Space and team labels (think of team labels as community labels)

Go in to the "Communities" tab and add a new community with the following settings:

Ok, now we can create our first community! Add the following wiki notation to an existing wiki page:

After saving the page, click the link and follow the on-screen instructions.

What did we forget?

Ok, by now you should have at least one community - but there's something missing. We forgot to add a method to allow users to join the community.

We forgot this on purpose to illustrate one other very useful feature of portals - when you make changes to a portal in the admin area, all instances of that portal will be updated (this saves hours and even days on large sites).

Go back in to the Community Bubbles config area and click on the "Widgets" tab then add a new widget with the following settings:

{join-community:spacekey|join=Join this %communitytitle%|leave=Leave this %communitytitle%}

{community-members:none=There are currently no members in this community|count=6}

After saving the new widget, go in to the "Portals" tab and edit the "DEMO" portal. Add the new COMMUNITY-MEMBERS widget in to column 2.

When you go back to one of your newly created communities you should now see an option to join the community on the home page. When you join you'll see the "My Communities" widget appear and your profile picture will also appear in the "Community Members" widget.