1. © Blackboard, Inc. All rights reserved. My First Building Block as a Content Type Heather Natour Senior Lead Engineer Blackboard Inc. July 18 th 1:30pm

2. Overview » Types of Content Oriented Building Block Integrations » Look at Various Implementations » Tips and Tricks » Questions

3. Types of Integrations » Content-Handlers which work with internal data structures and use Building Block perisisters for data storage » Content-Handlers which work with internal data structures and use other means for storage (XML, Java Property Files, etc) » Content-Handlers which simply link to an external system

4. Before we look at differences… » Let’s examine the commonalities…. » Let’s quickly walk through our Building Block Planning Process (From the My First Building Block Presentation) »

5. Planning » Where are you going to hook your application into Blackboard?

6. User Interface Integration Content-Handlers appear under the “add other” pull down from the content areas.

7. Planning » Which APIs are you going to use?

8. API Capabilities » Building Blocks API » 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)

9. Structure of the Building Block » It’s a standard JAVA Web Application (Webapp) with some additional descriptive data (XML Files) that is used by Blackboard to manage registration, deployment, security, and management.

10. Directory Structure

11. Package Format » A webapp is a zip file with a specific directory structure » WinZip, PkZip, or Java’s Jar utility will all create the correct package » Even though it is a zip file, the extension does not matter (.zip,.war,.bb will all work)

12. WEB-INF » Hidden from web » Contents » web.xml » bb-manifest.xml » Config directory » Classes directory » Lib directory

13. Config Directory » Hidden from web » Only directory that is owned by your building block » Can contain anything » No size limit

14. Custom Code and Libraries » Classes » Stored in WEB-INF\classes » Jars » Stored in WEB-INF\lib » Automatically on classpath via custom classloader

15. 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 at one for content …

16. Bb-manifest.xml »

17. Bb-manifest.xml »... » »... Set Handler Set Create, Modify, and Remove handlers

18. Bb-manifest.xml »... »

19. Now we know the structure… » Once we have decided our directory layout and created (customized) our bb-manifest.xml file, we are ready to look at the JSP pages which comprise our webapp.

20. With that… » We need to setup a structure for our webapp

21. Deploy the skeleton » It’s far easier to deploy the skeleton webapp and then make your changes directly on your DEVELOPMENT server. » Files are located in blackboard/content/ci/bb_bb60/xxx-xxxx/webapp »

22. Some good things to know… » Course ID and Container ID are passed to pages » If you use the taglibs (BbUI and BbData) you will always have access to the session data, user data, consistent UI widgets, etc. » You have access to read/write files to your webapps config space » Good for configuration data or application data!

23. Create.jsp » <% » /////////////////////////////////////////////////////////// » // Filename: Create.jsp » // Desc: Part of the sample content-handler, this file » // is responsible for displaying the form to gather » // the data for the creation of the content object. » /////////////////////////////////////////////////////////// » %> » <%@ page import=" » blackboard.platform.*, » blackboard.platform.plugin.*" » errorPage="/error.jsp" » %> » Page Imports Import Tag Libs Establish Context

24. Create.jsp » <% » if (!PlugInUtil.authorizeForCourseControlPanel(request, response)) » return; » %> » » "> » » "> » » SAMPLE CONTENT HANDLER » Check for Auth Doc and Course Taglibs Course and Content IDs are passed in Breadcrumb

25. Create.jsp

26. » » Yes No » Create.jsp

27. »

28. Create.jsp

29. Create_proc.jsp » Just the Highlights! » // retrieve the Db persistence manager from the persistence service » BbPersistenceManager bbPm = BbServiceManager.getPersistenceService().getDbPersistenceManager(); » // generate the internal IDs for the course and parent » Id courseId = bbPm.generateId(Course.COURSE_DATA_TYPE,request.getParameter("course_id")); » Id parentId = bbPm.generateId(CourseDocument.COURSE_DOCUMENT_DATA_TYPE,request.getParameter("parent_ id")); » // create a new content iteam » Content courseDoc = new Content(); » //set the title » courseDoc.setTitle(request.getParameter("title"));

30. Create_proc.jsp » // set the main data (as HTML data) » String strMainData = request.getParameter("maindata"); » FormattedText text = new FormattedText(strMainData,FormattedText.Type.HTML); » courseDoc.setBody( text ); » // set the parent ID » courseDoc.setParentId(parentId); » » // set the content handler » courseDoc.setContentHandler( "resource/x-bb-samplecontent" ); » // set the course ID » courseDoc.setCourseId( courseId ); » // Set to Track the content or not » String strTracked = request.getParameter("isTrack"); » if (strTracked.equalsIgnoreCase("true")) { » courseDoc.setIsTracked(true); » } else { » courseDoc.setIsTracked(false); » }

31. Create_proc.jsp » // validate the new content idem » courseDoc.validate(); » // Persist the object » ContentDbPersister contentPersister = (ContentDbPersister) bbPm.getPersister( ContentDbPersister.TYPE ); » contentPersister.persist( courseDoc );

32. Modify and Modify_proc » Almost identical to create process. » See the sample Content Handler for details » Remove is optional clean up

33. Demonstration

34. We covered the most basic… » Let’s touch on more advanced topics: » Storing additional parameters » Relative Referencing of the content_id » Linking to external resources » Import/Export/Copy/Migration Issues

35. Storing additional parameters » What types of data do you want to store? » In what do you want to store it? » In JAVA property files » As XML? » As Serialized Java Objects? » In your own proprietary (and somewhat creative formats)

36. » Where do you store the parameters? » In the webapp’s config directory? » In the content’s directory » In the content itself (hidden) » Externally Storing additional parameters

37. Using the webapps config dir » // Get the Configuration Directory » File dir = PlugInUtil.getConfigDirectory(“bb","sample-contenthandler"); » // get the config file » File cfg = new File(dir, “custom.properties"); » // If it doesn't exist yet, create a blank one » if (!cfg.exists()) { » cfg.createNewFile(); » FileOutputStream f = null; » try { » f = new FileOutputStream(cfg); » } catch (FileNotFoundException e){ » out.println("Can't find the file"); » } » Properties p = new Properties(); » // Write them out to the conf file » p.setProperty(“name",“value"); » p.store(f,“My Configuration File"); » f.close(); » }

38. Using the content directory » FileSystemService fileSysService; » fileSysService = (FileSystemService)BbServiceManager. lookupService( FileSystemService.class ); » java.io.File fileContentDirectory = fileSysService.getContentDirectory(course, courseDocId); » Advantages » Content on file system in this directory is PORTABLE with import/export/copy/migration » Can be referenced with the @X@content.url@X@ syntax rather than hard coded

39. Storing Data in the Content » Why not use the content item itself and store your other data in the MAIN DATA blob? » Use comment blocks to mask your data » Advantages: complete portability, no external dependencies » Disadvantages: ALL Data in this field is rendered by the content engine in the user view.

40. Externally » You can simply insert a URL to your own content engine in the Blackboard content item. » Advantages: » Many to One relationship between content and raw data » Setup own system for management and deployment » Disadvantages: » Content is ignorant of copy/import/export/migration and all copies will still point to the hard coded URL

41. Summary » We’ve seen how to create a new content-handler from scratch » We’ve seen the structure of the webapp and walked through an example of one. » We talked about the various places, structures, and methods of storing content and the advantages and disadvantages of each.

42. © Blackboard, Inc. All rights reserved. Thank you!