B2Context package

This package provides basic support functions for Building Blocks including easy access to language bundle values, configuration settings, navigation items, receipt messages and simple logging. An example Building Block (B2Context-demo) illustrating the use of this package is also provided.

For Building Blocks to be installed with the April 2014 release of Learn 9.1 (or later) it is essential that the 1.4.01 release (or later) of this package is used.

The B2Context package is written for use with Building Blocks written for Learn 9.0 (or later). Note that the package uses the following classes which are not publicly supported by Blackboard:

• blackboard.data.ReceiptOptions
• blackboard.data.navigation.NavigationItem
• blackboard.data.registry.Registry
• blackboard.data.registry.UserRegistryEntry
• blackboard.persist.navigation.NavigationItemDbLoader
• blackboard.persist.registry.UserRegistryEntryDbLoader
• blackboard.persist.registry.UserRegistryEntryDbPersister
• blackboard.platform.intl.BbResourceBundle
• blackboard.platform.servlet.InlineReceiptUtil
• blackboard.portal.data.Module

The package should be included in the war file for any Building Block which makes use of it.

This package is comprised of a single published class which is described in the JavaDocs documentation. The methods defined provide access to the following functionality:

• contextual information
• configuration settings
• utility methods

Contextual information

These methods access properties from the Building Block, Blackboard context or the HTTP request.

Building Block properties

• getHandle() - get the handle for the Building Block
• getPath() - get the path for the current Building Block
• getPlugIn() - get the plugin object for the Building Block
• getResourceString() - get a resource string from the bundle for the current locale
• getResourceStrings() - get all the resource strings from the bundle for the current locale
• getServerUrl() - get the URL for the current Building Block
• getVendorId() - get the vendor ID for the Building Block
• getWebappRoot() - get the file root for the Building Block

The resource strings are extracted from the bb-manifest properties file for the current locale; for example, bb-manifest-en_GB.properties located in the WEB-INF/bundles directory.

Blackboard context

• getContext() - get the current Blackboard context object
• setContext() - set the current Blackboard context object (see below)
• getNavigationItem() - get a navigation item
• setReceipt() - set a receipt option
• setReceiptOptions() - set success and/or error receipts to a session or URL

Setting the context object is useful when creating a context from an incoming HTTP request. The Blackboard context object has methods for checking whether it contains a course, content or group context. These methods are used by the configuration settings methods (see below) to determine where to look for non-global settings. It is possible to override the context methods using the setIgnoreCourseContext, setIgnoreContentContext and setIgnoreGroupContext. For example, when calling the getSettings method from within a content handler, the non-global anonymous settings will be taken from the content area. However, if ignoreContentContext is set to true, the content context will be ignored and settings will be taken from the course context (just as if there was no current content context).

HTTP request

• getRequest() - get the current HTTP request object
• getRequestParameter() - gets a parameter from the HTTP request
• getRequestParameters() - gets the values of all parameters from the HTTP request
• getRequestParameterValues() - gets the value(s) for a parameter from the HTTP request

These methods provide support for specifying default values for missing request parameters and also for combining multiple values for a single parameter.

Configuration settings

• clearSettings() - delete all configuration settings
• getSaveEmptyValues() - get the SaveEmptyValues setting
• getSetting() - get a configuration setting value
• getSettings() - get a list of all configuration settings
• persistSettings() - permanently save the current configuration setting values
• setSaveEmptyValues() - set the SaveEmptyValues setting
• setSetting() - set a configuration setting value

These methods enable simple settings (name and value pairs) to be loaded and saved for use with a Building Block. The SaveEmptyValues setting determines whether empty strings are saved or whether the setting is removed. Settings are divided into four categories based on the values of global and anonymous:

The settings for each category are saved in the following locations:

Utility methods

• getEditMode() - gets the current status of edit mode (aways returns false for Learn 9.0)
• getVersionNumber() - gets the Blackboard version number (e.g. 9.0.505.0)
• getIsVersion() - checks whether the Blackboard version number is the version passed or later (for the April 2014 release, use a service pack number of "201404")

A Building Block (B2Context-demo) is available for download to illustrate how to make use of this package. The examples used below are based on this Building Block.

Configuration settings

System settings

The following extract is from the system/simple.jsp file which displays a form containing a single mandatory text field and saves the value entered as a system-wide configuration setting:

...

<%
  String LOCATION_FIELD_NAME = "location";

  B2Context b2Context = new B2Context(request);
  String cancelUrl = "index.jsp";

  if (request.getMethod().equalsIgnoreCase("POST")) {
    String location = b2Context.getRequestParameter(LOCATION_FIELD_NAME, "").trim();
    b2Context.setSetting(LOCATION_FIELD_NAME, location);

    b2Context.persistSettings();
    response.sendRedirect(cancelUrl + "?inline_receipt_message=" +
       b2Context.getResourceString("receipt.success"));
  }

  pageContext.setAttribute("bundle", b2Context.getResourceStrings());
  pageContext.setAttribute("cancelUrl", cancelUrl);
