Portal Registration

The portal_registration tool is an action provider and provides one key action in Plone: joining. Clicking this link will open the join form. By default, any user (anonymous included) that hasn't already logged in can click this link to join.

When users register using the join form, they'll get two simple options for a Plone site: to either validate e-mail or not validate it. The only true way to validate an e-mail is to send an e-mail to the address and see if an appropriate response is returned. By default, e-mail validation is turned off; that is, when a user registers, by default they provide their name, e-mail, and password in Plone. They can then log in and use the site as usual. This is the form you've seen in Chapter 3. If e-mail validation is turned on, however, then users can give only a name, username, and e-mail, as shown in Figure 9-8.

Figure 9-8. Registering a user with e-mail validation turned on

After clicking the link in the e-mail, they'll then be taken to a login screen, and the registration process can continue as normal.

To enable validation in the Plone interface, click plone setup and select Portal Settings. Under Password Policy, select Generate and e-mail members' initial password and click Save to commit the changes.

If you'd like to view or edit the e-mail users get, then you can edit the page template that generates it. You can find the template by clicking plone_skins, clicking plone_templates, and then clicking registered_notify_template.

*Begin Sidebar*

If you want to add any other actions for users, before they join, this is the best place to add them. For example, if you wanted to add a page that outlined a privacy policy, this could be a good place. To do this, first add the page and all the information you want to contain in that policy. It would make sense to make the ID of the page something useful, such as privacy.html, and put it in the root of your Plone site.

In the ZMI, go to portal_registration and add a new action with the following information:

Name: Privacy
Id: privacy
Action: string: ${portal_url}/privacy.html
Condition: not: member
Permission: Add portal member
Category: user
Visible: selected

You'll now get the privacy link to your privacy page, if aren't logged in. By making the category user, you'll ensure it appears in the personal bar.

*End Sidebar*

Portal Member Data

The portal_memberdata tool holds the member data for each user. A Plone user has a series of options, such as skins, the time last logged in, What You See Is What You Get (WYSIWYG) editor, and so on. When a user joins a site, a default record in portal_memberdata is created. You set the actual properties created in that record in this tool; click portal_memberdata, and select Properties to see the default set of properties. In Plone these are the following:

• e-mail: This is the user's e-mail address.
• portal_skin: This is deprecated; ignore this property.
• listed: Show this user in the Members directory (Boolean). By default this is enabled.
• login_time: This is the date the user logged in for this session.
• last_login_time: This is the date of the last time the user logged in.
• fullname: This is a user's full name.
• error_log_update: This is used by the error log form; ignore this property.
• formtooltips: In old versions of Plone, there were options for displaying form help. This is now no longer relevant, so ignore it.
• visible_ids: This shows the IDs (or names) for objects. By enabling this, the first field on the edit form for each content type is Name, and by changing this users can rename objects. By default this is enabled.
• wysiwyg_editor: This is the editor to use in forms.

You can add or remove items from this list using the Zope interface. However, adding or removing elements from here doesn't automatically make the user interface form that users actually edit. In Chapter 3 you saw that by clicking my preferences, users can access and alter most of these properties. If you want to alter these preferences, then you'll have to customize that form. The values given for these fields are the default values for a newly registered user; for example, by default all members are listed in the Members tab, unless users explicitly decide otherwise.

So, for example, if you wanted all members not to be listed on the search by default, then you need to change the setting in this form. In the portal_memberdata form, find the listed property and uncheck the value in the form. Then click Save Changes, and all new users will no longer be selected.

The portal_groupdata tool contains the corresponding data for groups. The default properties for a group are as follows:

• title: A title for the group
• description: A description for the group
• email: An e-mail address
• listed: Whether to list the group to users

These tools store the user and group data on these tools and not in the main acl_users folder. If you want to move user information between Plone servers, then you'll need to move these tools as well; just moving the acl_users folder isn't enough. You can do this by importing and exporting these tools; however, before you import into the new Plone site, you must delete the existing tool, or an error will be raised.

Portal Membership

The portal_membership tool handles a few more properties; specifically, it matches the member data with the members. Accessing portal_membership from the ZMI gives a large number of options; the following are the most important:

