A Quick Introduction

User Manager is the core of LunpaCMS' ability to handle user credentials and basic login/logout functionality. When a user visits the site, a session id is created. Sessions NOT ASSOCIATED WITH A LOGIN are deleted when they are 3 days old automatically. Sessions for deleted users are automatically deleted as well.

How to Add Extra Columns to the User table

A common requirement is to add Extra Site Specific Fields to User Manager. To achieve this, do the following:

1. Create a routine to return a hash for a list of fields for adding users and updating users. Overloading the routine is quite easy for updates and add. **Add kofc_user_db_hash as an example**
2. Edit htdocs//html/templates/profile_form.template and profile_form-admin.template to accommodate the new field(s).
3. Add your fields to the users column
4. Add a map to activate usermanager using the new fields. LOCAL_USERMANAGER_ADD_DB_HASH with a value such as Library_pccc::pccc_user_db_hash($FORM, add=>1, admin=>$admin)
   To update the new fields. LOCAL_USERMANAGER_UPDATE_DB_HASH with a value such as Library_pccc::pccc_user_db_hash($FORM, update=>1, admin=>$admin)

Q: Why is there a routine for updates or adding?
A: The separation allows you to track some data only upon registration such as IP Address or Date of Creation.

Other Items in User Manager

Tracking the user's last visit
LOCAL_USERMANAGER_TRACK_LAST_VISIT

Want to enable user account deletion?
LOCAL_USERMANAGER_ALLOW_USER_DELETION to a value of 1.

Need to Perform extra tasks when a user logs out?
LOCAL_USERMANAGER_POST_USER_LOGOUT

Need to Disable certain users?
LOCAL_USERMANAGER_USER_SITE_LOGON_DISABLED containing a semi-colon separated list of usernames

Need to Disable creating users?
Set map LOCAL_USERMANAGER_USER_CREATE_DISABLED to 1 and create a template called profile_form-disabled.template to explain why creation is disabled.

Want to make passwords case insensitive?
Set LOCAL_USERMANAGER_SINGLE_CASE_ALL_PASSWORDS to a value of 1
NOTE: This feature is likely not completed because AuthDBI needs increased functionality to support the work. See note 30573.

Need to stop automated registrations?
Set LOCAL_USERMANAGER_CAPTCHA_ENABLED to a value of 1, and add a :::CAPTCHA::: tag to the profile_form-user template

Need to customize the view when asking for the old password?
Set LOCAL_USERMANAGER_OLD_PASSWORD_TAG

Need to change the time a password reset token will last?
Set LOCAL_USERMANAGER_LOST_PASSWORD_TOKEN_TIMEOUT

Need to Perform Extra Tasks when a user is deleted?
When a user is deleted, only the record in the users table is removed by default. If you want to do additional tasks, there are hooks to achieve this. Create a routine that performs the functions you want to achieve when a user is deleted, and save the routine name in LOCAL_USERMANAGER_POST_DELETE_USER.

Need to Perform Extra Tasks when a user is renamed
LOCAL_USERMANAGER_POST_RENAME_USER

Need to Perform Extra Tasks when a user is updated
LOCAL_USERMANAGER_POST_UPDATE_USER

Need to Perform Extra Tasks when a user is added
LOCAL_USERMANAGER_POST_ADD_USER

Need to Perform Extra Tasks when a user logs out
LOCAL_USERMANAGER_POST_USER_LOGOUT

Need to notify users when their password or email address changes
LOCAL_USERMANAGER_ACCOUNT_CHANGE_NOTICES

Want to require users to confirm their email address after registration?

1. Set map LOCAL_USERMANAGER_CONFIRM_EMAIL to 1
2. Create an email address for donotreply@<map_LOCAL_DOMAIN>
3. Modify email_confirmation_request.template as needed

Need to Check Form Data when Registering?
User Manager only checks by default for validity with the username, first and last name, email_address and captcha (if enabled).
To check other form data, create a function called check_user_profile_form_data in your local library
For example, if you have select for year, month and day for birthday and want to make sure users are claiming to be older than 13, you could add these routines:

sub check_user_profile_form_data {
  #THIS IS CALLED AFTER THE PERLCMS USER PROFILE FORM DATA CHECK
  my ($FORM, %params) = @_;

  #THE DATE OF BIRTH IN THE FORM IS NOT ONE ENTRY - HERE WE RECOMBINE IT
  $FORM->{'date_of_birth'} = "$FORM->{'dob_year'}-$FORM->{'dob_month'}-$FORM->{'dob_day'}";

  $FORM->{'date_of_birth'} = &Library_pccc::check_birth_date($FORM, date_of_birth=>$FORM->{'date_of_birth'}, check_back=>\$FORM->{'check_back'});
}

