Blog Posts From Jivespace Community Blog Tagged With widgets

Creating account spaces, part II: Widgets

communities@jivesoftware.com — Fri, 23 Jan 2009 16:52:22 GMT

Last episode I explained how we create the secure spaces and setup permissions (see How do the account spaces get created anyway? Is it private?). This post deals with the default widgets that come with a newly created community, and how we had to customize this functionality to meet our requirements.

I. How it's done out of the box

To do this, let's first take a look at how it would be done out of the box:

Create a new community
Then get re-directed to the newly created community

Here, community.ftl will call CommunityAction's getWidgetLayout via:

<#if widgetLayout?exists>
    <div id="jive-body-main">
        <div id="jive-widget-content">
            <div id="thread.watch.notify" class="jive-info-box" style="display:none">
            </div>

            <#include "/template/global/include/form-message.ftl" />

            <#include "${widgetLayout.freemarkerTemplate}" />

        </div>
    </div>
</#if>

And within getWidgetLayout() you'll see that if we haven't customized a community and a layout doesn't exist yet, we'll just copy the default:

public WidgetLayout getWidgetLayout() {
        try {
            if (!isHasCustomized()) {
                // if no draft widget frames exist, then no default layout exists
                if (widgetManager.getWidgetFrames(getCommunity()).size() == 0) {
                    copyDefaultLayout();
                }
                .....

And to copy the default, we do this:

/**
* Copy the default layout (large left, small right) to the current community.
*/
     protected void copyDefaultLayout() {
          WidgetManager widgetManagerUnproxied = (widgetManager instanceof WidgetManagerProxy) ? ((WidgetManagerProxy)widgetManager).getUnproxiedObject() : widgetManager;
 
          try {
               WidgetLayoutDescriptor wld = widgetManagerUnproxied.getWidgetLayoutByName(TwoColumnLargeLeftColumnLayout.class.getName());
               WidgetLayout wl = widgetManagerUnproxied.getWidgetLayout(wld);
               widgetManagerUnproxied.addWidgetLayout(getCommunity(), wl);
          .....

And at that point, you'll have the default layout with no widgets, and so further down the line you'll see a call to getWidgetFrames, and similarly to above it will copy the default:

public Map<Integer, List<WidgetFrame>> getWidgetFrames() {
        if (!isHasCustomized()) {
            if (widgetManager.getWidgetFrames(getCommunity()).size() == 0) {
                copyDefaultFrames();
            }
          .....

which will add the default widgets:

/**
     * Copy the default widget frames to the current community:
     *  <ul>
     *      <li>Left: Sub-Spaces</li>
     *      <li>Left: Projects</li>
     *      <li>Left: Recent Activity</li>
     *      <li>Right: Actions</li>
     *      <li>Right: Top Members</li>
     *      <li>Right: Tag Cloud</li>
     *  </ul>
     */
    protected void copyDefaultFrames() {
        try {
            WidgetManager widgetManagerUnproxied = (widgetManager instanceof WidgetManagerProxy) ? ((WidgetManagerProxy)widgetManager).getUnproxiedObject() : widgetManager;
 
            // column 1
            int row = 0;
            if (widgetManagerUnproxied.getWidgetByName(SubCommunitiesWidget.class.getName()) != null) {
                widgetManagerUnproxied.addWidgetFrame(WidgetUtils.createWidgetFrameBean(getCommunity(), SubCommunitiesWidget.class.getName(), 1, row++));
            }
            if (isProjectsEnabled()) {
                if (widgetManagerUnproxied.getWidgetByName(CommunityProjectsWidget.class.getName()) != null) {
                    widgetManagerUnproxied.addWidgetFrame(WidgetUtils.createWidgetFrameBean(getCommunity(), CommunityProjectsWidget.class.getName(), 1, row++));
                }
            }
            if (widgetManagerUnproxied.getWidgetByName(RecentContentWidget.class.getName()) != null) {
                widgetManagerUnproxied.addWidgetFrame(WidgetUtils.createWidgetFrameBean(getCommunity(), RecentContentWidget.class.getName(), 1, row));
            }
 
            // column 2, start row back at 0
            row = 0;
            if (widgetManagerUnproxied.getWidgetByName(CommunityActionsWidget.class.getName()) != null) {
                widgetManagerUnproxied.addWidgetFrame(WidgetUtils.createWidgetFrameBean(getCommunity(), CommunityActionsWidget.class.getName(), 2, row++));
            }
            if (widgetManagerUnproxied.getWidgetByName(TopMembersWidget.class.getName()) != null) {
                widgetManagerUnproxied.addWidgetFrame(WidgetUtils.createWidgetFrameBean(getCommunity(), TopMembersWidget.class.getName(), 2, row++));
            }
            if (widgetManagerUnproxied.getWidgetByName(TagCloudWidget.class.getName()) != null) {
                widgetManagerUnproxied.addWidgetFrame(WidgetUtils.createWidgetFrameBean(getCommunity(), TagCloudWidget.class.getName(), 2, row));
            }
        }
        ......

II. How do the objects interact, and how are they displayed?

Sometimes these widget layouts, widget layout descriptors, widgets, widget frames, etc can get kind of confusing. I hope this illustration and ftl explanation can help paint a better picture, and deepen the understanding.

As an overview, you have the layout (red - WidgetLayout), the layout descriptor (blue - WidgetLayoutDescriptor) which tells how to display the widgets (green - WidgetFrames, contain widgets). A bit more technical tidbits from the database side of things, the container in jiveWidgetFrame is essentially the column, and the frameIndex is essentially the row. See more here:http://www.jivesoftware.com/builds/docs/clearspace/latest/DatabaseSchemaGuide.html#jiveWidgetFrame

We saw above how it will grab the widget layout, but I didn't show it returning from that method. This can be seen as the red box in the picture above (the layout)

<#if widgetLayout?exists>
    <div id="jive-body-main">
        <div id="jive-widget-content">
            <div id="thread.watch.notify" class="jive-info-box" style="display:none">
            </div>

            <#include "/template/global/include/form-message.ftl" />

            <#include "${widgetLayout.freemarkerTemplate}" />

        </div>
    </div>
</#if>

public WidgetLayout getWidgetLayout() {
        try {
            if (!isHasCustomized()) {
                // if no draft widget frames exist, then no default layout exists
                if (widgetManager.getWidgetFrames(getCommunity()).size() == 0) {
                    copyDefaultLayout();
                }
                return widgetManager.getWidgetLayout(getCommunity());

After returning the layout, we look to the layout FTL (which for this particular layout is ls.ftl) and CommunityAction for what happens next (this is the blue box above, the layout descriptor). Each different layout FTL asks for the widget frames associated with it, and will have them available via the CommunityAction. For our example, it looks for the widget frames in the left container, and then the right container.

This loads the widgets in the left container (green A)...

<div id="jive-body-layout-ls">
    <div class="jive-body-layout-l">
        <div id="jive-widget-container_1" class="jive-widget-container jive-widget-container-large">
         <#if widgetFrames?exists && widgetFrames.containsKey(1?int)>
             <#list widgetFrames.get(1?int) as widgetFrame>
                 <#if widgets?exists>
                     <@jive.editWidgetFrame widgetFrame=widgetFrame />
                 <#else>
                     <@jive.displayWidgetFrame widgetFrame=widgetFrame size=enums["com.jivesoftware.community.widget.Widget$ContainerSize"].LARGE />
                 </#if>
             </#list>
         </#if>
        </div>
    </div>

....and the rest of the file loads the widgets in the right container (green B)

    <div class="jive-body-layout-s">
         <div id="jive-widget-container_2" class="jive-widget-container jive-widget-container-small">
         <#if widgetFrames?exists && widgetFrames.containsKey(2?int)>
             <#list widgetFrames.get(2?int) as widgetFrame>
                 <#if widgets?exists>
                     <@jive.editWidgetFrame widgetFrame=widgetFrame />
                 <#else>
                     <@jive.displayWidgetFrame widgetFrame=widgetFrame size=enums["com.jivesoftware.community.widget.Widget$ContainerSize"].SMALL />
                 </#if>
             </#list>
         </#if>
         </div>
    </div>
</div>

They widgetFrames are available from this call to the widgetManager in CommunityAction.getWidgetFrames():

return widgetManager.getPublishedWidgetFrames(getCommunity());

And that's it! The widgets are displayed.

III. How we customized this

As you've seen, it's all initiated by NOT having anything setup the first time you are directed to the community.ftl file. So, we needed to ensure that there was a widget layout, and within that widget layout there are widget frames. So, during our secure space creation we need to hook into this ourselves. Have a look at how we're doing it:

1. Get a list of all the widgets in the system

Map<WidgetDescriptor, Widget> widgets = widgetManager.getAvailableWidgets();

2. Identify the two widgets we want to add initially, and loop through all the available widgets and hold onto them

Widget actionWidget = null;
Widget openCasesWidget = null;
for(Iterator<WidgetDescriptor> it = widgets.keySet().iterator(); it.hasNext(); ) {
     WidgetDescriptor descriptor = it.next();
     Widget widget = widgets.get(descriptor);
 
     if(descriptor.getClassName().equalsIgnoreCase("com.jivesoftware.community.widget.impl.CommunityActionsWidget")) {
          actionWidget = widget;
     } else if(descriptor.getClassName().equalsIgnoreCase("com.jivesoftware.community.portal.widgets.OpenCasesWidget")) {
          openCasesWidget = widget;
     }
}

3. Then, as we saw above, we need to get the widget layout desired and add it to the newly created secure community

try {
  WidgetLayoutDescriptor wld = getWidgetLayoutByName(TwoColumnLargeLeftColumnLayout.class.getName());
  WidgetLayout wl = widgetManager.getWidgetLayout(wld);
  widgetManager.addWidgetLayout(community, wl);
  widgetManager.publishWidgetLayout(community);
}

4. Finally, setup our OpenCasesWidget (custom built by us) and the Actions widget. They are mapped to the correct lay out by the matching up of parentObjectType and ParentObjectID.

//load the widgets
WidgetFrameBean widgetBean = new WidgetFrameBean();
widgetBean.setWidgetID(openCasesWidget.getID());
widgetBean.setContainerID(1);
widgetBean.setParentObjectID(community.getID());
widgetBean.setParentObjectType(JiveConstants.COMMUNITY);
widgetBean.setPublished(true);
widgetManager.addWidgetFrame(widgetBean);
 
WidgetFrameBean actionWidgetBean = new WidgetFrameBean();
actionWidgetBean.setWidgetID(actionWidget.getID());
actionWidgetBean.setContainerID(2);
actionWidgetBean.setParentObjectID(community.getID());
actionWidgetBean.setParentObjectType(JiveConstants.COMMUNITY);
actionWidgetBean.setPublished(true);
widgetManager.addWidgetFrame(actionWidgetBean);

5. All done!

That is how we are creating the communities and customizing their overview tabs. Hope this has been helpful!

Let me know if there are any questions on the above functionality

Customization Part 3: Widgets

communities@jivesoftware.com — Mon, 30 Jun 2008 15:12:39 GMT

This post is the third in a series of blog posts about customizing for Clearspace 2.x. The previous posts covered general information about Customizations in Clearspace 2.x and upgrading themes and FTL files. This post continues the series with more information about widgets.

Widgets can be used much more broadly in version 2 than previously, so most of your widget-specific upgrade changes are related to this broader support. In version 1 a system or space administrator could use widgets only to assemble a space or community overview page. In version 2 both administrators and users can customize page layouts in several areas. Widgets can be used on the Clearspace instance home page (which has been rendered from main.ftl), a user's personal home page, a community/space overview page, a project overview page.

Note that unless your widget is extremely simple, you're likely to also need to keep in mind API changes and FreeMarker changes. For example, version 2 requires that widgets acquire references to Clearspace manager beans using Spring. The rest of widget development model -- artifacts involved, how you deploy them, and so on -- is unchanged from version 1.

When upgrading a widget (or developing a new one on version 2), you use the @WidgetTypeMarker annotation to specify which of the display contexts your widget is allowed in. Deciding which contexts to allow is an important part of your widget's design. For example, you might decide that a widget that takes a very individual-oriented set of property values (such as the Tag widget, which displays content associated with a particular tag) isn't useful in high-level contexts such as the instance or space home pages (where the broad set of people viewing might want views on a large variety of tags).

The @WidgetTypeMarker annotation supports values from the WidgetType enumeration. Here's an example that includes all of those values:

@WidgetTypeMarker({WidgetType.HOMEPAGE, WidgetType.PERSONALIZEDHOMEPAGE, 
    WidgetType.COMMUNITY, WidgetType.PROJECT})
@PropertyNames("myProperty")
public class MyWidget extends BaseWidget {
    // Implementation code omitted.
}

In order to reduce the tight coupling between the widget views (which are typically built using FreeMarker) and the rest of the Clearspace application, the widget context that was previously populated with a reference to the current context via a JiveContext instance has been modified so that the widget view no longer has access to that instance. That means that you'll need to provide everything that your widget view needs through the properties that the widget interface requires. Typically you'll create a widget class that extends BaseWidget and then you'll override this method:

protected Map<String, Object> loadProperties(WidgetContext widgetContext, ContainerSize size)

So in the previous version of Clearspace, you might have had something like this in the FTL file that's your widget's view:

${widgetContext.jiveContext.communityManager.rootCommunity.ID?c}

Because the JiveContext instance has been removed from the WidgetContext class, you'll need to provide your view with the properties it needs explicitly in your widget. Here's an example:

public class MyWidget extends BaseWidget {

    // Declare a property variable and setter for injection by Spring.
    private CommunityManager communityManager;
    public void setCommunityManager(CommunityManager cm) {
        this.communityManager = cm;
    }

    protected Map<String, Object> loadProperties(WidgetContext widgetContext, 
        ContainerSize size)
    {
        Map<String, Object> properties = super.loadProperties(widgetContext, size);
        // Implementation code omitted.
        properties.put("rootCommunityID", communityManager.getRootCommunity().getID());
        return properties;
    }
}

Finally, because you can create a widget that exists in multiple parts of the application (the homepage, a personalized homepage, a community, a project), you'll sometimes want to change the behavior of your widget based on where the widget is being rendered. You can determine the render context of your widget by checking the type of the WidgetContext class that you're given in the loadProperties method. Here's some example code that shows how you can determine what context the widget is in:

public class MyWidget extends BaseWidget {
    protected Map<String, Object> loadProperties(WidgetContext widgetContext, ContainerSize size) {
        Map<String, Object> properties = super.loadProperties(widgetContext, size);
        if (widgetContext.getWidgetType() == WidgetType.COMMUNITY) {
            CommunityWidgetContext cwc = (CommunityWidgetContext)widgetContext;
            // Do something specific for the community
        }
        else if (widgetContext.getWidgetType() == WidgetType.HOMEPAGE) {
            HomepageWidgetContext hwc = (HomepageWidgetContext)widgetContext;
            // Do something specific for the homepage
        } 
        else if (widgetContext.getWidgetType() == WidgetType.PERSONALIZEDHOMEPAGE) {
            PersonalizedHomepageWidgetContext phwc = 
                (PersonalizedHomepageWidgetContext)widgetContext;
            // Do something specific for the personalized homepage    
        }
        else if (widgetContext.getWidgetType() == WidgetType.PROJECT) {
            ProjectWidgetContext wwc = (ProjectWidgetContext)widgetContext;
            // Do something specific for the project
        }
    
        properties.put("rootCommunityID", communityManager.getRootCommunity().getID());
        return properties;
    }
}

The information above along with more details can be found in the Upgrading Extensions to 2.0 documentation.

You can also watch a video and download a presentation to learn more about how to write new widgets for Clearspace 2.0 from Aaron Johnson, Engineering Manager at Jive.

New Widgets

aaron@jivesoftware.com — Fri, 11 Jan 2008 00:49:02 GMT

In a future release of Clearspace we're talking about adding a personalized homepage feature, much like My.Yahoo.com or Google.com/ig, where users can add Clearspace widgets like 'Recent Content' or 'Top Members' to their homepage. A lot of the widgets that we debuted in the 'customize a community' feature (have you seen the video?) will be available for users on the homepage, but we'd like to hear from you: assuming you had a customizable homepage and you could use Clearspace like you use My.Yahoo.com or Google.com/ig, what widgets (Clearspace related or unrelated) would make your day?

Spruce Up Your UI with Your Own Widget

steve@jivesoftware.com — Wed, 21 Nov 2007 15:42:59 GMT

We were really pleased at how popular widgets were from the start. It seems as if everyone has an idea for something they want to "widgetize." So it's great that they're so easy to build.

If you haven't checked out widget development in Clearspace, now's a great time to do it. Version 1.8 improves on widgets' debut by adding support for including them in plugins. Now you can build a widget and get that handy autodeployment support you already get with macros, actions, and the like.

If you have looked at building widgets, then you know that the version 1.8 changes make them easier to deploy, but they were easy to build from the start. For an introductory tutorial on building widgets, check out #. And be sure to download the # for a sample.