Sub-totalling with List Builder is a great feature and I would definitely recommend using it over hand-coding your sub-totals but isn't fully documented, and there are a few gotchas, so I've put a few notes together to help you use it.



Let's just take a simple list with 2 columns: stage_description and financial_amount. We want to aggregate financial_amount for each stage_description. So in the beginning the elements section of our list looks like this:

  -elements {
          stage_description {
            label "[_ payment.Financial_Stages]"
          }
          financial_amount  {
            label "[_ payment.Amount]"
          }
    }





1. First we create a variable named groupby – give it a value of the name of the element we want to group by. Put this before our list definition. Behind the scenes this tells List Builder to create a filter named "groupby" (according to the docs you may need to put this in your ad_page_contract – I didn't need to):

set groupby "stage_description"



2. Add a new groupby section to end of the list. "type multivar" just tells List Builder to tell ad_page_contract that the groupby is not a multiple element. All the curly brackets are unfortunately needed – the first list element is the text which is displayed in front of each group; you can put HTML tags and more in here. The second list element tells List Builder that we are grouping by stage_description – this seems repetitive so maybe there’s a better way to do this, but I can't see any issues with it. You can also have an orderby clause in here if you need one.

  -groupby {
      type multivar
      values {
        { {[_ payment.Financial_Stage]} { {groupby stage_description} } }
      }
  }



3. Modify the financial_amount element to add aggregation information. aggregate can be one of “sum”, “average” or “count”. The aggregate_group_label allows you to put some text and a currency symbol before each sub-total. aggregate_label does the same for the grand total.

          financial_amount {
            label "[_ payment.Amount]"
            aggregate "sum"
            aggregate_group_label "[_ payment.Sub-Total]: [lc_get -locale $locale currency_symbol]"
            aggregate_label "[_ payment.Grand-Total]: [lc_get -locale $locale currency_symbol]"
          }



4. Gotchas to look out for:

you need to  use the -pass_properties section to allow List Builder to see program variables outside the list scope e.g. $locale.



List builder doesn't differentiate between currency and numbers – it just treats the aggregated column as a number. However, it does use the acs-lang formatting when displaying (specifically lc_numeric), which should be good enough for most cases. You need to do your own formatting on the individual line items. Here's how to use display_eval to format the financial_amount element:

display_eval {[lc_monetary -label_p "t" $financial_amount $locale ]}



Noquoting can be painful but the following workaround should suffice – note the triple underscore:

display_template {@financial.financial_amount___display;noquote@}




Our finished example:

  -elements {
          stage_description {
            label "[_ payment.Financial_Stages]"
          }
          financial_amount {
            label "[_ payment.Amount]"
            aggregate "sum"
            aggregate_group_label "[_ payment.Sub-Total]: [lc_get -locale $locale currency_symbol]"
            aggregate_label "[_ payment.Grand-Total]: [lc_get -locale $locale currency_symbol]"
display_eval {[lc_monetary -label_p "t" $financial_amount $locale ]}
display_template {@financial.financial_amount___display;noquote@}
          }
    }
  -groupby {
      type multivar
      values {
        { {[_ payment.Financial_Stage]} { {groupby stage_description} } }
      }
  }





A good example from OpenACS CVS:

http://cvs.openacs.org/cvs/openacs-4/packages/dotlrn-ecommerce/lib/tree-chunk.tcl?rev=1.2&view=markup