list.mc - List of something as HTML table

- NAME
- SYNOPSIS
- PARAMETERS
- METHODS

- row
- extra_row
- row_span
- action_bar
- checkboxes
- list_action
- column
- column_image
- column_delete
- column_edit
- column_checkbox
- column_number
- state
- self_url
- state_as_hidden
- before_title,after_title,before_footer,after_footer
- nodata

- REQUEST ARGUMENTS
- AUTHOR

# NAME

list.mc - List of something as HTML table

# SYNOPSIS

This Mason component replaces absoleted ePortal::HTML::List package.

It is used to create HTML tables for iterable objects and arrays.

     <&| /list.mc, id=>'list1', obj => $object OR  list => [@array] &>

      <&| /list.mc:row, parameters &>   # this method is optional
        <& /list.mc:column, parameters &>
        <& /list.mc:column_image, src => ... &>
      </&> # end of row
      <&| /list.mc:extra_row &>
         ...
      </&>

      # These method going after all "column" methods
      <&| /list.mc:before_title &> ...  </&>
      <&| /list.mc:after_title &> ...  </&>
      <&| /list.mc:before_footer &> ...  </&>
      <&| /list.mc:after_footer &> ...  </&>

      <&  /list.mc:row_span &>
     </&> # end of list

The typical list consists of the following:

     <table>
      <form>

       <before_title row>
       <title row>
       <after_title row>

         <one or more rows>
          <extra_row for each row>

       <before_footer row>
       <footer row>
       <action_bar row>
       <after_footer row>

      </form>
     </table>

The content of <&| list.mc &> is responsible for HTML generation of each row.

The very first call to content is when row_number==0. This call is used to count all columns, create soring groups and discover column titles. ThePersistent object is not restored at this moment and $_ is undefined for array lists.

Use local variable `$_` as iterator for array. $_ is the object for ThePersistent lists.

# PARAMETERS

All -xxx like parameters are passed directly to CGI::start_table. Others are

- id
  The ID of the list. Used for submit forms and when more then 1 list exists on page.

- submit
  Make HTML form inside the list.

- no_title
  Do not produce title row

- no_footer
  - ==1
    Do not produce footer row any case

  - ==2
    Show footer row if there is more than one page to display

- order_by
  ID of column to order by this column by default or ``!ID'' string to order by descending.

# METHODS

## row

Generic method to make a row. Call once per list content. Use extra_row method if you need more than one row per iteration.

This is optionsl method. list.mc call it implicitly at least once if you don't.

     <&| /list.mc:row &>
      <& /list.mc:column &>
      ...
     </&>

     <&| /list.mc:extra_row &>
      this is additional row
     </&>

- -xxx
  All parameters starting with '-' are passed to CGI::Tr() function.

## extra_row

Produce ``extra'' row in the same style as main row. Used for description and memos

- start_column
  By default extra_row is a td with all columns colspan. `start_column` specifies starting column to make colspan

- tr
  Parameters hash to pass to CGI::Tr() function

- td
  Parameters hash to pass to CGI::td() function

- -xxx
  All parameters starting with '-' treated as parameters for td

- content
  The content of extra row. You may use <&|> call instead of it.

## row_span

Make a space between rows.

     <&| list.mc:row &>
      ...
     </&>
     <& list.mc:row_span &>

- height
  Height of free space in pixels

## action_bar

Action bar below footer consists of two cells. Left is your content and right is popup_menu with submit button. The name of popup_menu is list_action. You may get it with list_action method or as $ARGS{list_action}.

Array of ID of selected checkboxes available with checkboxes method.

- content
  The content of left cell. You may use <&|> call instead of it.

- td
  Parameters hash for left CGI::td() function

- popup_menu
  Parameters hash for popup_menu

- button
  Optional parameters hash for submit button. Defaults are enough.

- label
  A label for popup_menu. Default is ``Selected items:''

## checkboxes

Returns array ID of checked checkboxes or empty array.

## list_action

Returns a value of list_action popup_menu or undef if form was not submitted. The fact of submit is request method eq 'POST'.

## column

Generic method to make a column. Call it as many times as many columns you have. Place the calls inside `row` method.

- id
  ID of the column. Also act as field name for Persistent objects

- title
  Column title

- a
  Hashref of arguments for CGI::a().

- url
  More short way to say a => {-href => ...}

- self_url
  Hashref of parameters to cunstruct self referencing URL. These parameters will be replaced with given values.

  A special parameter '#' => ... will be added as URL anchor

- -xxx
  All parameters like -xxx are passed to CGI::td() function.

- order_by
  Order By clause of SQL query when sort is on by this column. `id` column parameter is required if you use `order_by` of `order_by_desc` feature.

- order_by_desc
  Descending sorting for this column. By default is ``order_by DESC''.

## column_image

A column with image.

- src
  Path to image. Default is `/images/icons/msg.gif`

## column_delete

Produce delete button.

- url
  Optional URL for delete action.

- objid
  Optional object id for delete.htm. Default is ID of current object.

- objtype
  Reference type of object to delete. Default is ref of current object.

## column_edit

Produce ``edit object'' button.

- url
  URL for edit action.

- objid
  Optional object id of object to edit. Default is ID of current object.

## column_checkbox

Produce checkbox column

- value
  The value of checkbox. Default is array element or object ID

- name
  Name of checkbox field. Default is `list_chboxLISTID`

## column_number

Row number counter

## state

Returns HASH of arguments that represent current state of the list. Put these parameters to other forms on the page to save list apperance untouched.

- id
  ID of list

## self_url

Return self referencing URL without checkboxes selected.

## state_as_hidden

Put list state as hidden fields into your form

## before_title,after_title,before_footer,after_footer

This method used to insert a text before|after title|footer row. Place it AFTER all `column` methods. The content of method method is placed into one wide TD cell. Arguments are:

     <&| /list.mc:before_title &>
      this text goes before title row
     </&>

## nodata

What to show when no data available in recordset?

- content
  The content of warning

# REQUEST ARGUMENTS

These arguments are significant for list.mc when exists in request. See state method for convenient way to get hash of all of them.

- rowsLISTID
  Rows per page for LISTID list.

- pageLISTID
  Page number to display for LISTID list.

- order_byLISTID
  Sort order internal variable. This is id of column to sort ascending or !id to sort descending.

# AUTHOR

Sergey Rusakov, <rusakov_sa@users.sourceforge.net>