---

Class ::xowiki::includelet::categories

::xowiki::includelet::categories create ... \
           [ -parameter_declaration (default "
          {-tree_name ""}
          {-tree_style:boolean 1}
          {-no_tree_name:boolean 0}
          {-count:boolean 0}
          {-summary:boolean 0}
          {-locale ""}
          {-open_page ""}
          {-order_items_by "title,asc"}
          {-style "mktree"}
          {-category_ids ""}
          {-parent /}
          {-except_category_ids ""}
          {-allow_edit false}
          {-ordered_composite}
        ") ] \
           [ -title (default "#xowiki.categories#") ]

List the specified category tree.

Documented Parameters:

tree_name

match pattern, if specified displays only the trees with matching names

no_tree_name

if specified, tree names are not displayed

open_page

name (e.g. en:iMacs) of the page to be opened initially

tree_style

boolean, default: true, render category tree in tree style and not in sections style

parent

page-ref, default: /, select entries from this directory

Defined in packages/xowiki/tcl/includelet-procs.tcl

Class Relations

• class: ::xowiki::IncludeletClass
• superclass: ::xowiki::Includelet

::xowiki::IncludeletClass create ::xowiki::includelet::categories \
     -superclass ::xowiki::Includelet

Methods (to be applied on instances)

• category_tree_edit_button (scripted)

  set allow_p [::xo::cc permission  -object_id $object_id  -privilege admin  -party_id [::xo::cc set untrusted_user_id]]
  if {$allow_edit && $allow_p} {
    set package ::${:package_id}
    if {[info exists tree_id]} {
      #
      # If a tree_id is given, edit directly the category tree ...
      #
      set href "[$package package_url]?edit-category-tree&object_id=$object_id&tree_id=$tree_id"
      return [${:__including_page} include  [list edit-item-button -link $href -title [_ xowiki.Edit_category] -target _blank]]
    } else {
      #
      # ... otherwise, manage categories (allow defining new category trees, map/unmap, etc.)
      #
      set href "[$package package_url]?manage-categories&object_id=$object_id"
      return [${:__including_page} include  [list edit-item-button -link $href -title [_ xowiki.Manage_categories] -target _blank]]
    }
  }
  return ""

• category_tree_missing (scripted)

  # todo i18n
  if {$name eq ""} {
    #set msg "No category tree found."
    # maybe it is better to stay quiet in case, no category name was provided
    set msg ""
  } else {
    set msg "No category tree with name '$name' found."
  }
  ::${:package_id} flush_page_fragment_cache -scope agg
  set html "<div class='errorMsg'>[ns_quotehtml $msg]</div>"
  if {$edit_html ne ""} {
    return "$html Manage Categories? $edit_html"
  }
  return $html

• include_head_entries (scripted)

  ::xowiki::Tree include_head_entries -renderer ${:style}

• initialize (scripted)

  :get_parameters
  if {!$tree_style} {
    set style sections
  }
  set :style $style

• parameter_declaration (setter)

• render (scripted)

  :get_parameters
  
  set content ""
  set current_folder [:get_current_folder $parent]
  set folder_id [$current_folder item_id]
  
  set open_item_id [expr {$open_page ne "" ?
                          [::xo::db::CrClass lookup -name $open_page -parent_id $folder_id] : 0}]
  
  lassign [::xowiki::Includelet locale_clause -revisions r -items ci $package_id $locale]  locale locale_clause
  
  set trees [::xowiki::Category get_mapped_trees -object_id $package_id -locale $locale  -names $tree_name  -output {tree_id tree_name}]
  
  #:msg "[llength $trees] == 0 && tree_name '$tree_name'"
  if {[llength $trees] == 0 && $tree_name ne ""} {
    #
    # We have nothing left from mapped trees, maybe the tree_names
    # are not mapped; try to get these
    #
    foreach name $tree_name {
      #set tree_id [lindex [category_tree::get_id $tree_name $locale] 0]
      set tree_id [lindex [category_tree::get_id $tree_name] 0]
      if {$tree_id ne ""} {
        lappend trees [list $tree_id $name]
      }
    }
  }
  
  set edit_html [:category_tree_edit_button -object_id $package_id -allow_edit $allow_edit]
  if {[llength $trees] == 0} {
    return [:category_tree_missing -name $tree_name -edit_html $edit_html]
  }
  
  if {![info exists :id]} {
    set :id [::xowiki::Includelet html_id [self]]
  }
  
  foreach tree $trees {
    lassign $tree tree_id my_tree_name ...
  
    set edit_html [:category_tree_edit_button -object_id $package_id  -allow_edit $allow_edit -tree_id $tree_id]
    #append content "<div style='float:right;'>$edit_html</div>\n"
  
    if {!$no_tree_name} {
      append content "<h3>[ns_quotehtml $my_tree_name] $edit_html</h3>"
    } elseif {$edit_html ne ""} {
      append content "$edit_html<br>"
    }
    set categories [list]
    set pos 0
    set cattree(0) [::xowiki::Tree new -volatile -orderby pos  -id [:id]-$my_tree_name -name $my_tree_name]
  
    set category_infos [::xowiki::Category get_category_infos  -locale $locale -tree_id $tree_id]
    foreach category_info $category_infos {
      lassign $category_info cid category_label deprecated_p level
      set c [::xowiki::TreeNode new -orderby pos   -level $level -label $category_label -pos [incr pos]]
      set cattree($level) $c
      set plevel [expr {$level -1}]
      $cattree($plevel) add $c
      set category($cid) $c
      lappend categories $cid
    }
  
    if {[llength $categories] == 0} {
      return $content
    }
  
    if {[info exists ordered_composite]} {
      set items [list]
      foreach c [$ordered_composite children] {
        lappend items [$c item_id]
      }
  
      # If we have no item, provide a dummy one to avoid sql error
      # later
      if {[llength $items]<1} {
        set items -4711
      }
  
      if {$count} {
        set sql "category_object_map c
            where c.object_id in ([ns_dbquotelist $items]) "
      } else {
        # TODO: the non-count-part for the ordered_composite is not
        # tested yet. Although "ordered composite" can be used
        # only programmatically for now, the code below should be
        # tested. It would be as well possible to obtain titles and
        # names etc. from the ordered composite, resulting in a
        # faster SQL like above.
        set sql "category_object_map c, cr_items ci, cr_revisions r
            where c.object_id in ([ns_dbquotelist $items])
            and c.object_id = ci.item_id
            and r.revision_id = ci.live_revision
            and ci.publish_status <> 'production'
         "
      }
    } else {
      set sql "category_object_map c, cr_items ci, cr_revisions r, xowiki_page p  where c.object_id = ci.item_id and ci.parent_id = :folder_id  and ci.content_type not in ('::xowiki::PageTemplate')  and c.category_id in ([ns_dbquotelist $categories])  and r.revision_id = ci.live_revision  and p.page_id = r.revision_id  and ci.publish_status <> 'production'"
    }
  
    if {[llength $except_category_ids] > 0} {
      append sql  " and not exists (select * from category_object_map c2  where ci.item_id = c2.object_id  and c2.category_id in ([ns_dbquotelist $except_category_ids]))"
    }
    #ns_log notice "--c category_ids=$category_ids"
    if {$category_ids ne ""} {
      foreach cid [split $category_ids ,] {
        set or_ids [split $cid |]
        foreach or_id $or_ids {
          if {![nsf::is integer $or_id]} {
            ad_return_complaint 1 "invalid category_id"
            ad_script_abort
          }
        }
        append sql " and exists (select * from category_object_map  where object_id = ci.item_id and c.category_id in ([ns_dbquotelist $or_ids]))"
      }
    }
    append sql $locale_clause
  
    if {$count} {
      ::xo::dc foreach get_counts  "select count(*) as nr,category_id from $sql group by category_id" {
            $category($category_id) set count $nr
            set s [expr {$summary ? "&summary=$summary" : ""}]
            $category($category_id) href [ad_conn url]?category_id=$category_id$s
            $category($category_id) open_tree
          }
      append content [$cattree(0) render -style ${:style}]
    } else {
      lassign [split $order_items_by ,] orderby direction     ;# e.g. "title,asc"
      set increasing [expr {$direction ne "desc"}]
      set order_column ", p.page_order"
    #ns_log notice "--c category_ids=$category_ids\n$sql"
  
      ::xo::dc foreach get_pages  "select ci.item_id, ci.name, ci.parent_id, r.title, category_id $order_column from $sql" {
            if {$title eq ""} {set title $name}
            set itemobj [Object new]
            $itemobj mset [list  name $name title $title prefix "" suffix ""  page_order $page_order  href [::$package_id pretty_link -parent_id $parent_id $name]  ]
            $cattree(0) add_item  -category $category($category_id)  -itemobj $itemobj  -orderby $orderby  -increasing $increasing  -open_item [expr {$item_id == $open_item_id}]
          }
      append content [$cattree(0) render -style ${:style}]
    }
  }
  return $content

• title (setter)

---