My First Building Block

Presented By Tracy Engwirda28 September, 2005

Overview

• Background• Planning

– UI Integration– Which APIs

• Package Structure• Manifest Structure• Security Framework• UI Taglibs• Building Blocks Manager• .. and more

Terminology

• Building Blocks Program– All development and integration with Blackboard products

• Building Blocks Framework– The set of patterns and objects that allow interaction with all of

Blackboard’s products

• Building Blocks API– The Java and .NET interfaces

• Building Blocks Manager– The management interface for Building Blocks

• Building Block– An application that relies on the Building Blocks API

• Blackboard Enabled– A quality assurance and testing program for Building Blocks

Terminology

• Building Block Types – Plug-in

• Stand alone• Communicate only with Learning System

– Bridge• Communicates with external server(s) and

Learning System• Will not function without external server

Planning

• What are you project goals?

• What are the application requirements?

• How are you going to build your application?– JSP? Servlet? Web Service?

• Where are you going to “hook” your application?

• Which APIs are you going to use?

Planning

• Where are you going to hook your application into Blackboard?

UI Entry Points

• New Course Tool

• New Course Communication Tool

• New Control Panel Tool

• New System Admin Tool

• New Portal Module

• New Content Type

• New User Tool

Entry Points

• Programmatic Entry Points– Specified in bb-manifest.xml

• Manual Entry Points– System Administrator created

Course Tool

<link>

<type value="tool"/>

<name value="Sample Tool"/>

<url value="tool_1/tool.jsp" />

<description value="The description of Sample Tool." />

<icons>

<listitem value="/images/icon.gif"/>

</icons>

</link>

Course ID is passed to page

Course Communication Tool

<link>

<type value="communication"/>

<name value="Sample Communication Tool"/>

<url value="communication_1/tool.jsp" />

<description value="The description of Sample Communication Tool." />

<icons>

<listitem value="images/icon.gif"/>

</icons>

</link>

Course ID is passed to page

Course Control Panel

<link>

<type value="course_tool"/>

<name value="Sample Control Panel Tool"/>

<url value="control_panel_1/tool.jsp" />

<description value="The description of Control Panel Tool." />

<icons>

<listitem value="images/icon.gif"/>

</icons>

</link>

Course ID is passed to page

System Admin Panel

<link>

<type value="system_tool"/>

<name value="Sample Admin Panel Tool"/>

<url value="admin_panel_1/tool.jsp" />

<description value="The description of Control Panel Tool." />

<icons>

<listitem value="images/icon.gif"/>

</icons>

</link>

Nothing passed to page

Content Type

<content-handler>

<name value="Sample Content"/>

<handle value= "resource/x-bbgs-sample"/>

<http-actions>

<create value="handler/create.jsp"/>

<modify value="handler/modify.jsp"/>

<remove value="handler/remove.jsp"/>

</http-actions>

<icons>

<toolbar value="/images/add_ch1.gif"/>

<listitem value="/images/icon.gif"/>

</icons>

</content-handler>

Course ID and Container ID are passed to page

Portal Module

<module-defs>

<module-type ext-ref="smpl-module" title="Sample Module Type" uicreatable="true">

<jsp-dir>module</jsp-dir>

<jsp>

<view>view.jsp</view>

<admin>admin.jsp</admin>

</jsp>

</module-type>

</module-defs>

Nothing is passed to page

User Tool

<link>

<type value="user_tool"/>

<name value="Sample User Tool"/>

<url value="user_tool_1/tool.jsp" />

<description value="The description of User Tool." />

<icons>

<listitem value="images/icon.gif"/>

</icons>

</link>

Nothing passed to page

Custom Tab

• System admin can change the location of a tab to point to a Building Block

Custom Course Link

• System admin or course instructor change add a Building Block to the course navigation area

Hidden Link

• A page does not need to be in the manifest in order to be loaded.

Planning

• Which APIs are you going to use?

API Capabilities

• Building Blocks APIs– Announcement (read and write)– Calendar (read and write)– Content (read and write)– Gradebook (read and write)– Session (read and write)– File system (read and write)– *User (read)– *Course (read)– *Membership (read)– .. And Many, many more!

API Capabilities

• How to write to User/Course/Membership? Event APIs

• Event APIs use a similar data model to the Building Block APIs but has a different security model. Data object naming conventions match IMS structure of snapshot data.

API Capabilities

• Event APIs– Person (User)– Group (Course / Organization) – Membership– Catalog Category– Catalog Link– Data Source Key

Planning

• Installation

Installation

• Only system administrators can install

• No restart required with Bb 6

• Must confirm Building Block permissions

• Often requires configuration

• Installation is through the Building Blocks Manager

• Heart of the Blackboard Platform

• Controls security, permissions, and availability

• Manages the “hook points” within the UI

• Handles deployment

Building Block Manager

Blackboard Platform(LS/TS/CP)

DB

File System

Content

Gra

debook

An

no

un

cem

en

ts

Use

r

Course

Mem

bership

Calenda

r

Persistence

Plugin

Security

Session

TagLib (UI)

Building Blocks ManagerAPI Wrappers & Convenience Methods

Data Integrity Enforcement

User Interface H

ooks / Availability

Context P

assing

Security &

Manifest C

ontrols

Deploym

ent & T

racking

Building Block Manager

Building Block Manager

Structure of Building Blocks

Building Block = Webapp

• A Building Block is a Java Web Application (webapp) with one extra file

• The extra file is bb-manifest.xml

Directory Layout

Shared via web

