dialog.mc - Dialog contruction module.

- NAME
- SYNOPSIS

- Usage
- Parameters

- METHODS

- edit_dialog
- form

- DIALOG FORM FIELDS

- cell
- label_value_row
- canvas
- field
- hidden
- popup_menu
- radio_group
- textfield
- password
- textarea
- xacl_field
- upload
- yes_no
- checkbox
- date
- read_only
- buttons
- _table3td

- REQUEST HANDLING METHODS

- handle_request
- htmlSave
- isButtonPressed
- back_url

- AUTHOR

# NAME

dialog.mc - Dialog contruction module.

# SYNOPSIS

This Mason component replaces obsoleted ePortal::HTML::Dialog package.

`dialog.mc` is used to draw a dialog like windows. Some methods are used for easy creation of dialogs to edit `ThePersistent` objects.

## Usage

     <&| /dialog.mc, parameters ... &>
      content of the dialog
     </&>

## Parameters

- width,align
  These parameters are passed to <table> tag.

- color,bgcolor
  Colors used

- title, title_url, title_popup, title_class
  The title of dialog

- icons
  ArrayRef to HASHes with infomation about icons to place on the right side of the title. This HASH is passed directly to `img()` global function.

       icons => [
          { src => '/images/image.gif',
            href => 'some.where.htm',
            title => 'alt description for icons' }
       ]

- xxx_icon
  Some of icons are known to dialog.mc. No need for them to pass image source url. Icon names are edit q copy min max x

  xxx_icon - URL for the icon

  xxx_icon_title - popup title for the icon

  where xxx is a name of icon.

# METHODS

## edit_dialog

This method used to construct ``Edit an object'' dialog with a submit form iside.

WARNING! This method generates

     <table cols="2">
      Your content here
     </table>

Parameters:

- obj
  `ThePersistent` object to edit.

- xxx_icon
  For predefined icons enough to pass parameter

       xxx_icon => 1

  to construct an icons with all needed parameters. Call `isButtonPressed('xxx')` to check what button or icon was actually clicked.

- focus
  Name of the field to be focused when dialog apeears on screen

## form

Generate HTML form. See field methods for details how to generate HTML fields.

     <& /dialog.mc:form, parameters, ... &>

- formname
  Name of the form. Default is 'theForm'

- method
  Method of the form. Default is 'POST'

- action
  Action of the form. Default is $ENV{SCRIPT_NAME}

- multipart,multipart_form
  If true generate multipart form.

# DIALOG FORM FIELDS

Most of dialog field creation method accepts the following parameters:

- obj
  Base ThePersistent object to be edited. The `$obj` object may contain some useful attributes: `fieldtype`, `value`, `label`, etc...

- label
  What label to attach for the field. Default is `label` attribute of the object.

- value
  Default value of the field. Default is `value` attribute of the object.

- class,align
  These parameters are applied to `canvas` property.

## cell

Draw a cell for edit_dialog. That is is <td colspan=``2''>. All -xxx like parameters are passed to CGI::td() function.

## label_value_row

Draw a row with two cells: label and value

- label
- value

## canvas

Display `content` inside a `canvas`.

     <&| /dialog.mc:canvas, label => ..., parameters, ... &>
      dialog value
     </&>

     <canvas>
      <% optional label %>
      <% $m->content %>
     </canvas>

- label
  Optional label for content. Styled with class=``dlglabel''.

- canvas
  Type of canvas. May be one of the following: tr td div span none

- vertical
  Align label and content vertically. Not possible for tr canvas.

       <canvas>
        label
        content
       </canvas>

## field

Discover field type with a help of `fieldtype` attribute of the object and call appropriate method of dialog.mc. Default field type is `textfield`.

This is default method to produce a dialog field. This method created a row of table

     <tr>
       <td>label:</td> <td>field</td>
     </tr>

- obj
  The object to edit.

- name,id
  Mandatory. The name of the field to generate.

## hidden

/dialog.mc:hidden - generate hidden field

- name
  Name of the field

- value
  Value of the field

## popup_menu

Generates list box aka popup_menu.

- values
  Array ref of values

- labels
  Hash ref of labels for values. Every HASH label is decoded with pick_lang().

- popup_menu
  Callback function. Called with the object as argument. Should return array

       ($values_array, $labels_hash)

## radio_group

Generates radio button group.

- values
  Array ref of values

- labels
  Hash ref of labels for values. Every HASH label is decoded with pick_lang().

## textfield

Generate text field.

- size
  Visible size of text field

- maxlength
  Maximum length of input string

See DIALOG FORM FIELDS for other parameters.

## password

Generate password input field.

- size
  Visible size of text field

- maxlength
  Maximum length of input string

See DIALOG FORM FIELDS for other parameters.

## textarea

Generate text area field.

- rows,cols
  Visible size of text area field

- maxlength
  Maximum length of input string

See DIALOG FORM FIELDS for other parameters.

## xacl_field

Generate ACL property field.

See DIALOG FORM FIELDS for other parameters.

## upload

Generate file upload field.

See DIALOG FORM FIELDS for other parameters.

## yes_no

Generates list box or checkbox to input YES or NO.

## checkbox

Generates checkbox tag.

## date

Generates date input field.

## read_only

Generate text read only field.

See DIALOG FORM FIELDS for other parameters.

## buttons

Display dialog buttons.

     <& /dialog.mc:buttons, parameters, ... &>

Possible button names are: ok, cancel, more, delete, apply.

To diplay a button pass parameter xxx_button => 1

To change predefined label of a button pass parameter xxx_label => ``...''

ok and cancel buttons are displayed by default.

## _table3td

Internal method. Do not use it! Used to produce one row table with three cells. This is the correct way to align a table.

     td1     td2     td3

- td1
  Content of cell td1

- td2
  Content of cell td2

- td3
  Content of cell td3

- align
  Where to place ``main'' content. Left is td1, center is td2, right is td3.

- extra
  Extra info. Placed in opposite of main content (left or right). Not used if main content is aligned at center or none.

# REQUEST HANDLING METHODS

## handle_request

This the engine of dialog. Call it from `onStartupRequest` method for proper redirect handling.

This method does the following:

1. restore_or_throw object to edit

2. htmlSave parameters from request

3. if ok button is pressed then save the object and redirect to back_url

4. if cancel button is pressed then just redirect to back_url

- obj
  Required. The object to work on it.

- objid
  This parameter usually passed as request parameter. The ID of object to edit.

## htmlSave

This method is under construction

Safely get attributes values from request and apply them to the object. This method does not updates the object in database. Do it yourself.

This method does extra processing for special multipart attributes like DateTime, xacl_field, etc...

This method does not updates ID attributes.

- obj
  Object to update.

## isButtonPressed

Check is a button was pressed on dialog.

Every standard dialog button named as `dlgb_NAME`. If no `dlgb_NAME` parameter exists in request then `isButtonPressed('ok')` returns true on dialog submit.

- button
  A button name to check.

       icons: q max min edit x
       buttons: ok cancel copy delete apply more

## back_url

Calculates URL where to return (redirect) from Dialog when a button will pressed.

# AUTHOR

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