Home
About • Download • Documentation • Wiki • Forums • Contribute • Support
The Toolkit for Online Communities
15262 Community Members, 0 members online, 1872 visitors today 		Log In Register

A Notes Portlet for dotLRN

OpenACS Home : Wiki : A Notes Portlet for dotLRN
Pages that link to this page:

A Notes Portlet for dotLRN

Version 1.0

Goals

Assumptions

Introduction

In this tutorial you will learn to integrate an application package into dotLRN as a portlet. For the purposes of this exercise we will use the openacs notes package. The goal is to be able to mount an instance of the notes package in a community or class, so that students can keep notes for their courses.

By the end of this problem set you should be able to display a notes portlet in dotLRN as shown in the following screenshot:

The screen shot shows that there are two communities, one called Developer, the other called Standards. The Notes portlet (directly below the Groups portlet) conveys the notes created by the user in each of the communities that the user belongs to.

Step 1: Create the dotLRN Notes Applet

Use the news applet (dotlrn-news) as the basis for the notes applet. The dotlrn-notes package is required to register the notes application as an applet in dotLRN.

Go through the dotlrn-notes package (sql/tcl/www/catalog sub-directories) and do a search for "news" and replace all with "notes".

Congratulations! You've just created the dotLRN notes applet.

Step 2: Create the dotLRN Notes Portlet

Use the notes portlet (news-portlet) as the basis for the notes portlet.

Go through the notes-portlet package (sql/tcl/www/catalog sub-directories) and do a search for "news" and replace all with "notes".

Take note of the files in notes-portlet/www. There is no need for the "summary" files, so remove summary.adp and summary.tcl

The files that are worth looking through are notes-portlet* and notes-admin-portlet*. The notes-portlet* files (.tcl, .adp, -postgresql.xql and -oracle.xql) contain code for displaying the notes applet within the dotLRN portal. The notes-admin-portlet* contain code for displaying the administraition controls for the corresponding applet on the community admin page.

In general if a package contains an admin directory, then you would want to link the package-admin-portlet* files to the index page in your packages admin directory. Notes doesn't contain an admin directory, and there is no need for admin controls with this package, so we we'll put the bare minimum in the files to keep the portal system satisfied.

 ad_page_contract {
    The display logic for the notes admin portlet
 } -properties {

 }

 ad_return_template
 <ul><li>N/A</li></ul>

For the time being you can copy the notes index* files into the corresponding notes-portlet* files.

Step 3: Test the Notes Portlet

Test the Notes portlet by first installing the package. When you install the "dotLRN Notes Portlet" from the package installer in dotLRN, make sure that all package dependencies are met. You should only need to select the "dotLRN Notes Portlet", and the applet and notes package should be added automatically by the installer. If not, then you will need to visit the .info files in the notes portlet and applet packages to modify the version numbers and dependencies.

Once the packages are installed, you will need to create two communities in dotLRN. Then add the notes applet to both communities.

You should be able to view the notes interface within a portlet in each community that you added the notes applet to. However none of the links will work, so you won't be able to add a note from the notes portlet. You will need to browse the site map to find the Notes instance to add notes. Go back to the portlet to make sure that you can view the notes that were just added.

Now go to the other notes instance in the other community, and add a few notes. Go back to the community portal to view the recently added notes.

If you were observant, you might have noticed that the notes that were added in the first community notes instance can also be viewed in the second community notes instance. You may be thinking, "How is this possible if they are mounted as two different instances? Is this a bug?". Well actually both instances refer to the same notes instance. Therefore adding notes in the first community will effectively be the same as adding notes to the application in the second community. The reason for this is that the notes package has been enabled as a singleton application by default. The singleton pattern means only one instance of that application can exist.

The singleton pattern is useful for services, however it doesn't have a place in the dotLRN portlet system, especially if we want each community to have its own notes instance. Therefore you will need to edit the notes.info file, and set "singleton_p" to "f" for false.

You will now need to drop your database, reinstall dotLRN, and your "dotLRN Notes Portlet". You will not need to do this if you read these instructions before attempting this exercise. If you blindly followed these instructions, then at least you now know what a singleton enabled application does!

Step 4: The Notes Portlet Interface

Once you have re-installed the dotLRN Notes Portlet and mounted the application in at least two communities, add a number of notes to each instance to help with debugging purposes.

Now that we have some notes related data in the database, we can now look at displaying context specific notes in a portlet. When we talk about "context specific", we are referring to notes data that is specific to an application instance. In this case notes that belong to a specific community or class.

# You should now be looking at the notes-portlet-postgresql.xql file, to work out a query that will return context specific notes data in a multirow datatype, which can then be passed to the presentation layer.

To get started, you should be able to work on the "notes" query that was copied over from the index-postgresql.xql file in the notes package.

Some hints to get you on your way:

Your notes-portlet.tcl file should look like the following:

 ad_page_contract {
    The display logic for the notes admin portlet
 } -properties {
    notes:multirow
    create_p:onevalue
 }

 array set config $cf

 set shaded_p $config(shaded_p)
 set list_of_package_ids $config(package_id)

 set one_instance_p [ad_decode [llength $list_of_package_ids] 1 1 0]

 set user_id [ad_conn user_id]

 db_multirow notes notes {}
 ad_return_template

Now work on your notes-portlet.adp file to work on presenting your notes as shown in the screen shot above. You should look at the survey-portlet package for inspiration.

Step 5: Test Your dotLRN Notes Portlet

At this stage you should have a reasonably complete notes portlet. You should spend this time testing your portlet. Create a number of users, so that you can add notes as each of the users. You'll need to do this to test your permissions, to make sure users can't view other users' notes.

If you run into problems, then look at other dotLRN portlet packages, such as the survey or news portlets.

Help
This website is maintained by the OpenACS Community. Any problems, email webmaster or Submit a bug report.