NAME

AxKit::XSP::WebUtils - Utilities for building XSP web apps

SYNOPSIS

Add the taglib to AxKit (via httpd.conf or .htaccess):

    AxAddXSPTaglib AxKit::XSP::WebUtils

Add the web: namespace to your XSP <xsp:page> tag:

    <xsp:page
         language="Perl"
         xmlns:xsp="http://apache.org/xsp/core/v1"
         xmlns:web="http://axkit.org/NS/xsp/webutils/v1"
    >

Then use the tags:

  <web:redirect>
    <web:uri>foo.xsp</web:uri>
  </web:redirect>

DESCRIPTION

The XSP WebUtils taglib implements a number of features for building web applications with XSP. It makes things like redirects and getting/setting headers simple.

TAG REFERENCE

All of the below tags allow the parameters listed to be either passed as an attribute (e.g. <web:env_param name="PATH">), or as a child tag:

  <web:env_param>
    <web:name>PATH</web:name>
  </web:env_param>

The latter method allows you to use XSP expressions for the values.

<web:env_param name="..." />

Fetch the environment variable specified with the name parameter.

  <b>Server admin: <web:env_param name="SERVER_ADMIN"/></b>

<web:path_info/>

Returns the current PATH_INFO value.

<web:query_string/>

Returns the current query string

<web:request_uri/>

Returns the requested URI minus optional query string

<web:request_host/>

This tag returns the end-user-visible name of this web service

Consider www.example.com on port 80. It is served by a number of machines named abs, legs, arms, pecs and foo1, on a diversity of ports. With a proxy server in front that monkies with the headers along the way. It turns out that, while writing a script, people often wonder "How do I figure out the name of the web service that's been accessed?". Various hacks with uname, hostname, HTTP headers, etc. ensue. This function is the answer to all your problems.

<web:server_root/>

Returns the server root directory, aka document root.

<web:redirect>

This tag allows an XSP page to issue a redirect.

Parameters (can be attributes or child tags):

uri (required)

The uri to redirect to.

host (optional)

The host to redirect to.

secure (optional)

Set to "yes" if you wish to redirect to a secure (ssl/https) server.

Example (uses XSP param taglib):

  <web:redirect secure="yes">
    <web:uri><param:goto/></web:uri>
  </web:redirect>

<web:url_encode string="..."/>

Encode the string using URL encoding according to the URI specification.

<web:url_decode string="..."/>

Decode the URL encoded string.

<web:header>

This tag allows you to get and set HTTP headers.

Parameters:

name (required)

The name of the parameter. If only name is specified, you will get the value of the incoming HTTP header of the given name.

value (optional)

If you also specify a value parameter, then the tag will set the outgoing HTTP header to the given value.

Example:

  <p>
  Your browser is: <web:header name="HTTP_USER_AGENT"/>
  </p>

<web:return_code/>

This tag allows you to set the reply status for the client request.

Parameters:

code (required)

The integer value of a valid HTTP status code.

<web:username/>

Returns the name of the authenticated user.

<web:password/>

If the current request is protected by Basic authentication, this tag will return the decoded password sent by the client.

<web:request_parsed_uri>

This tag allows you to get the fully parsed URI for the current request. In contrast to <web:request_uri/> the parsed URI will always include things like scheme, hostname, or the querystring.

Parameters:

omit (optional)

Valid values: path, path_info, and query. If specified, the corresponding URL components will be ommited for the return value.

<web:request_prev_parsed_uri>

This tag allows you to get the fully parsed URI for the previous request. This can be useful in 403 error documents where it is required to post login information back to the originally requested URI.

Parameters:

omit (optional)

Valid values: path, path_info, and query. If specified, the corresponding URL components will be ommited for the return value.

Example:

  <p>Access Denied. Please login</p>
  <form method="post" name="login">
      <xsp:attribute name="action">
          <web:request_prev_parsed_uri omit="query"/>
      </xsp:attribute>
      ...

<web:request_prev_uri/>

Returns the URI of the previous request minus optional query string

<web:request_prev_query_string/>

Returns the query string of the previous request.

<web:request_prev_param name="...">

Returns the value of the requested CGI parameter of the previous request.

Parameters:

name (required)

The name of the parameter to be retrieved.

<web:match_useragent name="...">

Returns true if the User Agent pattern in name matches the current User Agent.

Parameters:

name (required)

A User Agent pattern string to be matched.

Example:

  <xsp:logic>
  if (!<web:match_useragent name="MSIE|Gecko|Lynx|Opera"/>) {
  </xsp:logic>
      <h1>Sorry, your Web browser is not supported.</h1>
  <xsp:logic>
  }
  else {
  </xsp:logic>
  ...

<web:is_https/>

Returns true if the current request comes in via SSL.

Example:

  <xsp:logic>
  if (!<web:is_https/>) {
  </xsp:logic>
    <a>
      <xsp:attribute name="href">
        https://<web:request_host/><web:request_uri/>
      </xsp:attribute>
      use secure connection
    </a>
  <xsp:logic>
  }
  </xsp:logic>

<web:is_initial_req/>

Returns true if the current request is the first internal request, returns false if the request is a sub-request or an internal redirect.

<web:variant_list/>

Returns the list of variants returned by mod_negotation in case of a 406 HTTP status code. Useful for 406 error documents.

Example:

  <h1>406 Not Acceptable</h1>
  <p>
    An appropriate representation of the requested resource <web:request_prev_uri/>
    could not be found on this server.
  </p>
  <web:variant_list/>

<web:server_admin/>

Returns the value of the Apache "ServerAdmin" config directive.

<web:error_notes/>

Returns the last 'error-notes' entry set by Apache. Useful for verbose 500 error documents.

Example:

    <h1>Server Error</h1>

    <p>An error occured. If the problem persists, please contact <web:server_admin/>.</p>
    <p>Error Details:<br/>
        <web:error_notes/>
    </p>

AUTHOR

Matt Sergeant, matt@axkit.com

Original code by Steve Willer, steve@willer.cc

LICENSE

This software is Copyright 2001 AxKit.com Ltd.

You may use or redistribute this software under the terms of either the Perl Artistic License, or the GPL version 2.0 or higher.

cpanm AxKit::XSP::WebUtils

perl -MCPAN -e shell
install AxKit::XSP::WebUtils