• Set members folder: This is the folder to put member folders into. This folder must exist. By default this is Member.
• Control creation of member areas: By default, a member area for each user is created when joining. That creation is optional, however. Uncheck Turn folder creation off to disable this. The default is that it's on.

Under the Actions tab you'll find a whole series of actions that relate to users when they're logged in, such my favorites, my preferences, and so on. These all have the category user so that the actions will appear in the top-right corner.

The portal_groups tool provides similar tools to portal_membership, but for groups. Likewise, when a group is created, a group workspace is created where all members of that group can add and edit content.

Useful APIs

The portal_membership tool has one of most commonly used set of API functions. Often you'll want to find out key information such as the currently logged in user, whether the user is anonymous, and so on. The portal_membership tool provides you with these methods; the following are some of the most important:

• isAnonymousUser(): This returns true if the user is anonymous.
• getAuthenticatedMember(): This returns the currently logged-in user wrapped with portal_metadata properties. If no user is logged in, it returns a special nobody user with null mappings for portal_metadata properties.
• listMemberIds(): This returns the IDs for all the users.
• listMembers(): This returns all the user objects.
• getMemberById(id): This returns the user object for a given ID.
• getHomeFolder(id=None): This returns the home folder for a given ID. The ID is optional and if not provided gives the current member's home folder.
• getHomeUrl(id=None): This returns a URL to the member's home folder. The ID is optional and if not provided gives the current members home folder's URL.

The user returned by these functions is 'wrapped� in the data from the portal_memberdata tool so that the properties are attributes of the user object. So, for example, the following is a little Script (Python) object to get the e-mail address for the user Bob:

##parameters=
u = context.portal_membership.getMemberById("andy")
return u.email

Cookie Authentication

By default Plone uses cookie authentication for its users, meaning that users must have cookies turned on in their browser to log in. This authentication is provided in a Plone site by the cookie_authentication object, which contains the necessary functionality for users to log in. If you really want to use Hypertext Transfer Protocol (HTTP) authentication, then you can simply remove this object; however, I really don't recommend it, because HTTP authentication isn't good for most sites.

This object provides the following items that you can edit from the ZMI:

• Authentication cookie name: This is the name of the cookie that will be used to persist user authentication. It does this by persisting a token for the user, which preserves a user's login. The default is __ac.
• User name form variable: This is the name of the variable in the login form that will contain the username. The default is __ac_name.
• User password form variable: This is the name of the variable in the login form that will contain the password. The default is __ac_password.
• User name persistence form variable: This is the name of the variable in the login form that will contain the persistence token. The default is __ac_persistent.
• Login page ID: If a user needs to log in, this is the page that they will be sent to in order to complete the login. The default is require_login.
• Logout page ID: If a user is to be logged out, then they will be sent to a nice page with a message. The page is this ID. The default is logged_out.
• Failed authorization page ID: When the authorization fails, this is the page that will show. By default, this is blank, as Plone does something different.
• Use cookie paths to limit scope: This sets the cookie to be local to the current folder and all folders below this. Leave this at the default of blank so that you'll authenticate for the entire site, regardless of where you actually click login.

To change the cookie that's being used, rather than the default, just change the value in this form and click Save. However, let me warn you that if you change the name of the cookie, all the existing cookies on your users' computers will be ignored, and they'll all have to log in again. If you wanted a different login page, then you could either customize the require_login page template or change the value of that variable.

The Actual User Folder

You can get access to the actual user folder for a Plone site by clicking the acl_users folder in the ZMI. This opens the Group User Folder (GRUF) interface, which gives you a variety of options.

The GRUF interface is actually quite similar to the user options you have through the Plone control panel. You can add and edit users and groups through a pretty straightforward interface. Clicking Users and Groups will allow you to edit these items. If you click the Contents tab, you'll get a choice of users or groups; click Users and then click acl_users. Finally you'll get to the actual user folder for a user. This looks like the standard user folder. You'll see a list of users, and to edit a user, you just click the username, as shown in Figure 9-9.

Figure 9-9. Editing the user record

From here you can alter a user's password or the roles. You'll note that at this point the group Management is actually represented as a role to ensure that no name collisions occur. The name is mangled to be group_Management. If you wanted to make this user a member of this group, then you could do so here. There isn't much you can do here, though, that you can't do at the highest level, so I wouldn't go down to this level unless you have to do something such as change the password or set a domain.