Forum .LRN Q&A: how to add portlets?

A variable value on the format <span>#</span>package_key.message_key# is a reference to a multilingual message in the message catalog. You can view all messages under /acs-lang/admin or look at the xml file at packages/package_key/catalog/package_key.locale.encoding.xml. When the variable value is displayed in the UI the proc lang::util::localize is invoked to convert the <span>#</span>package_key.message_key# value to a text in the language of the request (depending on the users preference).

To add a new portlet to dotlrn you need to create two new packages - a portlet package and an applet package. Take the forums portlet as example and study the following files:

- dotlrn-forums/tcl/dotlrn-forums-procs.tcl
As you can see from this file the forums applet takes care of mounting a forums and attachments package under the (dotlrn) class package. The applet also responds to events such as adding/removing a user from the community and adding/removing portlets. The applet is the contract between your application and dotlrn.

- forums-portlet/www/forums-portlet.tcl
- forums-portlet/www/forums-portlet.adp
These are the templates that actually display the forums in a portlet. Notice how these templates get passed the package_id of the corresponding forums package (see dotlrn_community::get_applet_package_id).

Any applets in the system will be picked up by dotlrn after server creation (see dotlrn/tcl/dotlrn-init.tcl, it does this by selecting all implementations of the dotlrn_applet service contract). The class admin is then able to visit the Manage applets page from the admin page of his community to add your applet. This should make the portlet available on the Customize Layout page where portlets are added and moved around.

I put up the dotLRN technical documentation here:

http://dotlrn.collaboraid.net/dotlrn/doc/

and you should probably read it.

If you gain further insights into this issue please post them here.

Thanks!

This is how I think it works. Correct me if I'm wrong.

If you start from a community page for example http://dotlrn.collaboraid.net/dotlrn/clubs/tennis-club/one-community?page_num=0 ,
you'll see that it serves the file one-community (in dotlrn/www).
The .adp file is essentially no more than @rendered_page@ with <master>.
The .tcl file creates the rendered_page variable by calling dotlrn::render_page

proc dotlrn::render_page calls portal::render with the correct portal_id and page number
portal::render will create an <include> (with master) for the one-community file. This is the template for the portal.

The included template will be one of the files in new-portal/www/layouts (for example simple2). All information is passed into the <include>, for example ' element_list'  that contains all element_id's.
The .tcl file will call portal::layout_elements $element_list to sort out the regions (columns) where the elements (portlets) need to go.
The .adp file will do an <include> for each element in element_list.

The included files are usually render_element (in new-portal/www/render-styles/individual), which is called for every element. (for admin pages it uses render-styles/all-in-one). The source for the included element (element_src) was defined in the portal_render proc.
The .tcl file of render_element will set the 'element_data' by calling portal::evaluate_element with the right portal_id, element_id and theme_id that it got from 'layouts/simple2.adp'
If no errors are thrown while retrieving the data then element_data is set to 'element' (the array that contains all element information)
The .adp file returns the @element.content@ (in .tcl file element(content)) with a <master> and <properties>. The latter create the 'theme' of the portlet with the config elements.

So portal::evaluate_element (portal::evaluate_element_raw for admin pages) creates config/cf to return to your question.
In this proc the theme and element data are retrieved from the database (
        db_1row element_select {} -column_array element
). The information is stored in an array 'element'
Then it calls portal::element_params_not_cached $element_id to store all config parameters in array 'config'
If an element has no config variables defined, some defaults are set up. For example: set config(shaded_p) "f"

Finally element(content) is added to the array by calling (
set element(content)  [datasource_call  -datasource_name $element(ds_name)  $element(datasource_id)  "Show"  [list [array get config]]
)
In the end config array is added to element array

The service contract portal_datasource of the portlet is used to retrieve the correct page as defined by the show procedure of the portlet_package. It passes [list [array get config]] as the variable cf that is needed by the ::show proc  For example forums_portlet::show cf which is a wrapper for:
portal::show_proc_helper  -package_key [my_package_key]  -config_list $cf  -template_src "forums-portlet"

This proc finishes the job by returning the output with all necessary tricks. (like setting cflist to $config_list in an upvar procedure)

Hope this helps.