[Zope-CVS] CVS: Products/Sessions/help - browser-add.stx:1.1 session-add.stx:1.1
Matthew T. Kromer
Mon, 5 Nov 2001 16:15:48 -0500
Update of /cvs-repository/Products/Sessions/help
In directory cvs.zope.org:/tmp/cvs-serv19229/help
=== Added File Products/Sessions/help/browser-add.stx ===
Browser Id Manager - Add
Though you'll likely interact mostly with "session data manager"
objects while you develop session-aware code, before you can
instantiate a session data manager object, you must instantiate a
"browser id manager." A browser id manager is an object which
doles out and otherwise manages session tokens. All session
data managers need to talk to a browser id manager to get token
You can add an initial browser id manager anywhere in your Zope
tree, but chances are you'll want to create it in your root
folder if you don't anticipate the need for multiple browser id
managers. In other words, just put one browser id manager in
the root Folder unless you have special needs. In the container
of your choosing, select "Browser Id Manager" from the add
dropdown list in the Zope management interface.
Form options available are:
id -- you cannot choose an 'id' for your browser id manager.
It must always be "browser_id_manager". Additionally, you cannot
rename a browser id manager. This is required in the current
implementation so that session data managers can find browser
id managers via Zope acquisition. This may be changed in a
title -- the browser id manager title.
session token key -- the cookie name and/or form variable name
used for this browser id manager instance. This will be the
name looked up in the 'cookies' or 'form' REQUEST namespaces
when the browser id manager attempts to find a cookie or form
variable with a session token in it.
token key search namespaces -- choose a "priority" for each
token key namespace. A priority of "1" is highest. For
instance, setting 'cookies' to '1' and 'form vars' to '2'
means that the browser id manager checks for cookies with a
session token first, then form variables second. Choosing
"off" for either 'cookies' or 'form vars' entirely excludes
that namespace from being searched for a session token. The
namepace identifiers ('cookies' and 'form') refer to the
REQUEST namespaces searched for the token key
(ie. REQUEST.cookies, REQUEST.form).
cookie path -- this is the 'path' element which should be sent
in the session token cookie. For more information, see the
Netscape Cookie specification at
cookie domain -- this is the "domain" element which should be
sent in the session token cookie. For more information, see
the Netscape Cookie specification at
Leaving this form element blank results in no domain element
in the cookie. If you change the cookie domain here, the
value you enter must have at least two dots (as per the cookie
cookie lifetime in days -- browser id cookies sent to browsers
will last this many days on a remote system before expiring if
this value is set. If this value is 0, cookies will persist
on client browsers for only as long as the browser is open.
only send cookie over https -- if this flag is set, only send
cookies to remote browsers if they're communicating with us
over https. The browser id cookie sent under this
circumstance will also have the 'secure' flag set in it, which
the remote browser should interpret as a request to refrain
from sending the cookie back to the server over an insecure
(non-https) connection. NOTE: In the case you wish to share
browser id cookies between https and non-https connections
from the same browser, do not set this flag.
After reviewing and changing these options, click the "Add"
button to instantiate a browser id manager.
You can manage a browser id manager by visiting it in the
management interface. In addition to adjusting the settings you
chose at add-time, you can additionally turn a browser id
manager "off" via this management interface, which will cause
session data managers to ignore it when attempting to acquire a
browser id manager. Session data managers will instead acquire
a browser id manager nearer the root of the ZODB.
Instantiating Multiple Browser Id Managers (Optional)
If you've got special needs, you may want to instantiate more
than one browser id manager. Having multiple browser id
managers may be useful in cases where you have a "secure"
section of a site and an "insecure" section of a site, each
using a different browser id manager with respectively
restrictive security settings. Some special considerations are
required for this setup.
Once you've instantiated one browser id manager, you will not be
able to instantiate another browser id manager in a place where
the new browser id manager can acquire the original browser id
manager via its containment path (for programmers: the session
id manager's class' Zope __replaceable__ property is set to
UNIQUE). This means, practically, that if you wish to have
multiple browser id managers, you need to carefully think about
where they should go, and then you need to place them in the
most deeply-nested containers first, working your way out
towards the root.
=== Added File Products/Sessions/help/session-add.stx ===
Session Data Manager - Add
After instantiating at least one browser id manager, it's
possible to instantiate a session data manager. You'll need to
do this in order to use session tracking.
You can place a session data manager in any Zope container,as
long as a browser id manager object can be acquired from that
container. The session data manager will use the first acquired
browser id manager which is active (ie. it will use any acquired
browser id manager that has not been been "turned off" via its
Zope management interface).
Choose "Session Data Manager" within the container you wish to
house the session data manager from the "Add" dropdown box in
the Zope management interface.
The session data manager add form displays these options:
id -- choose an id for the session data manager
title -- choose a title for the session data manager
transient object container path --
the path in Zope to a transient object container which will
store the actual session data. This path is
/temp_folder/transient_container in a default Zope installation.
automatic SESSION placement in REQUEST object --
check this option to have a SESSION object automatically
inserted into the REQUEST object, corresponding to the
current browser's session.
After reviewing and changing these options, click the "Add"
button to instantiate a session data manager.
You can manage a session data manager by visiting it in the
management interface. You may change all options available
during the add process by doing this.