## session

    Object
       |
       +--session

SUMMARY: Constructor | Properties | Methods | DETAIL: Constructor | Properties | Methods

Properties Summary
`String` | `_id` The unique identifier for a session object (session cookie).
`String` | `cookie` The cookie value of a session.
`HopObject` | `data` Object providing space for run-time user data (user cache).
`Date` | `lastModified` The date a session was created or a login or logout was performed the last time.
`String` | `message` If set, the message will be available during the next request as res.message
`User` | `user` A reference to the user object associated with the current session.

Methods Summary
`Date` | `lastActive()` A date object representing the time this user's session was last active.
`Boolean` | `login(<User> user,<String> password)` Logs in a user defined by its name and a password phrase, or by directly passing a HopObject.
`Date` | `onSince()` A date object representing the time a user's session was started.
`void` | `touch()` Refreshes the user's session.

Properties Detail

### _id

    String _id

The unique identifier for a session object (session cookie).
Contains the unique identifier of the current session, which is equivalent to the value stored in the HopSession-cookie on the client side.
This property is read-only.
Example:

     res.writeln(session._id);
     1fcca129764400@eefa22dfab

### cookie

    String cookie

The cookie value of a session.
Contains the unique identifier of the current session, which is equivalent to the value stored in the HopSession-cookie on the client side.
This property is read-only.
Example:

     res.writeln(session.cookie);
     1fcca129764400@eefa22dfab

### data

    HopObject data

Object providing space for run-time user data (user cache).
This property of the SessionObject offers the possibility to store arbitrary data within the current user session. Note, that this can just be used as a temporary storage, since sessions are not stored persistently within Helma, and are generally lost when the application is restarted.
Example:

     session.data.lastclick = new Date();
     session.data.language = "en";

     res.write(session.data);
     TransientNode session

     for (var p in session.data)
       res.writeln(p + ": " + session.data[p]);
     lastclick: Fri Jul 12 14:08:20 CEST 2002
     language: en

     res.write(session.data.lastclick);
     Fri Jul 12 14:08:20 CEST 2002

     res.write(session.data["language"]);
     en

### lastModified

    Date lastModified

The date a session was created or a login or logout was performed the last time.
This is a convenience property to acknowledge that pages are often dependent on the login status and must be re-rendered when a user has logged in, logged out or is running with a new session.
Contains the timestamp of when the associated client started the session, or logged in, or logged out the last time, whichever happened most recently.
This property is read- and write-able.
Example:

     if (session.lastModified < this.modifytime)
       renderSkin("main");
     else
       res.notModified();

### message

    String message

If set, the message will be available during the next request as res.message

### user

    User user

A reference to the user object associated with the current session.
Contains a reference to the UserObject associated with this session. This property is null if the client has not been logged in yet, or has already been logged out. Checking this for being unequal to null is the usual way to check whether a client is logged in or not. This property is read-only, but can be set through the method session.login(User usr).
Example:

     session.login("tobi", "mumbl3");
     res.write(session.user);
     HopObject tobi

     res.write(session.user.registered);
     Thu Jun 28 17:25:33 CEST 2001

     res.write(session.user["url"]);
     http://helma.org

Method Detail

### lastActive

    Date lastActive()

A date object representing the time this user's session was last active.
Contains the timestamp of the last web request, that has been submitted by that client. This property is read-only, but can be set to the current time through session.touch().
For new sessions, if the session represents a registered user the result equals the date the user was logged in the last time; otherwise the result equals the current date.
This property is read-only
Example:

     res.write(session.lastActive())
     Thu Nov 02 16:12:13 GMT+01:00 2000

Returns:

Date of last request by this user

### login

    Boolean login(<User> user,<String> password)

Logs in a user defined by its name and a password phrase, or by directly passing a HopObject.
There are two variants of session.login():
If called with one HopObject argument, the session is associated with the user represented by the HopObject.
If called with two string arguments, it returns true if the user name / password pair matches the stored values in the database and false otherwise.
Associates the passed User to that session, i.e. logs the client in as that User. The property user of the session object will refer to the User.
Example:

     var login = session.login("tobi", "mumbl3");
     if (login)
       res.write("Welcome back, " + session.user.name + "!");
     else
       res.write("Oops, please try again...");
     Welcome back, tobi!

Parameters:

`user` - as User object to be logged in

`user` - as String, the username of the user to be checked

`password` - as String, if the first parameter is a username

Returns:

Boolean true if the user was logged in, otherwise false

### onSince

    Date onSince()

A date object representing the time a user's session was started.
This property is read-only.
Example:

     res.write(session.onSince());
     Fri Aug 10 16:36:36 GMT+02:00 2001

Returns:

Date when the current session was started.

### touch

    void touch()

Refreshes the user's session.
The session's expiration date is set to the current date plus session timeout. This also happens automatically when a user request is sent to Helma.
The lastActive property will be set to the current timestamp. Useful to artificially avoid a session timeout.
Example:

     res.writeln(session.lastActive);
     Fri Jul 12 14:40:20 CEST 2002

     session.touch();

     res.writeln(session.lastActive);
     Fri Jul 12 14:55:20 CEST 2002

SUMMARY: Constructor | Properties | Methods | DETAIL: Constructor | Properties | Methods

Documentation generated by JSDoc on Thu Apr 5 01:59:00 2007