Forum OpenACS Q&A: Xowiki Categories Includelet Rendering Connundrum

I am trying to understand the rendering of the categories includelet in xowiki so that I can write a new TreeRenderer to support yuimenubar from existing markup, but am having trouble finding my way around.

My includelet declaration is as follows:

{{categories -decoration plain -style samplemenu -order_items_by page_order,asc}}

My categories includelet is rendered like this (abridged):

<!-- Menu Start -->
  <div  class='categories'>
    <h3>Contents </h3>
      <ul class='menu' id='xotcl::___R-Contents'>
        <li class='menu-closed'><span >  </span>
          <div class='submenu'>
            <ul >
              <li class='menu-closed'><span > SubMenu</span>
                <div class='submenu'>
                  <ul >
                    <li class='liItem'><a href='/item1'>Item 1</a></li>
                    <li class='liItem'><a href='/item2'>Item 2</a></li>
<!-- Menu End -->

I thought I had found the piece of code that actually renders this but am becoming very frustrated by my lack of success!

I have tried adding edifying flags such as "BOO!" and "GOTCHA!" to the code in the following locations with no success whatsoever:

-  categories instproc render

It seems that even when I hard-code the return value, the result does not appear in my page source.  I can only conclude that the categories includelet is not rendered by its own render method.

-  TreeRenderer create TreeRenderer=samplemenu

I have tried editing the css class applied in 'TreeRenderer=samplemenu proc render {tree}' but this change is not reflected in the displayed page source after page refresh.  I have confirmed several times that the file is being watched and have browsed the modified code in the xotcl code browser.

-  menu-procs.tcl

I have studied this file for any evidence of procs that might be involved, but this file seems to contain procs that support creating menus using the YUI javascript API rather than from existing markup as I want to do.

I would also like to find the piece of code that wraps the categories content in:
<div  class='categories'><h3>Contents </h3>
because try as I might I cannot seem to find it.

I realise that this may come down to me just being really really dumb, but I have to ask because I'm getting nowhere fast!


Posted by Richard Hamilton on
Replying to my own posts again - second sign of madness!

From earlier post, Gustaf replied:

"Anyhow, it is not likely that the mktree renderer is a good choice for rendering menus. Furthermore, "Category instproc render_category ... " is gone since early this year and has been replaced by some more generic tree renderer classes (in tree-procs.tcl) which are used for various purposes in xowiki (not only for categories). The right approach seems to be write your own tree renderer and pass the tree-renderer via "-style" to the categories includelet. This way, you can use arbitrary CSS classes and you can freely add / remove divs without breaking anything else."

( )

So I am at least poking around in the correct code when playing with the TreeRenderer, (although I am not sure if 'categories instproc render' is also deprecated).

What I still have not identified is the reason why my exploratory changes, including some intended to sabotage the thing altogether(!), make no difference. Is the page content caching working against me here?


Posted by Richard Hamilton on
Aha, here is the problem I think!

"Posted by Gustaf Neumann on 05/14/09 05:53 AM

A small followup: in order to develop a new viewer for e.g. categories, i would recommend to disable for the development the includelet caching (set parameter "cacheable" of the includelet "categories" to false). Otherwise you have to flush the page fragment cache entries frequently to check the results of your changes."

Posted by Richard Hamilton on
No wonder I'm having trouble! Even when I disable the page fragment caching for the categories includelet, the page is still cached! 😟

{{categories -decoration none -cacheable false -style samplemenu -order_items_by page_order,asc}}

The only way I can get changes to be reflected in the delivered output is to create a new revision.

Does anyone have any idea why "-cacheable false" is not working? Is there any other way to disable the page fragment caching while I work on my new TreeRenderer?


Posted by Gustaf Neumann on
The parameter "cacheable" is not setable on the includelet instance level, but on the includelet class level. This means that you have to alter in xowiki/tcl/includelet-procs.tcl the value of this flag from "true" to "false":
  ::xowiki::IncludeletClass create categories \
      -superclass ::xowiki::Includelet \
      -cacheable true -personalized false -aggregating true \
      -parameter {
        {title "Categories"}
        {parameter_declaration {
          {-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 ""}
          {-except_category_ids ""}
          {-allow_edit false}
The values under "parameter_declaration" are the ones that can be specified on a per-includelet instance level (when the includelet is instantiated, e.g. between curly brackets).

Note that when you change this definition, you should flush the page fragment cache via http://YOURHOST/xotcl/cache?cache=xowiki_cache (or restart the server).

Some more background: xowiki has various kinds of caches. The categories includelet can be cached in the so called "page fragment cache". The xowiki infrastructure supports various kinds of caching for page fragments, which can be specified as follows

  • cacheable: turn caching on/off for this includelet
  • aggregating: cached page fragments are flushed, when items in this instance are added/edited/deleted. This is useful, when altering content item in this instance might cause a different output from this includelet (this is the case for the categories includelet)
  • localized: different cached values are kept for every locale; useful, when an includelet returns different values depending on the locale
  • personalized: different cached values are kept per user-id; useful, when an includelet returns different values per user.
To understand caching, it helps to look at the cached values in the page fragment cache as indicated above.

Hope this helps

-gustaf neumann

Posted by Richard Hamilton on
Aha!! Thank you very much!

Yes, that helps tremendously.