NAME

AxKit::XSP::BasicSession - Session wrapper tag library for AxKit eXtesible Server Pages.

SYNOPSIS

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

    <xsp:page
         language="Perl"
         xmlns:xsp="http://apache.org/xsp/core/v1"
         xmlns:session="http://www.axkit.org/2002/XSP/BasicSession"
    >

And add this taglib to AxKit (via httpd.conf or .htaccess):

    AxAddXSPTaglib AxKit::XSP::BasicSession

You'll also need to set up Apache::AxKit::Plugin::BasicSession, as described on its pod page.

DESCRIPTION

The XSP session: taglib provides basic session object operations to XSP, using the Cocoon2 Session taglib specification. I tried to stay as close to the Cocoon2 specification as possible, for compatibility reasons. However, there are some tags that either didn't make sense to implement, or I augmented since I was there.

Keep in mind, that currently this taglib does not actually create or fetch your session for you. That has to happen outside this taglib - see Apache::AxKit::Plugin::BasicSession. This module relies on the $r->pnotes() table for passing the session object around.

Special thanks go out to Kip Hampton for creating AxKit::XSP::Sendmail, from which I created AxKit::XSP::BasicSession.

Tag Reference

<session:get-attribute>

This is the most used tag. It accepts either an attribute or child node called 'name'. The value passed in 'name' is used as the key to retrieve data from the session object.

<session:set-attribute>

Similar to :get-attribute, this tag will set an attribute. It accepts an additional parameter (as an attribute or child node) called 'value'. You can intermix attribute and child nodes for either parameter, so its pretty flexible. NOTE: this is different from Cocoon2, where the value is a child text node only.

<session:get-id>

Gets the SessionID used for the current session. This value is read-only.

<session:get-creation-time>

Returns the time the current session was created. Cocoon2's way of handling this is pretty wierd, so I didn't implement it 100% to spec. This tag takes an optional parameter of 'as', which allows you to choose your date format. Your only options are "string" and "long", where the string output is a human-readable string representation (e.g. "Fri Nov 23 15:38:13 PST 2001"). "long", contrary to what you would expect, is the number of seconds since epoch. The Cocoon2 spec makes "long" the default, while mine specifies "string" as default.

<session:get-last-accessed-time>

Similar to :get-creation-time, except it returns the time since this session was last accessed (duh).

<session:remove-attribute>

Removes an attribute from the session object. Accepts either an attribute or child node called 'name' which indicates which session attribute to remove.

<session:invalidate>

Invalidates, or permanently removes, the current session from the datastore. Not all Apache::Session implementations support this, but it works just beautifully under Apache::Session::File (which is what I used for my testing).

<session:exists name="foo"/>

Returns a boolean value representing whether the indicated session key exists, even if it has an empty or false value.

<session:enumerate/>

Returns an enumerated list of the session keys present. It's output is something like the following:

  <session-keys>
    <key id="1">
      <name>foo</name>
      <value>bar</name>
    </key>
    ...
  </session-keys>

<session:count/>

Returns the number of session keys that have been set for this particular session.

<session:is-new>

This tag returns a boolean value indicating if this session is a newly-created session.

<session:if name="foo"></session:if>

Executes the code contained within the block if the named key's value is true. You can optionally supply the attribute "value" if you want to evaluate the value of a key against an exact string.

This tag, as well as all the other similar tags mentioned below can be changed to "unless" to perform the exact opposite (ala Perl's "unless"). All options must be supplied as attributes; child elements can not be used to supply these values.

<session:if-exists name="foo"></session:if-exists>

Executes the code contained within the block if the named session key exists at all, regardless of it's value.

<session:if-regex name="foo" value="\w+"></session:if-regex>

Executes the code contained within the block if the named session key matches the regular expression supplied in the "value" attribute. The "value" attribute is required.

OBJECT-ORIENTED INTERFACE

There are times when using this module that you might wish to access the BasicSession methods directly from Perl, rather than using the XSP taglib interfaces. You may be within an <xsp:logic> block and not want the verbosity of a full XML tag, or you might have a heterogenous site with some XSP, some Perl providers. Whatever the reason, the OO interface to BasicSession will work for you.

Simply create a new BasicSession object by invoking the new constructor on it:

  my $bs = new AxKit::XSP::BasicSession;

Once you have this object created, you can call any of the standard taglib methods by using the taglib name, transposing any "-" characters to underscores.

The following is a list of the various methods available:

get_attribute($name)

get_id()

get_creation_time([$as, [$format]])

get_last_accessed_time([$as, [$format]])

set_attribute($name, $value)

remove_attribute($name)

is_new($name)

invalidate()

if_exists($name)

unless_exists($name)

if_regex($name, $regex)

unless_regex($name, $regex)

ifkey($name, $value)

unlesskey($name, $value)

enumerate()

keyexists($name)

count()

EXAMPLE

  <session:invalidate/>
  SessionID: <xsp:expr><session:get-id/></xsp:expr>
  Creation Time: <xsp:expr><session:get-creation-time/></xsp:expr>
    (Unix Epoch) <xsp:expr><session:get-creation-time as="long"/></xsp:expr>
  <session:set-attribute name="foo" value="bar"/>
  <session:set-attribute name="baz">
    <session:value>boo</session:value>
  </session:set-attribute>
  <session:set-attribute>
    <session:name>baa</session:name>
    <session:value>bob</session:value>
  </session:set-attribute>
  <session:remove-attribute name="foo"/>

ERRORS

To tell you the truth, I haven't tested this enough to know what happens when it fails. I'll update this if any glaring problems are found.

AUTHOR

Michael A Nachbaur, mike@nachbaur.com

COPYRIGHT

Copyright (c) 2001-2004 Michael A Nachbaur. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

AxKit, Apache::Session, Apache::AxKit::Plugin::BasicSession

cpanm AxKit::XSP::BasicSession

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