sub check_birth_date {
  my ($FORM, %params) = @_;
  my ($age_limit);

  $age_limit = 13;

  #IF THEY HAVE NONE IN THE BIRTHDAY AND THEY HAVE DIGITS, THEN IT IS A PARTIAL ENTRY AND NEEDS TO BE FLAGGED
  if ($params{'date_of_birth'} =~ /\d/ and $params{'date_of_birth'} =~ /none/i) {
    ${$params{'check_back'}} .= "<li>There is an error in your date of birth. Please select a day, month & year.</li>";
  } elsif (lc($params{'date_of_birth'}) eq 'none-none-none') {
    $params{'date_of_birth'} = '';
  } else {
    # DAY, MONTH, AND YEAR SELECTED. CHECK IF THE USER IS THIRTEEN OR MORE
    unless (&Library_pccc::is_over_than_given_year($FORM, year=>$age_limit, date=>$params{'date_of_birth'})) {
      ${$params{'check_back'}} .= "<li>You must be over $age_limit years of age to register.</li>";
    }
  }

  return $params{'date_of_birth'};
}

sub is_over_than_given_year {
  my ($FORM, %params) = @_;
  my ($query, $rv, $sth, $rowhash);

  $params{'year'} || return 0;
  $params{'date'} || return 0;

  $params{'year'} = int($params{'year'}) + 1;

  $query = "SELECT ? + interval ? year <= current_date() as old_enough";
  ($rv, $sth) = &Library_global::do_standard_query($query, $Library_global::dbh, $params{'date'}, $params{'year'});
  if ($rv > 0) {
    $rowhash = &Library_global::get_rowhash($sth);
  }
  &Library_global::finish($sth);

  return $rowhash->{'old_enough'};
}


Need to track user's last visit?
Set LOCAL_USERMANAGER_TRACK_LAST_VISIT to 'Library_phw::update_user_last_visited', and create a function update_user_last_visited in the local library:

sub update_user_last_visited {
  my ($FORM, %params) = @_;
  my ($rv, $sth, $query);

  $params{'user_id'} = int($params{'user_id'});
  $params{'user_id'} || return;

  #warn "DEBUG: updating user last visited - $params{'user_id'}\n";
  $query = "REPLACE into users_last_visited (user_id, last_visit) values (?,now())";
  ($rv, $sth) = &Library_global::do_standard_query($query, $Library_global::dbh, $params{'user_id'});

  return ($rv > 0);
}

Invitations

To invite a new user from the admin menu, click "User Manager", and then "Invite a New User". You can then enter the invitee's name, email, and any other information. An invitation will be automatically sent to their email address, asking them to confirm their membership. The invitation will expire 7 days from when it was sent. This functionality requires the following configuration:

• LOCAL_USERMANAGER_SYSTEM_EMAIL map - set this to the email address that user invitations will be sent from
• email_invite_request.template template - this template contains the content of the invitation email

Auto-Generating Passwords

When an administrator creates a new user, it is possible to automatically generate a new password and send an email to that user. To enable this functionality, set the LOCAL_USERMANAGER_ALLOW_AUTOGENERATED_PASSWORDS map to 1. When an administrator is creating a new user, the :::auto_generate_password_checkbox::: on the profile form template will add a checkbox to auto generate a password for the new user. The system will email email_auto_generated_password.template to that user's email address, with the tags :::full_name:::, :::user_login:::, and :::password::: filled in appropriately.

Additionally, it is possible for an admin to require a user to change their password after logging in. On the user profile form, the :::require_password_change_checkbox::: tag will add a checkbox for administrators to require a user to change their password on login. Automatically generated passwords have many disadvantages over pass phrases, so the require password change option is always set when automatically generating a password for a new user.

Mailman Integration

UserManager can be configured to call GNU Mailman functions as users edit their profile. To enable this feature for specific mailing lists, set the LOCAL_USERMANAGER_MAILING_LISTS map to a comma-separate list of mailing lists for your site.

Mailing list alterations need to be performed as the root or mailman users. To apply UserManager mailing list changes regularly, set a cronjob to execute /htdocs/local/usermanageradmin/sys/remote_mailman_update.pl --mailman-path=/path_to_mailman/bin --cnf-files "/htdocs/yourwebsite.com/yoursite-my.cnf" --databases "yourdb" --hosts "yourserver.com". This script should be run on your mailman server. If your website is hosted on a different server, you must be able to access your website's database from your mailman server.