%>
  <bbNG:pageHeader instructions="${bundle['page.system.simple.instructions']}">
    <bbNG:breadcrumbBar environment="SYS_ADMIN_PANEL" navItem="admin_plugin_manage">
      <bbNG:breadcrumb href="index.jsp" title="${bundle['plugin.name']}" />
      <bbNG:breadcrumb title="${bundle['page.system.simple.title']}" />
    </bbNG:breadcrumbBar>
    <bbNG:pageTitleBar iconUrl="../images/spvsp.gif" showTitleBar="true" title="${bundle['page.system.simple.title']}"/>
  </bbNG:pageHeader>
  <bbNG:form action="" id="id_simpleForm" name="simpleForm" method="post" onsubmit="return validateForm();">
  <bbNG:dataCollection markUnsavedChanges="true" showSubmitButtons="true">
    <bbNG:step hideNumber="false" id="stepOne" title="${bundle['page.system.simple.step1.title']}" instructions="${bundle['page.system.simple.step1.instructions']}">
      <bbNG:dataElement isRequired="true" label="${bundle['page.system.simple.step1.location.label']}">
        <bbNG:textElement name="<%=LOCATION_FIELD_NAME%>" value="<%=b2Context.getSetting(LOCATION_FIELD_NAME)%>" helpText="${bundle['page.system.simple.step1.location.instructions']}" size="30" minLength="1" />
      </bbNG:dataElement>
    </bbNG:step>
    <bbNG:stepSubmit hideNumber="false" showCancelButton="true" cancelUrl="${cancelUrl}" />
  </bbNG:dataCollection>
  </bbNG:form>

...

An instance of the B2Context class is created:

  B2Context b2Context = new B2Context(request);

The value of the form field submitted can be extracted with a default value of an empty string:

  String location = b2Context.getRequestParameter(LOCATION_FIELD_NAME, "");

The value submitted can be saved (in memory) as a system configuration setting (i.e. global and anonymous):

  b2Context.setSetting(LOCATION_FIELD_NAME, location);

which is equivalent to:

  b2Context.setSetting(true, true, LOCATION_FIELD_NAME, location);

To save the settings permanently:

  b2Context.persistSettings();

A string from a resource bundle can be obtained by name:

  String message = b2Context.getResourceString("receipt.success");

or all resource strings can be saved in a Map:

  Map<String,String> messages = b2Context.getResourceStrings();

The value of a system configuration setting can be accessed:

  String value = b2Context.getSetting(LOCATION_FIELD_NAME);

which may also be given a default value to use when the setting does not already exist:

  String value = b2Context.getSetting(true, true, LOCATION_FIELD_NAME, "My default");

User settings

The system/user.jsp file displays a form containing a single optional text field and saves the value entered as a user-specific setting.

Because the setting is optional and a default is used when no value exists, it is convenient not to save empty strings:

  b2Context.setSaveEmptyValues(false);

The anonymous parameter is set to false to denote that the setting is specific to the user:

  b2Context.setSetting(true, false, HOME_FIELD_NAME, location);

When persisting the settings remember to specify the same category:

  b2Context.persistSettings(true, false);

If no value exists for a setting then it is set to the value of the system configuration setting and a receipt displayed on the page to inform the user:

  if (b2Context.getSetting(true, false, HOME_FIELD_NAME).length() <= 0) {
    b2Context.setSetting(true, false, HOME_FIELD_NAME,
       b2Context.getSetting(LOCATION_FIELD_NAME));
    b2Context.setReceipt(b2Context.getResourceString("system.user.default"), false);
  }

Course settings

The course/simple.jsp file displays a form containing a single optional text field and saves the value entered as a course-specific setting. Set the global parameter to false to denote that the setting is specific to the context:

  b2Context.setSetting(false, true, LOCATION_FIELD_NAME, location);
...
  b2Context.persistSettings(false, true);
...
  String value = b2Context.getSetting(false, true, LOCATION_FIELD_NAME);

Contextual information

The B2Context package provides methods to obtain information about the Building Block. For example, the vendorID and the handle specified in the bb-manifest.xml file:

  String vendorID = b2Context.getVendorId();
  String handle = b2Context.getHandle();

The URL for the root of the Building Block can be consructed by combining the server URL and the path:

  String rootUrl = b2Context.getServerUrl() + b2Context.getPath();

The location of this root directory in the file system can be obtained by:

  String rootDir = b2Context.getWebappRoot();

Navigation items provide details of the location for specific areas within Learn 9; for example, to obtain the URL for the Installed Blocks page on the System Admin tab:

  String url = b2Context.getNavigationItem("admin_plugin_manage").getHref();

The names of navigation items can be found from the internal_handle column of the navigation_item table.

This work is written by Stephen Vickers and is released under a GNU Lesser General Public Licence. The B2Context package can be downloaded from OSCELOT. The source files are available from the ceLTIc Project repository, where any issues should be reported.