1. Copyright 2005 Academic Computing - University of South Florida Tips & Tricks in Building Blocks Development Blackboard Developers Conference July 19, 2005 Murali Nagulakonda http://www.acomp.usf.edu/~nagulako/presentations/

2. Copyright 2005 Academic Computing - University of South Florida1 Outline Connecting to the Database Storing Data in Course and User Registries Storing Data Outside the Database User Interfaces Tag Context and ContextManager Gradebook APIs Miscellaneous

3. Copyright 2005 Academic Computing - University of South Florida Connecting to the Database

4. Copyright 2005 Academic Computing - University of South Florida3 Connecting to the Database… Use Blackboard’s API’s to connect to the DB. (NON- PUBLIC APIs) Use Blackboard’s connection pool. Already established connections to the DB. Doesn’t require setup/teardown of connections. Getting a connection from the pool is faster Set the bb-manifest.xml permissions. import blackboard.db.*

5. Copyright 2005 Academic Computing - University of South Florida4 Connecting to the Database… Setting the Bb-manifest permission:

6. Copyright 2005 Academic Computing - University of South Florida5 Connecting to the Database… ConnectionManager conman; int i=0; private Connection bbConnectDatabase() throws ConnectionNotAvailableException, InterruptedException { BbDatabase bbDb = DbUtil.safeGetBbDatabase(); conman = bbDb.getConnectionManager(); while(conn == null && i<10){ try { conn = conman.getConnection(); } catch(ConnectionNotAvailableException cnae){ Thread.sleep(1000); ++i; } return conn; }

7. Copyright 2005 Academic Computing - University of South Florida6 Releasing the connection… if(conman != null) conman.releaseConnection(conn);

8. Copyright 2005 Academic Computing - University of South Florida Registries

9. Copyright 2005 Academic Computing - University of South Florida8 Registries Course & User Registries Excellent tables strictly for Key-Value pair data Makes building blocks portable Tables already exist Don’t have to worry about creating them Example of Key “usf.spa.lastviewed" Caveat: These are Non-public APIs. BB can change the APIs & tables anytime.

10. Copyright 2005 Academic Computing - University of South Florida9 Registries SQL> desc course_registry; Name Type --------------------------------------- SOS_ID_PK2NUMBER(38) PK1 NUMBER(38) CRSMAIN_PK1 NUMBER(38) CRSMAIN_SOS_ID_PK2 NUMBER(38) DTMODIFIEDDATE ROW_STATUSNUMBER(1) REGISTRY_KEY VARCHAR2(50) REGISTRY_VALUE VARCHAR2(255) DTCREATED DATE

11. Copyright 2005 Academic Computing - University of South Florida10 Registries SQL> desc user_registry; Name Type --------------------------------------- SOS_ID_PK2 NUMBER(38) USERS_SOS_ID_PK2NUMBER(38) PK1 NUMBER(38) ROW_STATUSNUMBER(1) REGISTRY_KEY VARCHAR2(50) REGISTRY_VALUE VARCHAR2(255) DTCREATEDDATE USERS_PK1 NUMBER(38) DTMODIFIEDDATE

12. Copyright 2005 Academic Computing - University of South Florida11 Registries APIs blackboard.persist.registry UserRegistryEntryDbLoader UserRegistryEntryDbPersister CourseRegistryEntryDbLoader CourseRegistryEntryDbPersister blackboard.data.registry CourseRegistryEntry UserRegistryEntry

13. Copyright 2005 Academic Computing - University of South Florida12 Registries Persisting Data into a Course Registry CourseRegistryEntryDbPersister crePersister = CourseRegistryEntryDbPersister.Default.getInstance(); String value = lineitem_id + ":" + values; String key = “usf.spa.lastviewed" + ":" + user_id; try { crePersister.deleteByKeyAndCourseId(key,cId); // cID – Course Id of type Id } catch(KeyNotFoundException kfe) {} catch(PersistenceException pe) {} CourseRegistryEntry cre = new CourseRegistryEntry(key,value); cre.setCourseId(cId); try { crePersister.persist(cre); } catch(PersistenceException pe) {}

14. Copyright 2005 Academic Computing - University of South Florida13 Course Registry Getting Data from a Course Registry CourseRegistryEntryDbLoader creLoader = CourseRegistryEntryDbLoader.Default.getInstance(); Registry registry = creLoader.loadRegistryByCourseId(cId); String key = “usf.spa.lastviewed" + ":" + user_id; String value = registry.getValue(key); Similar for User Registry

15. Copyright 2005 Academic Computing - University of South Florida Storing Data Outside the Database

16. Copyright 2005 Academic Computing - University of South Florida15 Storing Data outside the Database Data under the /webapps directory gets wiped out during an update / re-install Use Blackboard APIs to create the Config Directory Data not removed after uninstall or update of module

17. Copyright 2005 Academic Computing - University of South Florida16 Storing Data in the Config Directory

18. Copyright 2005 Academic Computing - University of South Florida17 File dir = null; java.util.Enumeration names = request.getParameterNames(); try { dir = blackboard.platform.plugin.PlugInUtil.getConfigDirectory("usf", “member-participation"); } catch(Exception e) { out.println("Exception = " + e); } File cfg = new File(dir,“custom.properties"); FileOutputStream f = null; if(!cfg.exists()) cfg.createNewFile(); try { f = new FileOutputStream(cfg); } catch(FileNotFoundException e) { System.out.println("cant find properties file"); } Properties p = new Properties(); for(; names.hasMoreElements();) { String name = (String) names.nextElement(); String value = request.getParameter(name); p.setProperty(name,value); } p.store(f,“Member-Participation Configuration File"); f.close();

19. Copyright 2005 Academic Computing - University of South Florida18 Storing Data outside the Database…

20. Copyright 2005 Academic Computing - University of South Florida19 Retrieving Data from Config Directory try { dir = blackboard.platform.plugin.PlugInUtil.getConfigDirectory("usf","member- participation"); } catch(Exception e) { out.println("Exception = " + e); } File cfg = new File(dir,“custom.properties"); FileInputStream fp = null; if(cfg.exists()) { fp = new FileInputStream(cfg); Properties p = new Properties(); p.load(fp); fp.close(); sname = p.getProperty("sname"); dbname = p.getProperty("dbname"); uname = p.getProperty("uname"); pwd = p.getProperty("pwd"); }

21. Copyright 2005 Academic Computing - University of South Florida

22. Copyright 2005 Academic Computing - University of South Florida21 tag Extremely useful in displaying lists of data Associate a comparator to a column ( listElement ) to enable sorting comparator

23. Copyright 2005 Academic Computing - University of South Florida22 BbList llist = uLoader.loadByCourseId(cId); GenericFieldComparator compUserName = new GenericFieldComparator(BaseComparator.ASCENDING, "getUserName", User.class ); Comparator " collectionLabel="Course Last Access" objectId=“user" className=“blackboard.data.User" resultsPerPage="-1"> "> Data to be displayed in the row userThe object Id to refer to the data within the “llist” collection throughout the rest of the list tag labelTitle of the column comparatorA non required value which allows the tag to sort the data

24. Copyright 2005 Academic Computing - University of South Florida23 " collectionLabel="Course Last Access" objectId=“user" className=“blackboard.data.User" resultsPerPage="-1"> resultsPerPage=“-1”: Blackboard doesn’t save state between pages. Use the “- 1” value to tell BB not to page. Default results per page is 20 Currently Blackboard’s list tag doesn’t save state between pages “-1” will show all data in one page.

25. Copyright 2005 Academic Computing - University of South Florida

26. Copyright 2005 Academic Computing - University of South Florida25 Creates the framework for the breadcrumb navigation. breadcrumbBar attributes handle: the database field used to uniquely identify the root nav item for the breadcrumb bar You can get a list of all “handles” from the database table “Navigation_Item” environment : Acceptable values are PORTAL, COURSE, CTRL_PANEL, SYS_ADMIN If you’re within a course, the page must have the “course_id” (_3320_1) accessible to it to generate the breadcrumbBar.

27. Copyright 2005 Academic Computing - University of South Florida26 Student Performance Assistant Requires the Requires For the context to properly generate you should have the “course_id” when coming from the control panel and pass it on to the subsequent pages.

28. Copyright 2005 Academic Computing - University of South Florida27 Student Performance Student View handle values If it is a course plugin Eg: From the Tools or Communication Area The handle is “vendor_id-plugin_handle-nav-1” Eg: usf-student-performance-nav-1 The numbers continue upwards. Must have course_id. No “handle” if it is a portal module.

29. Copyright 2005 Academic Computing - University of South Florida28 … From the portal No handle or way to generate the breadcrumb using the Public APIs. To generate the breadcrumb, import: blackboard.persist.navigation blackboard.data.navigation

30. Copyright 2005 Academic Computing - University of South Florida29 <bbUI:breadcrumbBar String tab_id = referer.substring(referer.indexOf("_"),referer.lastIndexOf("_1")+2); Id tabId = bbPm.generateId (Tab.DATA_TYPE,tab_id); //bbPm – Blackboard Persistence Manager TabDbLoader tabLoader = TabDbLoader.Default.getInstance(); Tab t = tabLoader.loadById(tabId); label = t.getLabel(); TabControl tc = TabControl.createInstance(t); if(request.isSecure()) { strTab = "https://" + request.getServerName() + tc.getFullUrl(request.getServerName()); } else { strTab = "http://" + request.getServerName() + tc.getFullUrl(request.getServerName()); } JSP PAGE "> Select Participation Parameters Referer from Header= http://redfrog.acomp.usf.edu/webapps/portal/tab/_109_1/index.jsp/_109_1

31. Copyright 2005 Academic Computing - University of South Florida Context & Context Manager

32. Copyright 2005 Academic Computing - University of South Florida31 Context & ContextManager Context Combination of Session Data & Client Request tag in jsp pages Set the context before calling the API methods Get User: ctx.getUser(); Get Course: ctx.getCourse(); Get CourseMembership: ctx.getCourseMembership(); Get UserId: ctx.getUserId();

33. Copyright 2005 Academic Computing - University of South Florida32 ContextManager If used within a Java class import blackboard.platform.context ctxMgr = (ContextManager)BbServiceManager.lookupService( ContextManager.class ); Context ctx = ctxMgr.setContext(request); //… work with the APIs if( ctxMgr != null ) ctxMgr.releaseContext();

34. Copyright 2005 Academic Computing - University of South Florida Gradebook APIs

35. Copyright 2005 Academic Computing - University of South Florida34 Gradebook APIs Lineitem Score CourseMembership User

36. Copyright 2005 Academic Computing - University of South Florida35 Gradebook APIs Connection conn = getConnection(); // Use the code sample shown previously to get a connection from the connection pool. LineitemDbLoader lLoader = (LineitemDbLoader) bbPm.getLoader(LineitemDbLoader.TYPE); Lineitem li = lLoader.loadById(lId); // lId is LineitemID BbList sList = li.getScores(); BbList.Iterator sIterator = sList.getFilteringIterator(); CourseMembershipDbLoader cmLoader = CourseMembershipDbLoader.Default.getInstance(); Id cmId ; CourseMembership cm ; User user; String username; while(sIterator.hasNext()) { Score score = (Score) sIterator.next(); cmId = score.getCourseMembershipId(); cm = cmLoader.loadById(cmId,conn,true); // true tells the loader to load all the associated User Data user = cm.getUser(); username = user.getUserName(); }

37. Copyright 2005 Academic Computing - University of South Florida36 Miscellaneous… All the “Non-Public” APIs shown here and not in the documentation can change when blackboard updates its software. You can use Netbeans to look at the non-public APIs. For building blocks APIs, load the bb-platform.jar. Don’t have to re-install a building block everytime you make changes to the class files. An “Active  Inactive  Active” will get Tomcat to reload the file. Exceptions to this rule are for the bb-manifest.xml file and the web.xml file

38. Copyright 2005 Academic Computing - University of South Florida37 Miscellaneous Building blocks may have multiple entry points E.g. Portal pages, Control Panel, Tools… Before deploying, make sure you have good logging information which goes to the tomcat logs

39. Copyright 2005 Academic Computing - University of South Florida38 Resources Bbug.ca Bb-opensource.org mailing list Building Blocks APIs behind.blackboard.com

40. Copyright 2005 Academic Computing - University of South Florida39 Questions or Comments? Murali Nagulakonda University of South Florida 4202 E. Fowler Ave., LIB 618 Tampa, FL 33620 nagulako@usf.edu