To allow users the option of unsubscribing or changing their digest settings on a granular basis, put the :::mailing_list_settings::: tag on the user profile form. If the LOCAL_USERMANAGER_ALLOW_SECONDARY_EMAILS map is set to 1, users can configure secondary email addresses and manage their subscriptions to your mailing lists separately. This feature requires that the mailman_secondary_emails, mailman_add_secondary_email_address, and mailman_remove_secondary_email_address functions are defined in your local library.

To run a monthly audit of your website's mailing lists, set a monthly cronjob to execute /htdocs/local/usermanageradmin/sys/mailing_list_audit.pl --mailman-path=/path_to_mailman/bin --cnf-files "/htdocs/yourwebsite.com/yoursite-my.cnf" --databases "yourdb" --hosts "yourserver.com". You will receive an email every month with two columns for each mailing list: users that should be on the list but are not, and email addresses on the list that are not tied to a user account. This feature can be used to catch unsubscriptions caused by bounces, and other similar issues.

Mailing List Settings

There are several mailing list settings that are configurable. To get to the settings page, go to the admin page, click "User Manager," and then locate "Mailing List Settings" at the top of the page. Add the names of the mailing lists that are associated with your website with the "Add Mailing List" box at the top of the page. Once you have added the mailing lists, the various settings for each mailing list can be changed by clicking toggling the checkbox in their respective columns.

The Options are:

• New Subscription Moderate - When checked, user's submissions to the list will be sent to be moderated before being allowed to post to the entire mailing list.
• Subscription Welcome - When checked, will send a welcome email to a user/member when they subscribe to the list
• Unsubscription Goodbye - When checked, will send a goodbye email to a user/member when they unsubscribe from the list
• Admin Notify Subscription - When checked, will send a notification email to an admin that a user/member has subscribed to the list
• Admin Notify Unsubscription - When checked, will send a notification email to an admin that a user/member has unsubscribed from the list
• Remove - removes the mailing list from the settings table

Emailing Users

To email users, go to <site name>/admin/usermanager/email.cgi enter the subject and message and hit "Send Email." This will email ONLY those users who have opted into admin emails. To send a custom email, add a function to the site's local library that is called "user_manager_email_list" that is formatted similar to the block of code below. Note that the return variables must be in the order they imply, and that $email_template and $subject override whatever is in the inputs on the send page.

Custom User Actions for Admins

It is easy to add actions on the admin usermanager index page. Simply add the map LOCAL_USERMANAGER_CUSTOM_USER_ACTIONS to your site and set it to the name of the function that contains the code that generates the custom links.

Allow Bypassing Re-entry of Password

On sites where it is likely a user may be editing their account many times, LunpaCMS sites can be set to not require users to re-enter their password within an hour of the last time they entered it. Set this by adding or changing the map LOCAL_USERMANAGER_ALLOW_RECENTLY_ENTERED_PASSWORD to 1. When a user edits his or her profile they will have to enter their password the first time and then will not be required to re-enter it for an hour.

Allow Non-Admin Users to Manage Certain Parts of the Site

Certain managers have the ability to allow non-admin users to make changes to the website. For instance, you can allow certain users to add or edit news articles or templates on the site. You can also enforace moderation of changes and additions and set one of the admin accounts on the site to allow or deny content be added.

To add and edit User Levels, go to <Site Name>/admin/usermanager/manage_user_levels.cgi (under Admin > User Manager > Manage User Levels) and enter the name of the user level, the access levels (which managers these users will have access to) and the moderator (if applicable). You can then add users to this level by editing the individual users by adding :::USER_PRIVILEGE_LEVEL::: to the profile form template.

Your site might also require a few new templates in order for pages to display correctly for your editor users. The templates editor_main-begin.template and editor_main-end.template should be added by either copying and modifying the admin main templates or by creating custom pages. Make sure these templates are not marked as admin only or else your editors will not be able to view them.

Snippets of code may be required to be added to your website specificallly for this to work. Specifically, any admin scripts that you want editors to be able to access should change the parameter admin=>1 to editor=>1 in the call to the main function and have all istances of:

  if ($params{'admin'}) {
    &Library_global::enforce_admin($FORM, $Library_global::dbh, failure_redir=>$FORM->{'map_LOCAL_REDIR_ON_ERROR'});
  }

  if ($params{'admin'}) {
    &Library_global::enforce_admin($FORM, $Library_global::dbh, failure_redir=>$FORM->{'map_LOCAL_REDIR_ON_ERROR'});
  } elsif ($params{'editor'}) {
    &Library_global::enforce_privileged($FORM, $Library_global::dbh, failure_redir=>$FORM->{'map_LOCAL_REDIR_ON_ERROR'}, manager=>'newsmanager');
  }