The Categories service provides a mechanism to associate one or more category trees that are relevant to your application. One example of such tree is a tree of geographical locations. Continents are on the top of such tree, each continent containing countries etc. Another tree might contain market segments etc. Before users of your application can take advantage of the Categories service there needs to be a way for administrators of your application to choose which category trees are applicable for the application.

The way to achieve this is to provide a link to the Category Management pages. Add the following snippet to your /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl file:

                  set category_map_url [export_vars -base "[site_node::get_package_url -package_key categories]cadmin/one-object" { { object_id $package_id } }]
          

and the following snippet to your /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp file:

                  <a href="@category_map_url@">#­categories.Site_wide_Categories#</a>
          

The link created by the above code (category_map_url) will take the admin to the generic admin UI where he can pick category trees that make sense for this application. The same UI also includes facilities to build and edit category trees. Notice that the only parameter in this example is package_id so that category trees will be associated with the object identified by this package_id. The categorization service is actually more general than that: instead of package_id you could use an ID of some other object that serves as a "container" in your application. For example, if your discussion forums application supports multiple forums you would use forum_id to associate category trees with just that one forum rather than the entire application instance.

Once the category trees have been selected users need a way to categorize items. The easiest way to do this is by adding the category widget type of the form builder to note-edit.tcl. To achieve this we'll need to use the -extend switch to the ad_form command. Here's the "meat" of the note-edit.tcl page:

                        # extend the form to support categories
                        set package_id [ad_conn package_id]
                            
                        category::ad_form::add_widgets -form_name note -container_object_id $package_id -categorized_object_id [expr {[info exists item_id] ? $item_id : ""}]

                        ad_form -extend -name note -on_submit {
                                set category_ids [category::ad_form::get_categories -container_object_id $package_id]
                        } -new_data {
                                ....
                                        category::map_object -remove_old -object_id $item_id $category_ids
                        } -edit_data {
                        ....
                                category::map_object -remove_old -object_id $item_id $category_ids
                        } -after_submit {
                                        ad_returnredirect "."
                                        ad_script_abort
                        }
                        

While the category::ad_form::add_widgets proc is taking care to extend your form with associated categories you need to ensure that your items are mapped to the corresponding category object yourself.

note-edit.tcl requires a note_id to determine which record should be deleted. It also looks for a confirmation variable, which should initially be absent. If it is absent, we create a form to allow the user to confirm the deletion. Note that in entry-edit.tcl we used ad_form to access the Form Template commands; here, we call them directly because we don't need the extra features of ad_form. The form calls itself, but with hidden variables carrying both note_id and confirm_p. If confirm_p is present, we delete the record, set redirection back to the index, and abort script execution.

The database commands:

