is_upload($name)

SEE ALSO

NAME

iAct - A multi-lingual web development and templating framework built on Apache and mod_perl.

SYNOPSIS

  <% # This snippet goes in an html file, accessible through Apache
       and handled by iAct's ContentHandler %>
  <table>
  <tr>
    <th><% lang en %>Param<% lang es %>Parámetro<% /lang %></th>
    <th><% lang en %>Value<% lang es %>Valor<% /lang %></th>
  </tr>
  <% call My::App::list_params repeat="one_param" %>
  <% section "one_param" %>
  <tr>
    <td><$ name $></td>
    <td><$ value $></td>
  </tr>
  <% /section %>
  </table>

  # And this is My/App.pm :
  package My::App;
  use strict;
  use iA;

  sub list_params {
    my ($self, $args) = @_;
    my ($txt, $sec) = ("", $args->{repeat});
    foreach my $p (iA::param()) {
      $self->assign_raw(name  => iA::escapeHTML($p),
                        value => iA::escapeHTML(param($p))
                       );
      $txt .= $self->fetch($sec);
    }
    $txt;
  }

1;

ABSTRACT

iAct is a web development and templating framework built on Apache and mod_perl.

The basic premise of iAct is that a webpage is not a linear sequence of html markup, but a collection of named chunks called sections, which insert themselves into more general templates. iAct encourages structured reuse of html code and design elements, by moving all the ``skeleton'' code (<html>, <body>, <table>s used for layout, etc) out of the individual html pages, into template files. These templates can in turn embed themselves into more general templates.

This results in a global tree hierarchy of templates, with the URL-mapped pages as its leaves. A small, purely declarative language is used to define sections within pages, use parent templates, import sections from other files, and define gaps where named content should be inserted.

From this language, Perl routines can be called by their name, and their output inserted into the stream. These perl subs have full access to the sections on the file they were called from, and on the templates it uses.

iAct is thoroughly multi-lingual; content can be entered in multiple languages, in separate files (blah.html.en, blah.html.es) or within a single file, using the <% lang %> command. This is integrated all the way to the ContentHandler, which determines a language preference list from the user's request, and sets the right http headers for the response language.

DESCRIPTION

The iA module provides functions to access global properties of the current connection, such as cookies, form parameters and file uploads. It also provides common utility functions for web programming, such as URL and HTML escaping.

See also the iA::Page documentation, for the list of methods available to manipulate sections, filters, and other page elements.

There are several ways to call functions in the iA module:

Directly by iA::function name

      use iA;

      sub whatever {
        my $name = iA::param("name");
        return iA::escapeHTML($name);
      }

From the iA::Page object passed by <% call %>

      sub whatever {
        my ($self, $args) = @_;
        my $name = $self->param("name");
        return $self->escapeHTML($name);
      }

Using iA.pm in an object-oriented way

      use iA;

      sub whatever {
        my $ia = new iA;
        my $name = $ia->param("name");
        return $ia->escapeHTML($name);
      }

The functions in iA.pm deal with data associated with the current HTTP connection, which is naturally a global object. The object-oriented interface is only a calling convention provided for convenience.

Calling functions directly by their qualified names (eg. iA::param(``blah'')) is the recommended interface, and also the fastest one.

FUNCTIONS

escape($value): URL-escape a string. This makes it fit to put in an URL parameter, eg. /path/to/page.html?param=URL%20escaped%20value

unescape($value): This function un-URL-escapes a string, replacing plusses with spaces, and 2-digit %codes with the corresponding characters.

escapeHTML($value): HTML-escape a string. This makes it fit to insert in an HTML page.; Note: it is a security hole to copy text strings provided by (untrusted) users into webpages shown to other users, without HTML-escaping them first!

notes($req, $key, $value): An interface to Apache notes, for inter-module communication. Mostly used internally by iAct. The first argument must be the current Apache request object (obtained with iA::request()).; Apache notes are a table key=value pairs that can be accessed by the various Apache modules, at each step of the processing chain. This wrapper always uses the ``main'' request object, so notes stick through subrequests.; If you don't provide a value, this function returns the current value of the note for the given key.

get_cookie($name): Returns the cookie of the given name, or undef if there is no such cookie. The cookie is an iA::Cookie object, which has the same methods as CGI::Cookie objects.

set_cookie($value)

This function creates a cookie, and adds it to the outgoing headers for the current request. The parameters are with CGI::Cookie's ``new'' method, e.g

  iA::set_cookie(-name => "blah", -value => "erf",
                 -expires => '+3d');

get_page($filename, $options)

Open an iAct-HTML page, going through the cache and parsing the sections, but not taking any <% parent %> or <% import %>s into account. Returns an iA::Page object.

Some methods available on iA::Page objects include assign, assign_raw and fetch. See the iA::Page documentation for details.

The $filename is absolute. $options is a hashref with parameters to be passed to iA::Page. The only recognized option is 'lang', which introduces an arrayref of language names, by preference order; eg.

  my $page = iA::get_page("/path/to/file.html",
                          { lang => [ "en", "es" ] });

get_template($filename, $options)

Open an iAct-HTML page, going through the cache and parsing the sections, and also loading any dependent files such as <% imports %> and the <% parent %> chain. Returns an iA::Template object.

The only interesting method available on iA::Template objects is page, which evaluates and returns the HTML page.

The $filename is relative to the HTML root directory. $options is a hashref with parameters to be passed to iA::Page. The only recognized option is 'lang', which introduces an arrayref of language names, by preference order; eg.

  my $tmpl = iA::get_template("/path/to/file.html",
                              { lang => [ "en", "es" ] });

