Composr Tutorial: Advanced Composr member system

Written by Chris Graham (ocProducts)
This tutorial will cover some of the more advanced features of the Conversr member system.

Table of contents

  1. Composr Tutorial: Advanced Composr member system
    1. Birthdays
    2. Choosing usergroups when members join
    3. Merging members
    4. Custom profile fields
      1. Limitations (don't go nuts!)
      2. Display rules
      3. Categorisation of CPFs
      4. Special CPFs
      5. Why some CPFs are locked
      6. Encrypted CPFs (advanced)
      7. Statistics
    5. Required fields
    6. Bookmarks
    7. Welcome E-mails
      1. E-mails sent when members are added manually
      2. Referencing member-specific data
    8. Importing/exporting members
      1. Exporting
      2. Loading into spreadsheet software
      3. Importing
        1. Edits
    9. Implicit usergroups and external usergroup listings (advanced)
      1. Limitations and background sync
    10. Forced password resets
    11. See also

Birthdays

Unless disabled, member birthdays will be shown in the main_bottom_bar block (shown at the bottom of the forum, by default).
Additionally, members may choose to receive notifications for their friends birthdays, or the birthdays of all members.

If members have chosen to reveal their age, their age will show, otherwise not.
If members have not selected a date of birth, no birthday can show for them.

Conversr contains a feature to automatically create/link-to a shared birthday topic for a member. By default, this is linked both from main_bottom_bar and the notifications.

The CNS_BIRTHDAY_LINK.tpl template controls how the main_bottom_bar birthday links will be shown.
You can change this to change what link is provided. For example, the Giftr addon replaces the topic link with a link to send an e-gifts.

The notifications are sent using these language strings, defined in the cns language file:

Code (INI)

BIRTHDAY_NOTIFICATION_MAIL_SUBJECT=It's {2}'s birthday
BIRTHDAY_NOTIFICATION_MAIL=It's {{{2}}}'s birthday. Come congratulate them on {1}:\n{4}
 
BIRTHDAY_NOTIFICATION_MAIL takes these parameters:
  1. Your site name
  2. The username of the member whose birthday it is
  3. A URL to the member profile (not used by default)
  4. The URL to create/view the shared birthday topic for the member
  5. A member ID
  6. Base URL

Choosing usergroups when members join

Usergroups have two settings affecting default usergroup memberships for new members:
  1. Initial primary usergroup
  2. Automatic secondary usergroup

If there are 0 usergroups with "Initial primary usergroup", then the hard-coded default usergroup will be entered into for any new member. By default this is the one named 'Newbie' (i.e. the beginning of the rank ladder).
If there is 1 usergroup with "Initial primary usergroup", then this is the default usergroup for new members.
If there are multiple usergroups with "Initial primary usergroup", then the member is given a choice while joining.

Members are automatically put in any usergroup with "Automatic secondary usergroup" enabled, behind-the-scenes.

At the time of writing there is no way to integrate payment directly to the join process. Usergroup subscriptions are entered into after joining.

There is also a usergroup setting, "Open membership", that defines whether members may join a usergroup immediately, i.e. without needing approval from the usergroup leader. This is something members can do after joining, while browsing through the usergroup directory.

Merging members

Image

Merging members

Merging members

(Click to enlarge)

The ability to merge members is only of occasional use, but when you find you do need it, it can be a great help. The usual situation is that one member gets 'bored', feels 'victimized', or wants to go 'undercover' (often, talking with their other account to 'hide the fact'), and creates themselves a second username. This may be a violation of your rules, depending which you have chosen, but is often annoying; it can usually easily be noticed just by seeing that two members have the same personality, spelling and language habits, usage patterns and IP address.

It is worth noting, that you should not be overly suspicious, as members who share some of the listed characteristics, may simply be family members in a household that shares an Internet connection.

The merge member feature will attempt to reassign everything attached (in any way) to the 'from' member to the 'to' member.
It is possible that some reassignments will not be possible, in which case, records may be dropped; for example, if both members share a secondary usergroup, Composr would fail [due to database key constraints] to assign both membership records to the same user, and hence drop one of them. You do not need to worry as this is handled automatically.

Custom profile fields

Image

Custom profile fields are edited by editing member profiles.

Side note: If you (as staff) edit the profile of another member then none of the CPFs will be set as required regardless of how they are configured, as the assumption is that you should not have to fill in unknown fields of a member that you are editing.

Custom profile fields are edited by editing member profiles.<br /><br />Side note: If you (as staff) edit the profile of another member then none of the CPFs will be set as required regardless of how they are configured, as the assumption is that you should not have to fill in unknown fields of a member that you are editing.

(Click to enlarge)

Image

Custom profile fields are optionally shown where members post

Custom profile fields are optionally shown where members post

(Click to enlarge)

Image

Custom profile fields are all shown in member profiles (those that the viewer has permission to view)

Custom profile fields are all shown in member profiles (those that the viewer has permission to view)

(Click to enlarge)

Image

Adding a custom profile field

Adding a custom profile field

(Click to enlarge)

The 'Custom Profile Fields' allow you to create new data fields to attach to member profiles. By default, an 'About me' field is included, and a number of hidden/locked/non-editable fields that store details relating to point counts, and staff-membership and role. A 'locked' custom profile field can not be edited or deleted.

You can manage Custom Profile Fields from: Admin Zone > Tools > Members > Custom Profile Fields.
You can delete a Custom Profile Field from the bottom of its edit form.

There are a number of custom profile field options that you may set that allow CPFs to function for a number of different purposes, including:
  • Storing hidden details on member (for example, a list of rule infractions, such as to aid decisions on cumulative punishment)
  • Allowing members to specify details about themselves (for example, their occupation)
  • Forcing members to specify certain additional details (for example, on a forum for staff of a company, you could make members enter their job role, so as to reduce the chance of a non-employee from joining and remaining an active member)
  • Allowing members of a certain sub-communities (via their usergroup) to specify details appropriate to that sub-community (for example, those in the 'Football' usergroup of a school discussion forum could specify the position they play, while those in the 'Music' usergroup could specify the instrument they play).

For details about the actual field types you can use, see the Custom fields tutorial.

Limitations (don't go nuts!)

If you have more than 60 textual CPFs (except Comcode ones), any ones created after the 60th will not be included for searching on the search module's member search form. This is due to a limitation in MySQL.

Additionally, you could run into problems with large numbers of CPFs on some servers. Some servers limit the number of request variables, either using a PHP setting, the unofficial Suhosin addon, or through other means that may not even be visible. If you notice field values disappearing, or WYSIWYG-edited fields showing in raw HTML after editing, it is likely caused by a server limitation.

Display rules

It is possible to configure where a value for a custom profile field for members will be displayed. The field will always be visible from their profile screen, but also:
  • if 'show in posts' is selected, it will also be visible on their forum posts, and their member galleries and member gallery images/videos
  • if 'show in post previews' is selected, it will also be visible when displaying a member sub-gallery in a list of sub-galleries

In more detail:
PROFILE FIELD SETTINGSSHOWS IN FOLLOWING CIRCUMSTANCES
Owner viewableOwner settablePublicly viewableRequiredJoinAdmin add memberEdit own profileEdit others profileEdit others profile but has 'View any field' permissionView own profileView others profileView own or others profile but has 'View any field' permissionMember searchable

N

N

N

N

 

N

Y

N

N

Y

N

N

Y

N

N

N

N

Y

 

Y

Y

N

N

Y

N

N

Y

N

N

N

Y

N

 

N

Y

N

Y

Y

N

Y

Y

N

N

N

Y

Y

 

Y

Y

N

Y

Y

N

Y

Y

N

N

Y

N

N

 

N

Y

N

N

Y

N

N

Y

N

N

Y

N

Y

 

Y

Y

N

N

Y

N

N

Y

N

N

Y

Y

N

 

N

Y

N

Y

Y

N

Y

Y

N

N

Y

Y

Y

 

Y

Y

N

Y

Y

N

Y

Y

N

Y

N

N

N

 

N

Y

N

N

Y

Y

N

Y

N

Y

N

N

Y

 

Y

Y

N

N

Y

Y

N

Y

N

Y

N

Y

N

 

N

Y

N

Y

Y

Y

Y

Y

N

Y

N

Y

Y

 

Y

Y

N

Y

Y

Y

Y

Y

N

Y

Y

N

N

 

N

Y

Y

N

Y

Y

N

Y

Y

Y

Y

N

Y

 

Y

Y

Y

N

Y

Y

N

Y

Y

Y

Y

Y

N

 

N

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

 

Y

Y

Y

Y

Y

Y

Y

Y

Y



There is also 'Privacy' sub-tab in the account settings that allows members to limit access beyond this. Members may choose to display fields:
  • Not at all
  • To members
  • To friends
  • To certain usergroups
  • To everyone

(Side-note: If there are more than 15 CPFs their privacy settings will only give them options for the CPFs they have filled in.)

Categorisation of CPFs

If you prefix CPF names like "Example: Field A" and "Example: Field B", Composr will be smart enough to treat this as a categorisation and display the join/edit-profile forms in a more appropriate way.

Special CPFs

Composr may install a number of special CPFs used for keeping hold of standardised user data. Composr's core set of profile settings is intentionally kept very narrow, and the special CPFs extend it, even for some core data. This both keeps our system lightweight, and also serves as a mechanism for us to store core data in third party forums.

To avoid user-interface-bloat, we automatically hide some of the special fields, if they are not currently in use. Typically this is when no addon needing them is installed.

Special CPFs include:
  • CPFs for tracking different sources of points (for example, how many ratings the member has made)
  • CPFs for holding address details (used by the shopping addon, passed through to PayPal, for example)
  • CPFs for holding payment details (if local payment is enabled, which is not a default-supported option by any bundled payment gateway, and should only be developed by programmers with a strong understanding of security and who will customise payment flow code as required)
  • CPFs for storing a list of what sites a member of staff is staff on (used if a multi-site-network has been configured)

All these CPFs may be edited just like any other CPF – as long as they are currently active (see above). One exception is the CPF title, which has to be edited via language string editing rather than on the CPF editing form.

By default the values of the CPFs are not publicly viewable.

Why some CPFs are locked

Some CPFS are only activated by certain addons. They are preinstalled as they may be shared between addons, yet may not be used by any. They show so you can know they are there, but are no made available for use to reduce feature-bloat. If no addons currently use them, they show in the list as unused and inaccessible. If you want them, you can install an addon that uses them, or simply add your own alternative CPF. The ecommerce addon uses quite a few.

Encrypted CPFs (advanced)

When creating a custom profile field, it is possible to mark it as encrypted inside the database. If you have the OpenSSL PHP extension installed and configured (see the Webhosting for Composr tutorial), Composr can automatically encrypt the contents of such CPFs, such that their sensitive data would not be revealed if the server were to be compromised.

To mark a CPF as encrypted, tick the "Encryption" box when creating the field, making sure to first have encryption set up on your server and on Composr.

When editing the value of an encrypted CPF, the encrypted data will be shown. To change the value, simply overwrite it with the data you want to change it to. Leaving the value alone will not cause it to be doubly-encrypted so don't worry.

When viewing an encrypted CPF on a member's profile screen, the encrypted data will not be decrypted or shown (the server literally does not know how). To decrypt and view the data, click the "Decrypt" JavaScript link for the CPF. A popup will allow the decryption passphrase to be entered and the data decrypted. The decryption passphrase is the passphrase used to unlock the private key, as specified when originally generating the public/private key pair. Typically only staff will have knowledge of the passphrase, since there's only one for the entire site.

Note that encrypted CPFs are not supported for any kind of CPF value that is not typed in (such as list selections).

Statistics

You can find a break-down of how CPFs were filled in from:
Admin Zone > Audit > Custom Profile Field statistics

Required fields

The following fields usually need filling in:
  • E-mail address
  • Date of birth
  • Any custom profile field set to required

However, there are a selection of privileges to soften this a bit. There are 3 common scenarios that show why we might want to soften the requirements:
  1. A staff-member adding an account on someone else's behalf, and not knowing the full details
  2. (Similar to the above) Members were mass-imported but with partial details, and you don't want staff doing editing of those accounts to have to fill things in
  3. A field was enabled or set to required after members joined, and you don't want to force them to fill it in next time they go to edit their account for some other purpose (potentially annoying!)

The privileges are:
  • Bypass filling-in required custom profile fields
  • Bypass filling-in required custom profile fields on existing accounts
  • Bypass filling-in e-mail address account options
  • Bypass filling-in e-mail address account options on existing accounts
  • Bypass filling-in date of birth account options
  • Bypass filling-in date of birth account options on existing accounts

Note that there are effectively two sets of privileges:
  1. Wholesale bypass of requirement (e.g. Bypass filling-in required custom profile fields)
  2. Bypass of requirement on existing accounts (e.g. Bypass filling-in required custom profile fields on existing accounts)

The wholesale bypass would typically be granted to staff and mainly exists for scenario 1. If lets staff add new accounts without having to fill everything in that would usually be required. It also is useful to generally remove the required-field status for date of birth and/or e-mail address fields (CPFs have individual required statuses so it is less useful for those).
The privilege on existing accounts is a weaker privilege that cover scenarios 2 and 3 well. They mean that if someone is editing an account (their own or someone else's) and the field is currently blank, they don't have to fill it in. However, if the field is already filled in then they will not be allowed to blank it out.

Note that there is an option "Take date of births". If that is disabled then date of birth fields will be completely disabled, and hence the above date of birth privileges won't have any effect. We allow date of birth to be either enabled or disabled because on some sites it would not be an appropriate thing to ask about. If date of birth is enabled but not required then the field will be titled as "Birthday" to indicate the lowered formality.

Bookmarks

Image

The bookmarks popup

The bookmarks popup

(Click to enlarge)

Image

Managing bookmarks

Managing bookmarks

(Click to enlarge)

If members are logged in then they may bookmark pages of your website within the site itself. The icon to do this is at the bottom of every Composr page unless the bookmarks addon has been installed, or it has been removed from GLOBAL_HTML_WRAP.tpl.

The bookmark feature is particularly useful for:
  • members who want to keep bookmarks for different websites separate
  • members who move between computers

Welcome E-mails

Image

Creating a welcome e-mail

Creating a welcome e-mail

(Click to enlarge)

Composr provides special support for composing a series of welcome e-mails that are sent out to new members on a predefined schedule.

Set these up at:
Admin Zone > Tools > Welcome E-mails

You can delete a Welcome E-mail from the bottom of its edit form.

The purpose of this feature is to gradually advertise the features of your website to your members in a way that reinforces awareness. As most members will not usually return to a website, welcome e-mails provide a strong tool to keep them aware and entice them to fully embrace whatever service you are providing.

For welcome e-mails to work the CRON bridge scheduler must be configured as discussed in the Configuration tutorial

Welcome e-mails will only be sent to validated members who have confirmed their e-mail address. E-mails are sent out based on join time, so if a member is not fully validated in time a welcome e-mail may simply never happen.
The one exception is welcome e-mails set to send immediately (i.e. as zero hours). In such a case Composr will assume that validation may not have had time to happen yet, so it will ignore it.
If you know validation may take a while, make sure any non-immediate welcome e-mail is going to happen after you can assume validation will have been handled.

E-mails sent when members are added manually

A very similar feature to welcome e-mails is the ability to send an e-mail when you manually add a new member. There are fields on the "Add member account" form to accommodate this.
The only differences between this and having a welcome e-mail set to send at zero hours, are:
  1. It is only sent to manually added members
  2. It does not require the system scheduler to be configured
  3. It sends immediately (not after a few minutes when the scheduler kicks in and anything ahead in the e-mail queue catches clears)
  4. You can reference the user's new password (explained in the section below)

Referencing member-specific data

As long as you have the newsletters addon installed, welcome e-mails will piggy-back off the newsletters templating code (regardless of whether the welcome e-mail is being sent to members or to a newsletter). This functionality is as described in the Newsletters tutorial ("Templated newsletters"); essentially it means you can use things like {name} in there.

For the e-mail sent from the "Add member account" form, an additional {password} reference is supported. This references the password entered on the form. It is not available in welcome e-mails because it is saved into the database in a hash-format which cannot be converted back to the original password: an important and standard security practice.

Importing/exporting members

Image

Importing members from a CSV file

Importing members from a CSV file

(Click to enlarge)

You can use CSV files to put member data into your website, or to export it. There are many different reasons you might want to do this, but in simple terms, organisations often need to shuffle member data between different systems and this is a good/normal way to do it.

Exporting

This is very easy. Just go to…
Admin Zone > Tools > Members > Download member spreadsheet (CSV)

There are a number of advanced filtering options you can use. Programmers can extend the export system to include "presets" for these options.

The non-bundled excel_support addon allows you to add XLS export support.

Loading into spreadsheet software

Composr will correctly include all data in a robust way, however spreadsheet packages may default some imported cells as numeric, which will not have any representation for leading zeros.
Fortunately this can be worked around.

For Excel (tested on Excel 2011 for Mac)…
  1. Start a new workbook (i.e. a new file)
  2. From the "File" menu, choose "Import".
  3. Choose "CSV File", click "Import".
  4. Select the file from your computer, click "Get Data".
  5. You will then be presented with the Text Import Wizard. Leave all settings on Step 1 alone, click "Next".
  6. On Step 2 choose only the "Comma" delimiter, and leave the other settings alone, click "Next".
  7. On Step 3, select all cells by holding shift and clicking the far-most right one (so they all go black); then select "Text" as the "Column data format"; then click "Finish".
  8. On the "Import Data" dialog that comes up just click "OK".
  9. (Your data should now be imported properly)

For OpenOffice…
Load as normal, but check the "Quoted field as text" checkbox.

Additionally, Excel has a 32KB limit on fields, so may truncate fields, possibly with some kind of error message (such as saying a repair is needed). Avoid embedding raw image data directly into CPFs: use proper attachments or image URLs.

Importing

Follow this process to do an import:
  1. To know the format to import with, it's best to do an export first to get a conclusive input template. So, export your existing members (Admin Zone > Tools > Members > Download member spreadsheet (CSV))
  2. Open the spreadsheet in some spreadsheet software (something like Microsoft Excel or LibreOffice)
  3. Blank out the existing rows in the spreadsheet (except the header row of course)
  4. Fill in new rows, as required
  5. Save back to a .csv file (.xls or .xlsx files are not supported). Make sure that it is a true CSV file (i.e. comma-delimiters between fields, not tab-delimiters or semi-colon delimiters). Opening it in something like Windows Notepad is a good way to confirm this.
  6. Take a full database backup (you can never be too careful, a small typo such as a corruption of the header row, or a regular error in the new user rows, could result in proliferate errors after import)
  7. Import (Admin Zone > Tools > Members > Import member spreadsheet (CSV)). You'll be asked to upload the CSV file and optionally to give a default password. Click the button to run the import.

Further notes follow…

There is full support for auto-creation of usergroups and custom profile fields as required to get the data imported.
i.e. Any column that does not correspond to an existing field will result in a new field being auto-created. Any referenced usergroup that does not correspond to an existing usergroup will result in the usergroup being auto-created.
The importer will tell you when it does this.

Note that Composr will make reasonable/consistent choices if columns are missing or cells are left blank. A missing column implies the default value of a field will be used. A blank field implies blank (or the closest equivalent for that field type) should be used.

Usergroups are referred to by name. You can put multiple usergroups in the usergroup column, separated by "/" (no spaces around this). The first usergroup provided is considered the primary usergroup. For example "A/B" puts someone in the usergroups named "A" and "B".

Passwords may be given in raw text, for the specific new password. If there is " / " in there, it is used to encode the hashed version of the password. This may confuse you a bit when looking at exported data, but don't worry, normal passwords written in there will transfer over correctly (you're not allowed to use a " / " in a password though, due to the previous encoding scheme). If no password is given, the default will be used (which you pick just before you start the import) – if no default was given, blank will be used, so be careful.

Boolean fields (true/false) are assumed false unless one of the following case-insensitive values is given: YES, 1, Y, ON.

If you're importing huge quantities of data

The import process disables normal PHP memory and time limits, however some webhosts may put in restrictions regardless. If you come against problems you may need to limit import batches to a few thousand records per attempt, or temporarily copy your site to a more reliable host (such as your own development machine), then copy the database back across to the live host.


Note that these instructions are based on using an export as a template. We do try and support de-facto standards for laying out basic fields such as Username and Password fields (with a variation of different spellings/abbreviation/synonyms/data-formats), but the template method is the best way because it is more predictable for you.

Edits

If a row in the spreadsheet represents an existing member rather than a new member, then we have to handle this as an edit rather than as an add.

All default parts of the Composr member record will be replaced. If certain Composr member record fields are not supplied, those will go to the Composr default.
Password is the one exception. If no new password, or hash, is supplied, then the old password remains. That's treated separately as the raw passwords are not saved within Composr, and hashes may not be understood or confidential, so to support reimporting exported records cleanly without the old passwords getting lost we need to be able to skip changing them.
Custom profile fields get individually saved, so any missing custom profile field in the import will not result in that field getting reset to the default.

Implicit usergroups and external usergroup listings (advanced)

Composr has support for 'implicit usergroups' which are usergroup memberships defined by custom code written by programmers, and getting usergroup membership from LDAP. It is useful for using permissions for handling special circumstances. For example, a programmer could create an implicit usergroup for under 18's and remove the bypass-wordfilter permission for that usergroup.

Limitations and background sync

Usually when Composr handles checks of when someone is in a usergroup it goes through some fool-proof methods to do it by looking at just that particular user. Sometimes Composr needs to efficiently find all members in a usergroup, and bypasses checking implicit groups and LDAP for performance/simplicity.
To mitigate this, Composr has a CRON hook (CRON bridge scheduler task) that is disabled by default that can be turned on by an Commandr command to synchronise implicit usergroups as normal usergroup memberships. To turn that on:

Code

:set_value('implicit_usergroup_sync','1');
If this is set then anyone put into the usergroup manually that does not match the implicit usergroup check would end up being removed again.

If synching is not enabled, or group memberships come from LDAP, then the following things will not work as expected when it comes to them:
  • member search by usergroup
  • birthdays RSS feed filtering by usergroup
  • sending a newsletter to a usergroup
  • implicit memberships are not shown in exported CSV files
  • copying members from one usergroup to another
  • various areas of code that list all staff or super-members
  • signing up everyone in a usergroup for calendar event reminders
  • showing how many members there are in a usergroup
  • listing usergroup memberships when viewing a usergroup

Forced password resets

You can force a member to change their password upon next login (e.g. if you want to promote increased security for some reason), via this Commandr command:

Code (Bash)

echo temporary > /members/bob/m_password_compat_scheme
 
(this assumes you are doing it for a member, bob).
You can also run SQL queries. To force all members to change their passwords:

Code (SQL)

UPDATE cms_f_members SET m_password_compat_scheme='temporary' WHERE m_password_compat_scheme=''
 

See also


Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.