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

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.