grab_params($string, $how): Takes a string, attempts to read a list of keys & values, and adds them to the current iA::param list. Recognizes ?&: as separators.; The 2nd param tells it what to do with keys that already exist:

set_params($key, $value, ...)

Takes a hashref or a list of keys & values, and sets them as params (one value per key only).

This is useful for <% call %>'ed subs when they want to push the params they've been passed as global params, and access them through iA::param(). The idiom is:

        sub myfunction {
          my ($self, $args) = @_;
          iA::set_params($args);
          ...
        }

These params always override any old values for keys that already existed.

now(): Get (or set) the current, cached time. Using this rather than direct calls to time() can save a few system calls by cache-ing the result within a request.; Time values are 32-bit integers, counting the number of seconds since 1 Jan 1970.

request(): Get the Apache request object. See the Apache manpage for details on the Apache request object.; Most user code shouldn't need this, but it is needed to get to iA::notes().

path_info(): Returns any additional path elements after the file name in the URL. For instance, if the current page is /path/to/file.html, and you access it as /path/to/file.html/foo/bar/urf.ext, then iA::path_info() will return ``/foo/bar/urf.ext''.

self_url(): Returns the URL of the current request, including the filename, any extra path_info, and any request parameters that were part of the URL.; Note that this will preserve form parameters if the form's method was GET, but not if it was POST.

url($option => 1, ...): Returns the URL of the current request in a variety of formats, similar to the CGI::url() function in the CGI.pm package.; This functions accepts the following options:

user_agent(): Get this request's User-Agent string (eg. ``Mozilla/4.75 [en] (X11; U; Linux 2.2.17-21mdk i686; Nav)'').

referer(): Get this request's referer URL.

remote_host(): Get the client's hostname, or, failing that, the remote IP address.

remote_addr(): Get the client's IP address.

auth_type(): Get the request's auth type (eg. ``basic'' or ``digest''), for password-protected pages.

remote_user(): Get the authorization name, for user verification with the ``basic'' auth type.

server_name(): Get this server's name (possibly virtual).

request_method(): Get the request's method (eg. ``GET'', ``POST'').

param(): Get or set parameters; one parameter can get more than one value in a single call. This function can be used in 3 ways:

param1(``name1'', ``name2'', ...)

Reads parameters passed to the current page. This function returns excactly one scalar value for each argument. The idiom is

  my ($foo, $bar, $zoinx) = iA::param1("foo", "bar", "zoinx");

delete(``name'', ...): Deletes one or more parameters.

upload($name): Gets a file upload, by name. The name is corresponds to the name=``whatever'' value in the <input> HTML tag.; If the file was uploaded, this function returns a list with 4 elements:

`is_upload($name)`

Simply checks to see if a filename has been entered in a file form field. Returns 1 if it's there, 0 otherwise.

set_header(``Header'' = $value)>: Set a header in the out-going HTTP response to the client. Note that these headers don't get sent out if the response ends up being an error code (eg. with iA::not_found()).

get_header($name): Get an http header from the request, by name; ex. iA::get_header(``Accept'').

has_priv($priv): Checks if the currently logged-in user has a given privilege.; The user's privileges are taken from iA::param('priv'), which is a comma-separated list of keywords. Optionally, the first keyword can be a number, in which case has_priv($number_smaller_than_that) will return true.; The global privilege configuration (list of known privileges, implied privs, etc) is in iA::Config.

keep($name): This marks a parameter for keeping, so that it gets preserved in a cookie (or in all the links from the current page, if cookies are off).; This function applies to this request only; kept parameters can be read again (with iA::param()) at the next request, but you will have to call iA::keep() again if you want to keep preserving them.; See the iA::State module for details about iAct's client-side state management.

redirect($url): Send a redirection (302) to another URL. The URL should be fully-qualified, including the http://hostname.domain/ part.

file_redirect($filename): This silently redirects the client to another file on the system, also handled by iAct. All the iA::param()s are preserved; the assign'ed sections aren't.; The filename is relative to the HTML root directory.

redirect2($url): Does a ``smart'' redirection, automatically adding the hostname in front of absolute URLs, and adding the ::data at the end of the URL if the redirection is within the site and cookies are not known to be on.

return_html($html_text, $language): This returns the given HTML to the client, escaping from any levels of templating/calls/etc. The HTML should be a self-sufficient page, including the <html> and <body> tags.; This is useful for returning ``exceptional'' content, and to show pages done with systems other than iAct (eg. CGI::FastTemplate).; The language parameter is optional, and represents the language in which the HTML contents are.

return_file($filename, $mime_type): This returns the contents of the given file to the client, escaping from any levels of templating, calls, etc. The file is served by Apache's C code, so this is more efficient than reading and printing it out from perl.; This is useful to implement ``download''-type links, when the item to be downloaded is a file.; The mime_type parameter is optional. If given, it specifies the mime type to return in the returned HTTP headers; otherwise the mime type is just whatever Apache guessed from the URL, usually 'text/html'.

not_found(): Returns a ``404 not found'' error to the client.

warn($message): Issue a warning; warnings to go the error_log, and are collected by the ContentHandler so they can be displayed to the browser in debug mode.; Debug mode can be entered by appending ``?debug=1'' to the end of URLs; you need to be logged-in, and have privileges, for debug mode to work.

notice($message): Notices are just like warnings, but they don't go to the error_log (only to the browser in debug mode).

warnings($value): Returns the list of warnings; mostly for use by the content handler.

new()

This is the constructor method for the OO interface to iA.pm. All the iA::* functions can be called as methods of the object returned by iA->new(). Ex:

       my $ia = new iA;
       my $name = $ia->param("name");