Login Welcome to LeeGarner.com
Friday, August 01 2014 @ 02:48 AM PDT
 

glProfile - Custom Profiles

The Custom Profile plugin for glFusion allows the administrator to create custom profile elements for user acccounts. Prevously, this required significant cusom programming and template modification.

Although some templates still need to be customized, and a few functions added to lib-custom.php, this only needs to be done once. After the initial setup, custom fields can be created and removed at will with no further site customization and no database modifications.

Features

  • Administrators can create, modify and delete profile elements easily.
    • Text fields
    • Radio buttons
    • Checkboxes
    • Dropdown selections
    • Date fields, with a javascript date picker and administrator-defined formats
  • Elements may optionally be:
    • shown on the signup form.
    • hidden or made read-only to users, by using the Owner permission.
    • required entries (will automatically appear on the registration form)
    • disabled and enabled.
    • automatically generated according to admin supplied custom functions (0.0.3)

Requirements

  • glFusion v1.2.0 or newer.

Installation

The Profile Plugin uses the glFusion automated plugin installer. Simply upload the distribtuion using the glFusion plugin installer located in the Plugin Administration page.

The manual plugin installation method is also supported.

Fields and Features

Field Permissions

Field permissions indicate whether a given field and its data are visible when the user's profile is viewed. (NOTE: these permission settings do not affect whether a field is shown in a member listing. See below.)

Starting with version 1.1.0, the “read-only” setting has been removed and the Owner permission is used to control visibility. To restrict access by a user to their own profile data, set the owner's permission accordngly:

  • Read/Edit : Normal, a user can view and update the field in their own profile.
  • Read : The user can view, but not update the field data.
  • None : The field is invisible to the user and cannot be viewed or updated.

A user with the profile.admin or profile.manage right can always update their own and other users' profiles, including read-only or hidden fields.

The Group permission is only to determine visibility; the Edit permission is not used here. The Member and Anonymous “Read” permission is used normally.

System Fields (1.1.0)

Some fields are designated as “System” fields and cannot be deleted, but may be disabled if not needed. These fields exist to accommodate other functions that rely on them, including other plugins. The current system fields are:

  • sys_directory : Allows users to decide whether their profile information will be included in the member lists. If this field is disabled, then all members are listed.
  • sys_membertype : A text field to indicate the type of member. Used by the Subscription plugin 1.0.0 or later.
  • sys_expires : A date field to indicate the membership expiration. Used by the Subscription plugin 1.0.0. or later.

Auto-Generating Fields

Fields may be set to auto-generate their values, which may be useful for creating membership IDs or other data. The default function uses COM_makeSid(), which creates the same type of string that's used for article ID values.

You can create your own custom function to generate values which can affect one or all auto-generating fields. To affect only one field, name your function “CUSTOM_profile_autogen_fieldname. If this function is not found, but one named simply “CUSTOM_profile_autogen” is, then that will be used instead.

This function takes two arguments: an array containing the field definition and value data, and the user ID. For example:

/**
*   Generate content for a specific field.
*   This function generates a string for a field named "state".
*   The function should be named "CUSTOM_profile_autogen_{fieldname}
*
*   @return string  Field Content
*/
function CUSTOM_profile_autogen_state($A, $uid=0)
{
    return 'CA';
}

The second approach is to create a more general CUSTOM_profile_autogen() function. This function must accept two arguments: the field name and the field type. Based on those two elements you can decide which values to return.

For example:

/**
*   Generate content for any field.
*   This function handles all field names and types, and it completely
*   overrides the default PRF_autogen() function (which is to return
*   COM_makeSID()).
*
*   @param  array   $A      Field definition and value
*   @param  integer $uid    Optional user ID, current user by default
*   @return string          Field Content
*/
function CUSTOM_profile_autogen($A, $uid=0)
{
  switch ($A['name']) {
      case 'membershipid':
          // Generate a random Membership ID
          return 'member' . rand(1,99);
          break;
  }

  switch ($A['type']) {
      case 'text':
          // Return a static text value
          return "I'm a text field";
          break;
      case 'date':
          // Return a static date value
          return '07/04/1776';
          break;
  }
}

The plugin looks for those two functions, in order, and uses the first one that exists. If neither function is available, the plugin calls COM_makesid() to create a random ID. Data validation in the CUSTOM_ functions is left to the function writer.

Member Lists (1.1.0)

Membership lists can be created for viewing by administrators or regular site members. When creating a list, remember that the permissions of the individual fields are not used. Each list has its own permission setting to restrict viewing to a group, all logged-in users, or anonymous users. Fields which are hidden from the profile display can still be viewed in a list.

If the sys_directory field is enabled, then members can choose to exclude themselves from the membership lists. For normal viewers, users who have checked this field will not be displayed in the member lists. However, the Profile Admin group has a special permission: profile.viewall. This permission allows profile administrators to view all members even if they have elected to be hidden. This right may be granted to other groups, such as board members or membership managers.

Be sure to keep these issues in mind as you create membership lists. You don't want to violate your members' trust.

Upgrading

