Storing and retrieving data for portal modules using the CustomData API

Introduction

The CustomData API is used for storing data related to portal module. There are two types of data that are stored.

1. Global data for the module. i.e. settings and global preferences.
2. User preferences for the module. i.e. any preferences that the user can choose themselves.

There are two methods for storing and retrieving this data. The first is to use the Blackboard JSP tags, the second is to use the Building blocks API directly. This document discusses how to use the API directly.

To store and load preferences, there are 4 parts of the Building blocks API you will need to use. These are:

1. PortalViewerDbLoader and associated classes.
2. The Module class.
3. The BbPersistenceManager framework.
4. The CustomData framework.

What is a PortalViewer?

A "PortalViewer" is simply a reference to a blackboard user associated with a particular instance of the portal.

Retrieving CustomData for a User

To retrieve a user's personalisation data for a module, you need both an Id for the module, and an Id for the PortalViewer. The portal Viewer can be obtained by using the following code.

Context ctx = BbServiceManager.getContextManager().setContext(request);
PortalViewer portalViewer = PortalViewerDbLoader.Default.getInstance().loadByUserId(ctx.getUser().getId());

Once we have the PortalViewer for the current user, we need to get the module. The easiest way to do this is by retrieving the module from the request object.

Module module = (Module) request.getAttribute("blackboard.portal.data.Module");

If you want to access module data in code that isn't executed as part of the module request, you will have to pass the module ID back to your code as a request parameter.
The following example shows the module ID being passed to an AJAX handler.
Two things to note are:

1. The module id string has already been created in the controller by calling something like moduleIdStr = module.getId().toExternalString(). It is being inserted into the AJAX URL using a JSP EL expression.
2. Because the module JSP is included, it "forgets" it's original URL, so you need to generate a URL that is relative to the root of the server. eg. ${ actionBean.pluginUriStem }modules/View.action

    function sendCollapsedState(elementId,state) {
        new Ajax.Request("${actionBean.pluginUriStem}modules/View.action?saveCollapsedState&moduleIdStr=${actionBean.moduleIdStr}&elementId="+elementId+"&collapsedState="+state, {
            method: 'get',
            onSuccess: function(transport) {
                var notice = $('notice');
                if (transport.responseText.match(/FAILURE/)) {
                    alert("Couldn't save state of the my courses module");
                }
            }
        });
    }

In order to get the module reference, this code must be executed in the JSP that is defined as the module view in bb-manifest.xml. In the example below, the view is a servlet mapping named view.html

<module-type ext-ref="gu-custommycourses" title="Griffith My Courses Module" uicreatable="true">
    <jsp-dir>module</jsp-dir>
    <jsp>
        <view>view.htm</view>
    </jsp>
</module-type>

Once we have the Module and PortalViewer, we use a static method on CustomData to get a CustomData instance containing the user's personalisation properties.

data = CustomData.getCustomData(module.getId(), portalViewer.getId());