File Structure of a Building Block

As you begin your Building Block development, you'll notice that the file structure is identical to that of a Java-based web application. In fact, you can use the Dynamic Web Project wizard in Eclipse or its NetBeans equivalent to get a good shell for your project. The only difference between a Building Block and a webapp is the presence of the bb-manifest.xml file which is used to specify to the Blackboard application where your tool will hook into the GUI and define the operations it is allowed to perform.

About the bb-manifest.xml file

The bb-manifest.xml file is very similar in purpose to the portlet.xml and related configuration files of a JSR-168 portlet. More information on the bb-manifest can be found in the "Building Block XML Packaging Format" section of the Building Blocks Developer Guide found in the Documentation area of this site.

The bb-manifest is broken up into five main areas: basic configuration information, content handler definition, tool application definitions, module definitions, and security/permissions. Depending on the type and complexity of the Building Block you are developing, your plugin may contain as few as two or as many as all of these sections. More information on each follows.

Basic Information and Configuration

In this section of the manifest, you define the name of the application, description, vendor/developer information, the minimum version of Blackboard the tool requires, and a link to configure the Building Block among other details.

Content Handlers (user for Custom Content Type Building Blocks)

Content handlers allow you to add custom content types above and beyond those offered in the core product. For an example, one open source content type Building Block allows an instructor to add a photo slideshow to his/her course. Photo slideshows are not offered in the core product but can be added via this Building Block to relay visual information to learners. If you are developing a custom type of content handler, you will define the user interface hooks that tell Blackboard how to behave when a user clicks the links to add, modify, and remove custom content. You can also define the icons associated with your content type that display in the content areas of a course. Content type Building Blocks are added to the drop-down list of options in each course content area.

Application Definition (used for Tool Type Building Blocks)

Tool type Building Blocks allow you to add links to your application in any of several areas of the core application. Some of these areas are accessible to students, others to teachers, others to all users, and others only to Blackboard administrators. These tools allow you to place links to either external applications or applications written to extend the Blackboard application itself. An example would be a group tool that teachers can use to automate randomized creation of course groups that offer functionality beyond the group tools of the core application. This part of the bb-manifest allows you to specify link names, link URLs, and link types/locations within the Blackboard GUI.

Module Definitions

In this area, you can define the functionality of portal modules which can be customized and added to the My Institution page or any other portal page. These modules can be used to visually display information to your users.

More information on Portal Modules can be found in the Module Developer Guide located in the Documentation area of this site. This documentation is separated from the core Building Blocks Developer Guide. Portal module functionality including customizable modules, institution roles, and tabs is only available to clients who license the Blackboard Community System.

Security & Permissions

This area of the bb-manifest file allows you to specify which areas of the application your Building Block explicitly has access to in a very granular fashion. It also allows you to specify to which external servers your Building Block has access. In addition to allowing the developer to better secure his/her application, these permission definitions allow a system administrator to evaluate what types and levels of access a given Building Block will expose their application server to.