autohandler.mc - Base Mason component

- NAME
- SYNOPSIS
- ATTRIBUTES

- Title
- Popup
- Directory browsing

- dir_enabled
- dir_nobackurl
- dir_sortcode
- dir_description
- dir_columns
- dir_include,dir_exclude
- dir_title

- Access control

- require_registered => boolean
- require_user => [ ]
- require_group => [ ]
- require_admin => boolean

- METHODS TO OVERLOAD

- HTMLhead
- onStartRequest
- Title
- Footer
- MenuItems

- COMMON URL ARGUMENTS
- AUTHOR

# NAME

autohandler.mc - Base Mason component

# SYNOPSIS

autohandler.mc is base Mason component for entire ePortal site.

# ATTRIBUTES

Attributes are defined via <attr> mason tag:

     <%attr>
     Attribute => value
     </%attr>

## Title

This is title for the page. This title is used for <TITLE> HTML tag and displayed at top of every ePortal's page.

This attribute is used for static Title. For dynamic Title see `Title` method

## Popup

May be 1 or 0. Default is 0.

Used for popup windows. No windows caption, no APP bar, no menus.

## Directory browsing

There are some attributes to control directory browsing process. Browsing is go when no index.htm file in directory.

### dir_enabled

Enable or disable directory browsing. Default is 1. Is browsing is disabled then redirect to /errors/not_found.htm is done.

### dir_nobackurl

Show or not `..` at top of list of files.

### dir_sortcode

Should be sub ref. Two arguments ($a,$b) are passed to sub which both are absolute filenames.

### dir_description

How to discover a description of a file? May be HASH with filenames or sub ref. Two arguments `(absolute_filename,filename)` are passed to sub.

The default is `\&ePortal::Utils::filter_auto_title`

### dir_columns

How many columns and which to show? This is array ref. Possible values are: /icon name size modified description/

### dir_include,dir_exclude

Array ref with regexs. First all dir_include regexs work then dir_exclude. Default is to include all files.

### dir_title

How to title the directory listing? Default is directory name.

## Access control

You always may restrict access to some pages with a help of .htaccess. Use `require` directives to to this.

Here is another way to do this. You may use the following attributes in pages or directory autohandlers to restrict access to some parts of your site.

Attributes are processed in given order. If any of them are true then access is allowed else redirect is made to /errors/require_xxx.htm page.

### require_registered => boolean

Requre user to be registered. Deny access for anonymous users.

### require_user => [ ]

Require user to be registered and be listed. Argument if array ref to list of valid user names.

### require_group => [ ]

Require user to be registered and be member of a group. Argument if array ref to list of valid group names.

### require_admin => boolean

Require user to be registered and be an admin.

# METHODS TO OVERLOAD

You may overload some autohandler's method to add more functionality to a page.

     <%method method_name>
     .. your code goes here
     return "something";
     </%method>

Overloaded parent can be called as

     <& PARENT:method_name, %ARGS &>

## HTMLhead

Add any HTML text to put in <HEAD> section of HTML page.

## onStartRequest

This method is called just after request processing preparation (check user, etc.) but before any content is sent to client. This method is useful for client events processing and handling redirects.

Any string returned is passed to redirect.mc to do external redirect.

## Title

This is the same functionality as `Title` attribute. This method is used to make the Title be dynamic not static.

## Footer

This is very last part of screen. Useful to show copyright messages

## MenuItems

This method is used to show a menu on the left side of the screen. It returns an array or pairs.

     <% method MenuItems>
     % return [
       ['menu1' => 'http://...'],
       ['---' => '---'],
       ['html' => '<b>this is HTML</b>']
      ];
     </%method>

Every pair may be any of the following

- ['title','URL']
  Used to make usual menu item

- ['---','---']
  Make a horizontal separator 1 pixel height

- ['require-user','username']
  Require `username` to be registered to see next items.

- ['require-group','groupname']
  Require the user to be member to the `groupname` to see next items.

- ['require-none','']
  Turns off any restriction on user or group to see next items.

- ['html','any HTML text']
  This pair is used to produce any HTML text at this point.

- ['img','http://www/images/file.gif']
  Just insert an image at this point

- ['',5]
  Insert blank row 5 pixels width.

# COMMON URL ARGUMENTS

Some arguments names are reserved for internal purposes. Here are:

- objid
  Object identifier. The ID of the current object to work with it.

- objtype
  Type of the object. It means `ref($object)` in Perl.

- cal_xxx
  Reserved for `calendar` component

- dlg_xxx,dlgb_xxx
  Reserved for Dialog controls and buttons.

- list_xxx
  Reserved for `list` component.

# AUTHOR

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