The upgrade process is identical to the installation process, simply upload the distribution from the Plugin Administration page.

Administration

Administrator access is via the “Custom Profile” administrator menu option, or the corresponding icon in Command and Control. The first thing that you'll see is the list of currently defined fields:

Custom Profile List

The plugin installs several fields by default to use as examples. They may be renamed or deleted as you see fit.

The fields have the following functions:

Field/Icon
PencilOpens the editing form for the field
Red “X”Deletes the field. Automatically deletes all data items from user accounts that belong to this field. You will be prompted to confirm the deletion.
Blue ArrowsAllow you to quickly redorder the fields. The order in which they are displayed in this list is the order in which they will appear on forms and display areas.
EnabledIndicates whether the field is in use. If this is not checked, the field will not appear on any forms or displays, regardless of other settings.
RequiredIndicates that the field is required. The fValidator class is used on the entry forms to prevent users from bypassing the field if this is checked. Implies “Registration”.
RegistrationIndicates whether the field will appear on the signup form, or only in Account Settings. Implied by “Required”.
Read OnlyIndicates that regular users cannot modify the field contents. Only users with the profile.admin privilege can edit these fields. Overrides “Registration”, preventing fields from appearing on the signup form (since users can't edit the data).
Auto-GenerateIndicate whether the field data should be automatically generated. Currently this is only supported during registration.

Editing Fields

When you click the pencil icon in the profile list, you'll be presented with the field edit form. Note that the available elements, and their meanings, will change depending upon what field type you select in the dropdown.

Custom Field Edit Form

FieldFunction
Field NameThis indicates the field name that will be used to identify the custom field. This must be unique and should not contain spaces or other special characters.
Text PromptThis is the string that will appear next to the field on forms, just like the prompts on this form.
Field TypeHere you can select the type of field. Your options are:
Text - Simple text field
Dropdown - Select from a list of values
Radio Buttons - Select one from among a few values
Checkbox - Either true or false
Value(Dropdown, Radio Buttons) Enter the options in the form of “value:text;value:text;”. The text will be displayed on the forms and the value will be stored. If you modify the text for a given value, that text will be used for existing user data. If you remove or modify the value for an option, the user data will not be changed and unpredictable results may occur.
Input Field Length(Text) Enter the displayed length for the text field. This value will become the “size” parameter.
Maximum Entry Length(Text) Enter the maximum size for the text field. This will become the “maxlength” parameter.
Default Value(Any) Enter the value to be used as the default for new entries. For Dropdown and Radio Button types, this should correspond to one of the “value” arguments in the Value field. For Checkboxes, this should be either “1” for checked or “0” for unchecked. For Text and Date fields, this is simply the text that will be entered by default.
Show Time?(Date) Indicates whether the time will be an option in the date picker. This does not affect the display; see “Format” for that.
12 or 24 hour format?(Date) Indicates whether the date picker uses 12- or 24-hour format. See the “Format” field for the actual display format.
Format(Date) This is the display format for date fields, such as ”%Y-%m-%d” for YYYY-MM-DD. Refer to the PHP date() function for more information.
EnabledIndicates that the field will appear on forms.
RequiredIndicates that the field is a required entry. Implies “Enter at Registration”.
Enter at RegistrationIndicates that the field will appear on the site signup form. Implied by “Required”, Overridden by “Read Only”.
Read OnlyIndicates that only administrators can change the field value.
Position AfterSelect the field after which the current one should be displayed. This allows you to reorder fields.

Using the Data

After you've created your custom fields and you or your site members have entered information into them, how can you access it? There are a few ways:

This area is just beginning to be created, and is subject to change

Variables in the $_USER array

All custom fields are set into the global $_USER array for the current user. The field names are prepended with “c_” (for “custom”) to help avoid possible name collisions as fields may be added to the glFusion core in the future.

For example, a field indicating a user's favorite color, called “favcolor” would be set as $_USER['c_favcolor']. The string value is placed into $_USER, not the value. Therefore, $_USER['c_favcolor'] might contain “Blue”, not “2”.

The PRF_getValue() function

Custom variables can also be retrieved by calling PRF_getValue and passing to it the name of the value desired and an optional user ID. This is a bit more robust, but requires some coding. You should also check that the function exists before attempting to use it, or you might encounter a fatal PHP error.

if (function_exists('PRF_getValue')) {         // indicates that the Profile plugin is available
    list($value, $text) = PRF_getValue('favcolor');
} else {
    list($value, $text) = array(0, 'undefined');
}

PRF_getValue accepts one or two arguments. The first is required and is the name of the variable to retrieve. The second is optional and is the user ID to whom the data belongs. If the second argument is omitted, the current user ID is used. If an invalid field name is submitted, or no data is available, then the array elements will be empty.

The return value from PRF_getValue is an array containing two elements: the value of the variable, and the text representation of the value. For example, calling

PRF_getValue('favcolor', 3)

would return

array('2', 'Blue')

(For Text and Date fields, the value and the value string are equal.)

Autotags

The Profile plugin supports autotags for retrieving field values or user lists into static pages or other parts of glFusion.

profile Autotag

Using the previous example of obtaining the user's favorite color, simply place an autotag into your text like so:

[profile:favcolor {options}]

The {options} consist of Name:Value pairs to indicate what should be shown and how. The available options are currently:

NameDescription
uidUser ID to use. The current user ID is used by default.
caseThe case to use for the text. Possible values are “u” and “l” to have the text shown in upper- and lower-case, respectively.
valueTells the plugin to return the actual value, rather than the text, for the field. This option is used alone, no parameters

Assume that the default supplied 'favcolor' field is used. The possible values are 1=“Red”, 2=“Blue”, and 3=“Yellow”. Assume also that the value for user 3 (the currently-logged-in user) is 1 and for user 4 it is 2.

TagReturnsNotes
[profile:favcolor]RedThe textual value for the current user is the default
[profile:favcolor uid:4|Blue|Gets the text value for the requested user ID| |[profile:favcolor case:u uid:3]REDReturns the text value as upper case
[profile:favcolor value]1Gets the numeric value, not the text, for the current user

profile_list Autotag

The [profile_list] autotag allows you to embed a user list into a static page or other content. This tag requires one parameter, the list ID which matches the string identifier of the list. Optional parameters are:

extrasActivates the “extras” in the list, including the search form and results limit.
menuShows the tabbed menu of available lists. Clicking on a menu item redirects the visitor to the main lists page.
exportShows the “Export to CSV” link, if the current user is a member of the export group.

Examples:

[profile_list:email]Displays the member list named “email”, without headers or menus
[profile_list:email extras]Displays the same list, and adds the search box at the top
[profile_list:phone menu export]Displays the “phone” list, with a menu of all available lists and the “Export to CSV” link.

Known Issues

Version 0.0.1

  • Setting a field as “required” does not affect the Account Settings or user edit forms. Only the registration form properly handles the javascript for this case.
  • In version 0.0.1, the sample CUSTOM_userEdit function doesn't check if the plugin is enabled. Replace with this
    function CUSTOM_userEdit($uid)
    {
        global $_USER;
     
        // glFusion 1.1.5 and higher have a different method for the
        // "Account Settings" screen
        if (GVERSION >= '1.1.5' && $uid == $_USER['uid']) {
            return '';
        }
     
        if (function_exists('USES_profile_functions')) {
            USES_profile_functions();
            return PRF_editForm('edit', $uid);
        } else {
            return '';
        }
    }

    Fixed in SVN commit 26

Version 1.0.0

  • Non-english language files aren't selected correctly. Download and unzip this new functions.inc file into your plugins/profile directory to fix the issue. This has been fixed in SVN.
  • Checkbox values aren't recorded correctly since standardizing on “1” and “0” instead of user-supplied values. Download and unzip this new profile_functions.inc.php file into your plugins/profile directory to fix the issue. This has been fixed in SVN.
  • Read-only fields are reset when a regular user saves their profile. The disabled fields don't come through the form and thus are reset to empty values. Download and unzip this new profile_functions.inc.php file (updated to cover the above issue as well) into your plugins/profile directory to fix the issue. This has been fixed in SVN.

Changes in upcoming version 1.1.0

Version 1.1.0 represents a major shift in how data is stored and retrieved. Previously, each profile data item was kept in a simple 3-field record: user ID, field name, field value. This was very flexible when adding or changing field types, but didn't allow for the best integration with glFusion. Creating custom member lists, for example, was difficult.

Beginning in 1.1.0, each profile record is a single record keyed by the user ID. When fields are added or changed, the schema of the profile_data table is updated accordingly. This allows for better searching and sorting since it's now a simple, single join instead of multiple records to read for each user.

Since each database field is named for the field, the field names need to be sanitized and database-safe. They are converted to lower-case, have any non-alphanumeric characters removed, and are prefaced by 'prf_' to indicate that they are profile fields. (see “System Fields” below)

Owner's Permissions

The Owner Permission field is now fully utilized to control which fields a user can view or edit within their own profile. The “read-only” flag has been removed, and fields can now be made read-only or hidden by changing the owner's permission.

Field Indicators

When the profile form is presented, either at user registration or when accessing Account Settings, each field now indicates whether it is required, whether it is visible in the public profile, and whether there is help text associated with it. For the last option, a short text message can be provided to the field which will appear when the mouse hovers over the Information icon.

For field visibility, “publically-visible” means that either Members or Anonymous have read access to the field. If not,the field is deemed non-public.

System Fields

Several fields have been added which are required and cannot be modified. These are the “system” fields and include: membership expiration, membership type, and a checkbox indicating that the user wishes their profile to be visible in the member lists.

The point of these fields is that they are referenced elsewhere in the plugin and therefore must be present. Some modification may be done, for instance, changing the expiration date from 12- to 24-hour time. Major changes, such as deleting the field or changing the type, are not allowed. If not used, these fields can be disabled.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Copyright (C) 2009-2011 by Lee Garner

glfusion/glprofile/start.txt · Last modified: 2011/07/19 23:02 by lee
 
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3

Random Image

 
 
You can't see me.
Browse Album

My Account






Lost your password?