[Zope-Checkins] CVS: Zope/lib/python/Products/Sessions/help - SessionInterfaces.py:1.3 browser-add.stx:1.6 browser-change.stx:1.5 session-add.stx:1.6 session-change.stx:1.5 sessionapi-prog.stx:1.5
Chris McDonough
chrism@zope.com
Sat, 17 Nov 2001 11:07:42 -0500
Update of /cvs-repository/Zope/lib/python/Products/Sessions/help
In directory cvs.zope.org:/tmp/cvs-serv27973/help
Modified Files:
SessionInterfaces.py browser-add.stx browser-change.stx
session-add.stx session-change.stx sessionapi-prog.stx
Log Message:
As per suggestions by Amos, I changed the terminology used by the browser id manager and session data manager. Previous to the change, browser ids were known as "tokens". I've changed this to "browser id" in the docs as well as in all API methods that used the name "token". Interfaces, permissions, and help have been updated with the changes.
=== Zope/lib/python/Products/Sessions/help/SessionInterfaces.py 1.2 => 1.3 ===
A Zope Browser Id Manager is responsible for assigning ids to site
visitors, and for servicing requests from Session Data Managers
- related to the browser token.
+ related to the browser id.
"""
def encodeUrl(self, url):
"""
- Encodes a provided URL with the current request's browser token
+ Encodes a provided URL with the current request's browser id
and returns the result. For example, the call
encodeUrl('http://foo.com/amethod') might return
'http://foo.com/amethod?_ZopeId=as9dfu0adfu0ad'.
Permission required: Access contents information
- Raises: BrowserIdManagerErr. If there is no current session token.
+ Raises: BrowserIdManagerErr. If there is no current browser id.
"""
- def getTokenKey(self):
+ def getBrowserIdName(self):
"""
Returns a string with the name of the cookie/form variable which is
used by the current browser id manager as the name to look up when
- attempting to obtain the browser token value. For example, '_ZopeId'.
+ attempting to obtain the browser id value. For example, '_ZopeId'.
Permission required: Access contents information
"""
- def getToken(self, create=1):
+ def getBrowserId(self, create=1):
"""
- If create=0, returns a the current browser token or None if there
- is no browser token associated with the current request. If create=1,
- returns the current browser token or a newly-created browser token if
- there is no browser token associated with the current request. This
- method is useful in conjunction with getTokenKey if you wish to embed
- the token-key/token combination as a hidden value in a POST-based
- form. The browser token is opaque, has no business meaning, and its
- length, type, and composition are subject to change.
+ If create=0, returns a the current browser id or None if there
+ is no browser id associated with the current request. If create=1,
+ returns the current browser id or a newly-created browser id if
+ there is no browser id associated with the current request. This
+ method is useful in conjunction with getBrowserIdName if you wish to
+ embed the browser-id-name/browser-id combination as a hidden value in
+ a POST-based form. The browser id is opaque, has no business meaning,
+ and its length, type, and composition are subject to change.
Permission required: Access contents information
- Raises: BrowserIdManagerErr. If ill-formed browser token
+ Raises: BrowserIdManagerErr. If ill-formed browser id
is found in REQUEST.
"""
- def hasToken(self):
+ def hasBrowserId(self):
"""
- Returns true if there is a browser token for this request.
+ Returns true if there is a browser id for this request.
Permission required: Access contents information
"""
- def isTokenNew(self):
+ def isBrowserIdNew(self):
"""
- Returns true if browser token is 'new'. A browser token is 'new'
+ Returns true if browser id is 'new'. A browser id is 'new'
when it is first created and the client has therefore not sent it
back to the server in any request.
Permission required: Access contents information
- Raises: BrowserIdManagerErr. If there is no current browser token.
+ Raises: BrowserIdManagerErr. If there is no current browser id.
"""
- def isTokenFromForm(self):
+ def isBrowserIdFromForm(self):
"""
- Returns true if browser token comes from a form variable (query
+ Returns true if browser id comes from a form variable (query
string or post).
Permission required: Access contents information
- Raises: BrowserIdManagerErr. If there is no current browser token.
+ Raises: BrowserIdManagerErr. If there is no current browser id.
"""
- def isTokenFromCookie(self):
+ def isBrowserIdFromCookie(self):
"""
- Returns true if browser token comes from a cookie.
+ Returns true if browser id comes from a cookie.
Permission required: Access contents information
- Raises: BrowserIdManagerErr. If there is no current browser token.
+ Raises: BrowserIdManagerErr. If there is no current browser id.
"""
- def flushTokenCookie(self):
+ def flushBrowserIdCookie(self):
"""
- Deletes the token cookie from the client browser, iff the
- 'cookies' token key namespace is being used.
+ Deletes the browser id cookie from the client browser, iff the
+ 'cookies' browser id namespace is being used.
Permission required: Access contents information
Raises: BrowserIdManagerErr. If the 'cookies' namespace isn't
- a token key namespace at the time of the call.
+ a browser id namespace at the time of the call.
"""
class SessionDataManagerInterface(
@@ -193,7 +193,7 @@
A Zope Session Data Manager is responsible for maintaining Session
Data Objects, and for servicing requests from application code
related to Session Data Objects. It also communicates with a Browser
- Id Manager to provide information about browser tokens.
+ Id Manager to provide information about browser ids.
"""
def getBrowserIdManager(self):
"""
@@ -207,9 +207,9 @@
def getSessionData(self, create=1):
"""
Returns a Session Data Object associated with the current
- browser token. If there is no current token, and create is true,
+ browser id. If there is no current browser id, and create is true,
returns a new Session Data Object. If there is no current
- token and create is false, returns None.
+ browser id and create is false, returns None.
Permission required: Access session data
"""
@@ -217,7 +217,7 @@
def hasSessionData(self):
"""
Returns true if a Session Data Object associated with the
- current browser token is found in the Session Data Container. Does
+ current browser id is found in the Session Data Container. Does
not create a Session Data Object if one does not exist.
Permission required: Access session data
=== Zope/lib/python/Products/Sessions/help/browser-add.stx 1.5 => 1.6 ===
- 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
- information.
-
- 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.
+ A browser id manager is an object which identifies visitors
+ to your site, even if they don't log in. Browser id managers
+ are part of the Zope sessioning machinery.
Form options available are:
- id -- you cannot choose an 'id' for your browser id manager.
+ 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
later release.
- title -- the browser id manager title.
+ Title -- the browser id manager title.
- session token key -- the cookie name and/or form variable name
+ Look for browser id name in -- 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.
+ variable with a browser id 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).
+ Browser id location -- select from one of the available
+ lookup ordering schemes involving cookies and forms
- cookie path -- this is the 'path' element which should be sent
+ 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
http://home.netscape.com/newsref/std/cookie_spec.html.
- cookie domain -- this is the "domain" element which should be
- sent in the session token cookie. For more information, see
+ Cookie domain -- this is the "domain" element which should be
+ sent in the browser id cookie. For more information, see
the Netscape Cookie specification at
http://home.netscape.com/newsref/std/cookie_spec.html.
Leaving this form element blank results in no domain element
@@ -58,12 +38,12 @@
value you enter must have at least two dots (as per the cookie
spec).
- cookie lifetime in days -- browser id cookies sent to browsers
+ 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
+ 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
@@ -81,24 +61,18 @@
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.
+ If you've got special needs, you may want to instantiate more than
+ one browser id manager. In its default configuration, Zope will not
+ allow you to create a browser id manager if one is installed in the
+ root or 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
+ delete the root browser id manager, then you need to place
+ additional browser id managers in the most deeply-nested containers
+ first, working your way out towards the root, finally replacing
+ the root browser id manager if desired.
See Also
=== Zope/lib/python/Products/Sessions/help/browser-change.stx 1.4 => 1.5 ===
Form options available are:
- title -- the browser id manager title.
+ Title -- the browser id manager title.
- session token key -- the cookie name and/or form variable name
+ Browser id name -- 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.
+ variable with a browser id 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).
+ Look for browser id name in -- select from one of the available
+ lookup ordering schemes involving cookies and forms
- cookie path -- this is the 'path' element which should be sent
+ 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
http://home.netscape.com/newsref/std/cookie_spec.html.
- cookie domain -- this is the "domain" element which should be
- sent in the session token cookie. For more information, see
+ Cookie domain -- this is the "domain" element which should be
+ sent in the browser id cookie. For more information, see
the Netscape Cookie specification at
http://home.netscape.com/newsref/std/cookie_spec.html.
Leaving this form element blank results in no domain element
@@ -35,12 +27,12 @@
value you enter must have at least two dots (as per the cookie
spec).
- cookie lifetime in days -- browser id cookies sent to browsers
+ 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
+ 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
=== Zope/lib/python/Products/Sessions/help/session-add.stx 1.5 => 1.6 ===
- 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.
+ A Zope Session Data Manager is responsible for maintaining a
+ relationship between session data objects and Zope browser ids.
+ It is part of the Zope sessioning machinery. Programmers will
+ sometimes interact with a session data manager in order to obtain
+ information about session data.
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).
+ object named "browser_id_manager" as a browser id manager.
Choose "Session Data Manager" within the container you wish to
house the session data manager from the "Add" dropdown box in
@@ -27,7 +27,7 @@
/temp_folder/transient_container in a default Zope installation.
place SESSION in REQUEST as --
- If set, the REQUEST variable will be updated with the session
+ If set, the REQUEST variable will be populated with the session
object, stored as the given name (default is 'SESSION')
After reviewing and changing these options, click the "Add"
=== Zope/lib/python/Products/Sessions/help/session-change.stx 1.4 => 1.5 ===
place SESSION in REQUEST as --
- If set, the REQUEST variable will be updated with the session
+ If set, the REQUEST variable will be populated with the session
object, stored as the given name (default is 'SESSION')
After reviewing and changing these options, click the "Change"
=== Zope/lib/python/Products/Sessions/help/sessionapi-prog.stx 1.4 => 1.5 ===
-
Overview
- Developers generally *not* interact directly with a Session Data
- Manager instance in order to make use of sessioning in Zope.
-
- All of the methods implemented by Session Data Managers, and
- Browser Id Managers are fully documented in the
- Session API in the "See Also" section below.
-
+ Sessions allow you to maintain state associated with anonymous
+ users between requests. A session is a temporary "scratch" area
+ in which you can store information related to a site visitor.
+ A "session" ends when a visitor who begins a session neglects to
+ revisit your site in some number of minutes.
+
+ Usage
+
+ Developers will usually interact with the SESSION object stored
+ in REQUEST in order to perform session-related tasks.
+
+ More infrequently, developers will interact directly with
+ Browser Id Manager and Session Data Manager objects.
+
Common Programming
- Generally, instead of directly interacting with the session data
- manager, you use it's built in traversal feature to put a SESSION
- object in the REQUEST. This is simple, and fairly intuitive.
+ In order to manipulate session data, you interact with the
+ REQUEST.SESSION object.
+
For example, in DTML you might::
<dtml-with SESSION mapping>
@@ -26,12 +32,12 @@
<dtml-var SESSION>
This would print the cart object in the session, or the entire SESSION
- object. You could set an
- object in the session similarly to how you set it in the REQUEST::
+ object. You could set an object in the session similarly to how you
+ set it in the REQUEST::
<dtml-call expr="SESSION.set('cart','this is really more of a wagon')">
- You adjust the name of the SESSION object in the management screens
+ You may change the name of the SESSION object in the management screens
for the session data object. You can do more complex operations on
SESSION data with python scripts, e.g.::
@@ -42,18 +48,11 @@
session['cart'] = cart # force a save back to the session
-
- In general, it is better to put manipulation of data in the session in
- a python script than it is to do it via DTML or a page template; while
- the latter is possible, it would be far better to simply place a session
- management call at the top of any page which requires manipulation of
- session data.
-
Tips
- Keep in mind that SESSION objects (Which are really Transient Objects)
- are basically dictionaries; if you wish to iterate through them in the
- context of a DTML-IN expression, you should use something like::
+ Keep in mind that SESSION objects are a lot like dictionaries; if
+ you wish to iterate through them in the context of a dtml-in expression,
+ you should use something like::
<dtml-in expr="SESSION.items()">
<dtml-var sequence-key>: <dtml-var sequence-item>