[$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.xql

<?xml version="1.0"?>
<queryset>
  <fullquery name="do_delete">
    <querytext>
      select samplenote__delete(:note_id)
    </querytext>
  </fullquery>
  <fullquery name="get_name">
    <querytext>
      select samplenote__name(:note_id)
    </querytext>
  </fullquery>
</queryset>

And the adp page:

[$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.adp

<master>
<property name="title">@title@</property>
<property name="context">{@title@}</property>
<h2>@title@</h2>
<formtemplate id="note-del-confirm"></formtemplate>
</form>

The ADP is very simple. The formtemplate tag outputs the HTML form generated by the ad_form command with the matching name. Test it by adding the new files in the APM and then deleting a few samplenotes.

We will now make categories optional on package instance level and also add a configuration page to allow the package admin to enable/disable categories for his package.

Go to the APM and create a number parameter with the name "EnableCategoriesP" and the default value "0".

Add the following lines to your index.tcl:

          set return_url [ns_conn url]
          set use_categories_p [parameter::get -parameter "EnableCategoriesP"]
          

Change your to this:

                        <a href=configure?<%=[export_vars -url {return_url}]%>>Configure</a>
                        <if @use_categories_p@>
                        <a href="@category_map_url@">#­categories.Site_wide_Categories#</a>
                        </if>
          

Now create a configure page

                ad_page_contract {
                        This page allows an admin to change the categories usage mode.
                        } {
                        {return_url ""}
                        }

                        set title "Configure category mode"
                        set context [list $title]
                        set use_categories_p [parameter::get -parameter "EnableCategoriesP"]

                        ad_form -name categories_mode -form {
                        {enabled_p:text(radio)
                                {label "Enable Categories"}
                                {options {{Yes 1} {No 0}}}
                                {value $use_categories_p}
                        }
                        {return_url:text(hidden) {value $return_url}}
                        {submit:text(submit) {label "Set Mode"}}
                        } -on_submit {
                        parameter::set_value  -parameter "EnableCategoriesP" -value $enabled_p
                        if {$return_url ne ""} {
                                ns_returnredirect $return_url
                        }
                        }
           

and add this to its corresponding ADP page

                <master>
                        <property name="title">@title@</property>
                        <property name="context">@context@</property>

                        <formtemplate id="categories_mode"></formtemplate>
              

Reference this page from your admin page

                #TCL:
                set return_url [ad_conn url]

                #ADP:
                <a href=configure?<%=[export_vars -url {return_url}]%>>Configure</a>
                

Change the note-edit.tcl:

                # Use Categories?
                set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0]
                if { $use_categories_p == 1 } {
                        # YOUR NEW FORM DEFINITION
                } else {
                # YOUR OLD FORM DEFINITION
                }
        

You can filter your notes using categories. The below example does not support multiple filters and displays a category in a flat format.

The first step is to define the optional parameter category_id for index.tcl:

                ad_page_contract {
                YOUR TEXT
                } {
                        YOURPARAMS
                {category_id:integer,optional {}}
                }
          

Now you have to check whether categories are enabled or not. If this is the case and a category id is passed you need to extend your sql select query to support filtering. One way would be to extend the mfp::note::get proc to support two more switches -where_clause and -from_clause.

                set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0]

                if { $use_categories_p == 1 && $category_id ne "" } {

                        set from_clause "category_object_map com"
                        set_where_clause "com.object_id = qa.entry_id and com.category_id = :category_id"
                        
                        ...
                                                                
                mfp::note::get \
                -item_id $item_id \
                -array note_array \
                -where_clause $where_clause \
                -from_clause $from_clause
                
                ...
                } else {
                # OLD STUFF
                }
          

Also you need to make sure that the user can see the corresponding categories. Add the following snippet to the end of your index page:

          # Site-Wide Categories
                if { $use_categories_p == 1} {
                set package_url [ad_conn package_url]
                if { $category_id ne "" } {
                        set category_name [category::get_name $category_id]
                        if { $category_name eq "" } {
                        ad_return_exception_page 404 "No such category" "Site-wide \
                                Category with ID $category_id doesn't exist"
                        return
                        }
                        # Show Category in context bar
                        append context_base_url /cat/$category_id
                        lappend context [list $context_base_url $category_name]
                        set type "all"
                }

                # Cut the URL off the last item in the context bar
                if { [llength $context] > 0 } {
                        set context [lreplace $context end end [lindex $context end end]]
                }

                db_multirow -unclobber -extend { category_name tree_name } categories categories {
                        select c.category_id as category_id, c.tree_id
                        from   categories c, category_tree_map ctm
                        where  ctm.tree_id = c.tree_id
                        and    ctm.object_id = :package_id
                } {
                        set category_name [category::get_name $category_id]
                        set tree_name [category_tree::get_name $tree_id]
                }
                }
                

and to the corresponding index ADP page:

                <if @use_categories_p@>
                        <multiple name="categories">
                        <h2>@categories.tree_name@
                        <group column="tree_id">
                        <a href="@package_url@cat/@categories.category_id@?@YOURPARAMS@&category_id=@categories.category_id@">@categories.category_name@
                        </group>
                </multiple>
                <a href="@package_url@view?@YOURPARAMS@">All Items</if>
          

Finally you need an index.vuh in your www folder to rewrite the URLs correctly, the section called “Using .vuh files for pretty URLs”:

          set url /[ad_conn extra_url]

          if {[regexp {^/+cat/+([^/]+)/*} $url ignore_whole category_id]} {
              rp_form_put category_id $category_id
          }
          rp_internal_redirect "/packages/YOURPACKAGE/www/index"          
          

Now when ever the user select a category only notes that belong to this category are displayed.