Hidden from web

Package Format

• A webapp is a zip file with a specific directory structure

• WinZip, PkZip, Java’s Jar utility, or Ant will all create the correct package

• Even though it is a zip file, the extension does not matter (.zip, .war, .bb will all work)

WEB-INF

• Hidden from web

• Contents– web.xml– bb-manifest.xml– Config directory– Classes directory– Lib directory

Config Directory

• Hidden from web

• Only accessible by the Building Block

• Can contain anything– One option for storing your application data.

• No size limit

Custom Code and Libraries

• Classes– Stored in WEB-INF\classes

• Jars– Stored in WEB-INF\lib– Automatically on classpath via custom

classloader

Manifest Structure

• bb-manifest.xml– Set of directives the developer provides

• Building Blocks Configuration• Application Definitions

– Content Handlers– UI Links– Portal Modules

• Security Declarations

• Let’s Take a Look…

bb-manifest.xml File<?xml version="1.0" encoding="ISO-8859-1"?><manifest> <plugin> <name value= "Blackboard Link Checker"/> <handle value= "link-checker"/> <description value= "This plugin is for checking and disabling external links in Blackboard."/> <version value= "2.0.4"/> <requires> <bbversion value="6.0.0"/> </requires> <vendor> <id value="bb"/> <name value="Blackboard Research and Development"/> <url value="http://www.blackboard.com/" /> <description value="Blackboard Research and Development Team" /> </vendor> <http-actions> <config value="admin/config.jsp"/> <remove value="admin/remove.jsp"/> </http-actions> <application-defs> <application handle="linkchecker" type="course" use-ssl="false" name="Link Checker" can-allow-guest="true" small-icon="" large-icon="">

bb-manifest.xml File<?xml version="1.0" encoding="ISO-8859-1"?><manifest> <plugin> <name value= "Blackboard Link Checker"/> <handle value= "link-checker"/> <description value= "This plugin is for checking and disabling external links in Blackboard."/> <version value= "2.0.4"/> <requires> <bbversion value="6.0.0"/> </requires> <vendor> <id value="bb"/> <name value="Blackboard Research and Development"/> <url value="http://www.blackboard.com/" /> <description value="Blackboard Research and Development Team" /> </vendor> <http-actions> <config value="admin/config.jsp"/> <remove value="admin/remove.jsp"/> </http-actions> <application-defs> <application handle="linkchecker" type="course" use-ssl="false" name="Link Checker" can-allow-guest="true" small-icon="" large-icon="">

bb-manifest.xml File <application-defs> <application handle="linkchecker" type="course" use-ssl="false" name="Link Checker“> <description lang="en_US">Link Checker tool installed with the Link Checker Plugin</description> <links> <link> <type value="course_tool"/> <name value="Link Checker"/> <url value="links/checklinks.jsp" /> <description value="Checks and disables links in Blackboard." /> <icons> <listitem value="images/link-logo.gif"/> </icons> </link> </links> </application> </application-defs> <permissions> <permission type="persist" name="Content" actions="modify"/> <permission type="attribute" name="user.authinfo" actions="get"/> <permission type="socket" name="*" actions="connect"/> </permissions> </plugin></manifest>

bb-manifest.xml File <application-defs> <application handle="linkchecker" type="course" use-ssl="false" name="Link Checker“> <description lang="en_US">Link Checker tool installed with the Link Checker Plugin</description> <links> <link> <type value="course_tool"/> <name value="Link Checker"/> <url value="links/checklinks.jsp" /> <description value="Checks and disables links in Blackboard." /> <icons> <listitem value="images/link-logo.gif"/> </icons> </link> </links> </application> </application-defs> <permissions> <permission type="persist" name="Content" actions="modify"/> <permission type="attribute" name="user.authinfo" actions="get"/> <permission type="socket" name="*" actions="connect"/> </permissions> </plugin></manifest>

bb-manifest.xml File <application-defs> <application handle="linkchecker" type="course" use-ssl="false" name="Link Checker“> <description lang="en_US">Link Checker tool installed with the Link Checker Plugin</description> <links> <link> <type value="course_tool"/> <name value="Link Checker"/> <url value="links/checklinks.jsp" /> <description value="Checks and disables links in Blackboard." /> <icons> <listitem value="images/link-logo.gif"/> </icons> </link> </links> </application> </application-defs> <permissions> <permission type="persist" name="Content" actions="modify"/> <permission type="attribute" name="user.authinfo" actions="get"/> <permission type="socket" name="*" actions="connect"/> </permissions> </plugin></manifest>

Security Framework

• Security must be explicitly declared in the bb-manifest.xml file.

• XML Format corresponds closely with the format for Standard Java policy files

• Security will be enforced by the JVM

UI Taglibs

• XML style tags that can be placed on a jsp page.

• Blackboard supplies two sets of taglibs– bbUI for making pages fit in with the

product– bbData for giving pages context and virtual

installation information

• Specify your own in web.xml

More information• Building Blocks Website

http://www.blackboard.com/developers/

– Building Blocks Catalog– Software Development Kit (SDK)

• Blackboard Developer Network (BbDN)http://behind.blackboard.com/

– Learning System Developer License– Communities, Knowledge Base, Code Snippets, White

Papers, Beta Software

• Other Community Resources– Open Source User Group and BBUG forums http://www.bb-

opensource.org/

Why Start from Scratch?

• Start with a sample Building Block

• Reuse existing code

• Customize to meet your needs

Let’s take a look at some real code…

Enough of the theory!

Questions?